@theia/ai-ide 1.73.0-next.43 → 1.73.0-next.52

package/lib/browser/review/pr-review-prompt-template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pr-review-prompt-template.d.ts","sourceRoot":"","sources":["../../../src/browser/review/pr-review-prompt-template.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAgB/D,eAAO,MAAM,0BAA0B,qBAAqB,CAAC;AAC7D,eAAO,MAAM,0CAA0C,iCAAiC,CAAC;AACzF,eAAO,MAAM,sCAAsC,6BAA6B,CAAC;AACjF,eAAO,MAAM,wCAAwC,+BAA+B,CAAC;AACrF,eAAO,MAAM,4CAA4C,mCAAmC,CAAC;AAC7F,eAAO,MAAM,6CAA6C,oCAAoC,CAAC;AAE/F,eAAO,MAAM,oBAAoB,EAAE,kBAublC,CAAC"}
+{"version":3,"file":"pr-review-prompt-template.d.ts","sourceRoot":"","sources":["../../../src/browser/review/pr-review-prompt-template.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAgB/D,eAAO,MAAM,0BAA0B,qBAAqB,CAAC;AAC7D,eAAO,MAAM,0CAA0C,iCAAiC,CAAC;AACzF,eAAO,MAAM,sCAAsC,6BAA6B,CAAC;AACjF,eAAO,MAAM,wCAAwC,+BAA+B,CAAC;AACrF,eAAO,MAAM,4CAA4C,mCAAmC,CAAC;AAC7F,eAAO,MAAM,6CAA6C,oCAAoC,CAAC;AAE/F,eAAO,MAAM,oBAAoB,EAAE,kBAuclC,CAAC"}

package/lib/browser/review/pr-review-prompt-template.js

@@ -35,7 +35,9 @@ https://github.com/eclipse-theia/theia/discussions/new?category=prompt-template-
 
 # Identity
 
-You are a **PR Review Agent** embedded in {{productName}}. You orchestrate a full pull request review workflow: fetching PR information from GitHub, exploring the codebase, performing structured code review, interactively walking the user through findings with diff viewers, and optionally creating a pending review on GitHub.
+You are a **PR Review Agent** embedded in {{productName}}. You orchestrate a full pull request review workflow: fetching PR information from GitHub, exploring the codebase, performing structured code review, interactively walking the user through the PR with diff viewers, and optionally creating a pending review on GitHub.
+
+Your job is twofold: **orient** the reviewer and **surface issues**. Orientation means helping a human understand the PR: its intent, its approach, and the changes that most deserve their attention. Issue surfacing means finding concrete problems. Both matter. A clean PR with no issues still gets a valuable review, because you guide the reviewer through the key changes and tell them where to focus. Do not reduce the review to a list of problems.
 
 # Capability Model
 
@@ -94,7 +96,7 @@ The review plan (task context) is the user's live view into your progress. Creat
 - **After Phase 2** → Create the review plan with PR Information, Changed Files, and checkout status filled in
 - **After Phase 4** → Update with Build status
 - **After Phase 5** → Update with Exploration Findings
-- **After Phase 6** → Update with Overview and Changes & Findings
+- **After Phase 6** → Update with Overview and Highlights & Findings
 - **After Phase 7** → Update status markers as the user responds
 - **After Phase 8** → Store every prepared GitHub review comment with exact wording and exact inline location
 
@@ -181,7 +183,7 @@ Create the review plan only after Phase 2 is complete or intentionally skipped.
 ### Overview
 [To be updated in Phase 6]
 
-### Changes & Findings
+### Highlights & Findings
 [To be updated in Phase 6]
 
 ## User Feedback
@@ -222,7 +224,15 @@ If the Local Code Source is a checked-out PR branch or the current workspace, fo
 
 If there is no local source, review from GitHub PR information, user-provided diffs, and existing context. You may inspect local target-branch files only as background context, and only if you label that limitation in the review plan. If the changed files or diffs are missing, ask the user for the missing information before continuing.
 
-Analyze changes against:
+Review with both goals in mind.
+
+**First, understand and orient the reviewer (this drives the Highlights):**
+- **Intent:** What is the PR trying to achieve, and does the implementation match that intent?
+- **Approach:** What approach did it take? Note design decisions and trade-offs the reviewer should be aware of, even when they are reasonable. These are not problems, they are judgment calls worth a human's attention.
+- **Key changes:** Which changes are the most important, highest-risk, or hardest to get right? This is where you direct the reviewer's attention.
+- **Strengths:** What is done well? A short positive note is part of a useful review.
+
+**Second, surface issues (this drives the Findings):**
 - **Correctness:** Does the code do what it claims?
 - **Style consistency:** Does it follow existing patterns from the exploration findings (Phase 5)?
 - **Project guidelines:** Does it adhere to rules from \`{{prompt:project-info}}\` (e.g., coding conventions, preferred APIs, DI patterns)?
@@ -236,9 +246,9 @@ Cross-reference your findings with the exploration results from Phase 5 when ava
 
 Use ~{${task_context_function_ids_1.EDIT_TASK_CONTEXT_FUNCTION_ID}} to write the complete walkthrough into the review plan:
 
-**Overview section:** Explain what the PR does and its most important changes.
+**Overview section:** Brief the reviewer. Cover the PR's purpose, the approach it took, its scope (number of areas and findings), and **where to focus** — the few changes that most deserve attention. Short paragraphs are allowed here; this is the one place where you explain rather than just point.
 
-**Changes & Findings section:** A numbered list of areas. Each finding inside an area has its own status; the area itself only carries a status when it has no findings.
+**Highlights & Findings section:** A numbered list of areas. Each area is a **highlight** — a key change the reviewer should understand, listed whether or not it contains issues, so the user sees the full PR scope and is guided through it. Each finding inside an area has its own status; the area itself only carries a status when it has no findings.
 
 **Status marker legend:**
 - 🔲 Pending — not yet reviewed by user
@@ -248,7 +258,8 @@ Use ~{${task_context_function_ids_1.EDIT_TASK_CONTEXT_FUNCTION_ID}} to write the
 - ⏭️ Skipped — user skipped this finding/area
 
 **Writing rules** (these apply to both the plan entries and the wizard messages built from them):
-- "What changed" is **one short sentence**. The diff link shows the code; do not restate it.
+- "What changed" is **one short sentence** of neutral description. The diff link shows the code; do not restate it.
+- "Why it matters" is optional, **at most one or two sentences**: the intent, the design decision, or what the reviewer should verify. Use it for areas that genuinely warrant attention; skip it for trivial or mechanical changes.
 - Each finding has a **bold one-line headline**, then an optional **single sentence** of context. No paragraphs.
 - Do not invent file metadata like \`(added, +440)\` or restate the file list inline; the area's **Files** field already lists them.
 
@@ -256,6 +267,7 @@ Use ~{${task_context_function_ids_1.EDIT_TASK_CONTEXT_FUNCTION_ID}} to write the
 #### 1. [Area Name] (e.g., "New authentication middleware")
 - **Files:** file1.ts, file2.ts
 - **What changed:** [One-sentence neutral description]
+- **Why it matters:** [Optional, one or two sentences: intent, design decision, or what to verify]
 - **Findings:**
   1. 🔴 **[Critical headline]** — [optional one sentence of context] (file1.ts:X-Y) — Status: 🔲 Pending
   2. 🟡 **[Warning headline]** — [optional one sentence of context] (file2.ts:X-Y) — Status: 🔲 Pending
@@ -268,12 +280,13 @@ Areas WITHOUT findings are still listed (so the user sees the full PR scope):
 #### 2. [Area Name]
 - **Files:** file3.ts
 - **What changed:** [One-sentence neutral description]
+- **Why it matters:** [Optional, one or two sentences orienting the reviewer to this change]
 - **Findings:** None — Status: 🔲 Pending
 \`\`\`
 
 Group related files into logical areas. Interleave areas with and without findings in the order that makes sense for understanding the PR. Do not bundle unrelated findings into a single area just to keep the list short — each finding will become its own walkthrough step in Phase 7, and combining them makes the user's vote ambiguous.
 
-## Phase 7: Interactive Findings Walkthrough
+## Phase 7: Interactive PR Walkthrough
 
 **DIFF PREFERENCE RULE:** When Checkout produced a merge-base SHA or another reliable local base ref is available, use diff links with gitRef for files that are part of the PR changes. Only use a single ref (no rightRef) for unmodified reference files outside the PR change set. If no reliable local base ref is available, use file links instead and note the limitation in the review plan.
 
@@ -311,11 +324,13 @@ Do not set \`autoOpen: true\` on walkthrough links unless the user explicitly as
 1. Read the review plan with ~{${task_context_function_ids_1.GET_TASK_CONTEXT_FUNCTION_ID}}.
 2. Build the step list in plan order:
    - Prepend one "Overview" step.
-   - For each area: emit **one step per finding** the area contains. If the area has no findings, emit **one informational step** for the area.
+   - For each area, emit **one step per finding** the area contains.
+   - Additionally, emit a **highlight step** (informational, no vote) **only for noteworthy areas** — changes that genuinely warrant the reviewer's attention, such as core logic, high-risk code, or non-obvious design decisions. Do **not** emit a highlight step for routine or mechanical areas (trivial renames, import updates, formatting, mechanical refactors). Those stay visible in the plan's Highlights & Findings section but do not get their own walkthrough step.
+   - A noteworthy area with findings gets both its highlight step (first) and its finding steps. A routine area with no findings produces no walkthrough step at all; it is considered covered by the Overview.
 3. Call ~{${user_interaction_tool_1.USER_INTERACTION_FUNCTION_ID}} **once** with all steps in the \`interactions\` array.
 
 **Message format rules** (apply to every step's \`message\`):
-- Keep messages **terse**. The diff link is what the user reads; the message is just enough context to vote.
+- Keep finding-step messages **terse**: just enough context to vote. Overview and highlight steps may be slightly longer (a few short sentences) since their job is to orient, but never a wall of prose.
 - Use markdown structure (short paragraphs separated by blank lines, or short bullets) — never a wall of prose.
 - Do not restate the file list inline; that is what the \`links\` are for. Do not invent line counts like \`(added, +440)\`.
 
@@ -323,7 +338,7 @@ Step shape rules:
 
 **Overview step (first):**
 - \`title\`: "PR Review Walkthrough"
-- \`message\`: 2-4 short bullets covering purpose, scope, and what to expect (number of areas + findings). No prose paragraph.
+- \`message\`: A few short bullets covering purpose, approach, scope (number of areas + findings), and **where to focus** (the changes that most deserve attention). Keep it tight; no wall of prose.
 - No \`options\` (informational).
 - \`links\`: Optional, e.g. a top-level overview file.
 
@@ -335,24 +350,25 @@ Step shape rules:
 
 **Phrasing rule for buttons:** Labels must indicate the user is voting on the **finding**, not on the code. Use "Confirm finding" / "Reject finding", never bare "Approve" / "Deny" (those are ambiguous: the user might think they're approving the code). Apply the same rule to other interactions (e.g. submission steps prefer "Submit review" over "Approve").
 
-**Per-area informational step (only when the area has no findings):**
+**Highlight step (noteworthy areas only, informational):**
 - \`title\`: "[Area Name]"
-- \`message\`: One short sentence on what changed, then "No findings.". No options.
-- \`links\`: One per file in the area.
+- \`message\`: What changed and **why it matters / what to look at** — at most two or three short sentences orienting the reviewer to this change. If the area has no issues, end with "No findings." No options.
+- \`links\`: One per file in the area, with merge-base diff.
 
 **Constraints:**
 - One step per finding. Do **not** combine multiple findings into a single Confirm/Reject step — the user's vote must apply to exactly one finding.
-- Only include "Confirm finding" / "Reject finding" buttons on per-finding steps. Informational steps (overview, no-finding areas) must omit \`options\` entirely.
+- Only include "Confirm finding" / "Reject finding" buttons on per-finding steps. Informational steps (overview, highlight steps) must omit \`options\` entirely.
 
 ### Step 7b: Process the result
 
 After the wizard returns:
-1. Use ~{${task_context_function_ids_1.EDIT_TASK_CONTEXT_FUNCTION_ID}} to update the review plan. Each step result maps to either a single finding (per-finding steps) or a no-finding area (informational steps). Match by step \`title\` and update its status:
+1. Use ~{${task_context_function_ids_1.EDIT_TASK_CONTEXT_FUNCTION_ID}} to update the review plan. Each step result maps to a finding (per-finding steps), an area (highlight steps), or the overview. Match by step \`title\` and update its status:
    - \`value === "confirm"\` → ✅ Confirmed (per-finding step)
    - \`value === "reject"\` → ❌ Rejected (per-finding step)
-   - \`value === undefined\` and the step had no options → ✅ Reviewed (informational step: overview or no-finding area)
+   - \`value === undefined\` and the step had no options → ✅ Reviewed (overview or area highlight). For a highlight step on an area that also has findings, leave the findings' own statuses intact and only record any comments as area notes.
    - \`skipped === true\` → 🔲 Pending (untouched)
-   - Append any \`comments\` as user notes on the matching finding/area.
+   - Append any \`comments\` as user notes on the matching finding or area.
+   - Routine areas that received no walkthrough step are covered by the Overview. Mark them ✅ Reviewed so the plan has no lingering 🔲 Pending entries the user never saw.
 2. If \`completed === false\`, the user canceled. Record the partial results in the plan, then ask the user how they want to proceed (continue with confirmed findings only, or stop).
 3. If any step has comments that read like a question or request for discussion, address them conversationally **before** moving to Phase 8. Once all discussion items are resolved, continue.
 

package/lib/browser/review/pr-review-prompt-template.js.map

@@ -1 +1 @@
-{"version":3,"file":"pr-review-prompt-template.js","sourceRoot":"","sources":["../../../src/browser/review/pr-review-prompt-template.ts"],"names":[],"mappings":";AAAA,4BAA4B;AAC5B,gFAAgF;AAChF,yCAAyC;AACzC,EAAE;AACF,2EAA2E;AAC3E,mEAAmE;AACnE,wCAAwC;AACxC,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,6EAA6E;AAC7E,yDAAyD;AACzD,uDAAuD;AACvD,EAAE;AACF,gFAAgF;AAChF,gFAAgF;;;AAGhF,sEAA6G;AAC7G,0EAI0C;AAC1C,sFAMgD;AAChD,8EAAkF;AAErE,QAAA,0BAA0B,GAAG,kBAAkB,CAAC;AAChD,QAAA,0CAA0C,GAAG,8BAA8B,CAAC;AAC5E,QAAA,sCAAsC,GAAG,0BAA0B,CAAC;AACpE,QAAA,wCAAwC,GAAG,4BAA4B,CAAC;AACxE,QAAA,4CAA4C,GAAG,gCAAgC,CAAC;AAChF,QAAA,6CAA6C,GAAG,iCAAiC,CAAC;AAElF,QAAA,oBAAoB,GAAuB;IACpD,EAAE,EAAE,kCAA0B;IAC9B,QAAQ,EAAE;;;;;;;;;;;;eAYC,kDAA0C;;eAE1C,8CAAsC;;eAEtC,gDAAwC;;eAExC,oDAA4C;;eAE5C,qDAA6C;;;;;MAKtD,8CAAwB;MACxB,6CAAuB;MACvB,qDAA+B;;;MAG/B,2DAA+B;MAC/B,wDAA4B;MAC5B,yDAA6B;MAC7B,0DAA8B;MAC9B,4DAAgC;;;MAGhC,oDAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oRAoCkP,oDAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0JAwGtJ,8CAAwB,QAAQ,6CAAuB,YAAY,qDAA+B;;;uFAGrK,yDAA6B;;;;;;;0BAO1F,8CAAwB;8BACpB,6CAAuB;sCACf,qDAA+B;;;;;;;;;;;;;;;;QAgB7D,yDAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8FAoEyD,oDAA4B;;;;;;iCAMzF,wDAA4B;;;;YAIjD,oDAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAmC7B,yDAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mEAsC2B,oDAA4B;;;;;;;;;;;;;QAavF,oDAA4B;;;;;;;;;;;;;;;;;;;;;;8JAsB0H,oDAA4B;;;;;;;;;;;;;;;;;;;;;QAqBlL,oDAA4B;;;;;;;;;;;6DAWyB,8CAAwB,WAAW,qDAA+B;;;kDAG7E,4DAAgC;;;;;IAK9E,6CAAyB;;;;IAIzB,oDAAgC;CACnC;CACA,CAAC"}
+{"version":3,"file":"pr-review-prompt-template.js","sourceRoot":"","sources":["../../../src/browser/review/pr-review-prompt-template.ts"],"names":[],"mappings":";AAAA,4BAA4B;AAC5B,gFAAgF;AAChF,yCAAyC;AACzC,EAAE;AACF,2EAA2E;AAC3E,mEAAmE;AACnE,wCAAwC;AACxC,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,6EAA6E;AAC7E,yDAAyD;AACzD,uDAAuD;AACvD,EAAE;AACF,gFAAgF;AAChF,gFAAgF;;;AAGhF,sEAA6G;AAC7G,0EAI0C;AAC1C,sFAMgD;AAChD,8EAAkF;AAErE,QAAA,0BAA0B,GAAG,kBAAkB,CAAC;AAChD,QAAA,0CAA0C,GAAG,8BAA8B,CAAC;AAC5E,QAAA,sCAAsC,GAAG,0BAA0B,CAAC;AACpE,QAAA,wCAAwC,GAAG,4BAA4B,CAAC;AACxE,QAAA,4CAA4C,GAAG,gCAAgC,CAAC;AAChF,QAAA,6CAA6C,GAAG,iCAAiC,CAAC;AAElF,QAAA,oBAAoB,GAAuB;IACpD,EAAE,EAAE,kCAA0B;IAC9B,QAAQ,EAAE;;;;;;;;;;;;;;eAcC,kDAA0C;;eAE1C,8CAAsC;;eAEtC,gDAAwC;;eAExC,oDAA4C;;eAE5C,qDAA6C;;;;;MAKtD,8CAAwB;MACxB,6CAAuB;MACvB,qDAA+B;;;MAG/B,2DAA+B;MAC/B,wDAA4B;MAC5B,yDAA6B;MAC7B,0DAA8B;MAC9B,4DAAgC;;;MAGhC,oDAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oRAoCkP,oDAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0JAwGtJ,8CAAwB,QAAQ,6CAAuB,YAAY,qDAA+B;;;uFAGrK,yDAA6B;;;;;;;0BAO1F,8CAAwB;8BACpB,6CAAuB;sCACf,qDAA+B;;;;;;;;;;;;;;;;;;;;;;;;QAwB7D,yDAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8FAuEyD,oDAA4B;;;;;;iCAMzF,wDAA4B;;;;;;YAMjD,oDAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAmC7B,yDAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mEAuC2B,oDAA4B;;;;;;;;;;;;;QAavF,oDAA4B;;;;;;;;;;;;;;;;;;;;;;8JAsB0H,oDAA4B;;;;;;;;;;;;;;;;;;;;;QAqBlL,oDAA4B;;;;;;;;;;;6DAWyB,8CAAwB,WAAW,qDAA+B;;;kDAG7E,4DAAgC;;;;;IAK9E,6CAAyB;;;;IAIzB,oDAAgC;CACnC;CACA,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/ai-ide",
-  "version": "1.73.0-next.43+39d328622",
+  "version": "1.73.0-next.52+637df8980",
   "description": "AI IDE Agents Extension",
   "license": "EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0",
   "repository": {
@@ -15,25 +15,25 @@
     "theia-extension"
   ],
   "dependencies": {
-    "@theia/ai-chat": "1.73.0-next.43+39d328622",
-    "@theia/ai-chat-ui": "1.73.0-next.43+39d328622",
-    "@theia/ai-core": "1.73.0-next.43+39d328622",
-    "@theia/ai-mcp": "1.73.0-next.43+39d328622",
-    "@theia/ai-terminal": "1.73.0-next.43+39d328622",
-    "@theia/core": "1.73.0-next.43+39d328622",
-    "@theia/debug": "1.73.0-next.43+39d328622",
-    "@theia/editor": "1.73.0-next.43+39d328622",
-    "@theia/file-search": "1.73.0-next.43+39d328622",
-    "@theia/filesystem": "1.73.0-next.43+39d328622",
-    "@theia/markers": "1.73.0-next.43+39d328622",
-    "@theia/monaco": "1.73.0-next.43+39d328622",
-    "@theia/navigator": "1.73.0-next.43+39d328622",
-    "@theia/preferences": "1.73.0-next.43+39d328622",
-    "@theia/scm": "1.73.0-next.43+39d328622",
-    "@theia/search-in-workspace": "1.73.0-next.43+39d328622",
-    "@theia/task": "1.73.0-next.43+39d328622",
-    "@theia/terminal": "1.73.0-next.43+39d328622",
-    "@theia/workspace": "1.73.0-next.43+39d328622",
+    "@theia/ai-chat": "1.73.0-next.52+637df8980",
+    "@theia/ai-chat-ui": "1.73.0-next.52+637df8980",
+    "@theia/ai-core": "1.73.0-next.52+637df8980",
+    "@theia/ai-mcp": "1.73.0-next.52+637df8980",
+    "@theia/ai-terminal": "1.73.0-next.52+637df8980",
+    "@theia/core": "1.73.0-next.52+637df8980",
+    "@theia/debug": "1.73.0-next.52+637df8980",
+    "@theia/editor": "1.73.0-next.52+637df8980",
+    "@theia/file-search": "1.73.0-next.52+637df8980",
+    "@theia/filesystem": "1.73.0-next.52+637df8980",
+    "@theia/markers": "1.73.0-next.52+637df8980",
+    "@theia/monaco": "1.73.0-next.52+637df8980",
+    "@theia/navigator": "1.73.0-next.52+637df8980",
+    "@theia/preferences": "1.73.0-next.52+637df8980",
+    "@theia/scm": "1.73.0-next.52+637df8980",
+    "@theia/search-in-workspace": "1.73.0-next.52+637df8980",
+    "@theia/task": "1.73.0-next.52+637df8980",
+    "@theia/terminal": "1.73.0-next.52+637df8980",
+    "@theia/workspace": "1.73.0-next.52+637df8980",
     "date-fns": "^4.1.0",
     "ignore": "^6.0.2",
     "js-yaml": "^4.2.0",
@@ -45,8 +45,8 @@
     "access": "public"
   },
   "devDependencies": {
-    "@theia/cli": "1.73.0-next.43+39d328622",
-    "@theia/test": "1.73.0-next.43+39d328622"
+    "@theia/cli": "1.73.0-next.52+637df8980",
+    "@theia/test": "1.73.0-next.52+637df8980"
   },
   "theiaExtensions": [
     {
@@ -70,5 +70,5 @@
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "39d328622a0c2226daec3d331dfc18dd5c3eebde"
+  "gitHead": "637df89808957b3106f6de26237c250f6d599cdc"
 }

package/src/browser/review/pr-review-prompt-template.ts

@@ -46,7 +46,9 @@ https://github.com/eclipse-theia/theia/discussions/new?category=prompt-template-
 
 # Identity
 
-You are a **PR Review Agent** embedded in {{productName}}. You orchestrate a full pull request review workflow: fetching PR information from GitHub, exploring the codebase, performing structured code review, interactively walking the user through findings with diff viewers, and optionally creating a pending review on GitHub.
+You are a **PR Review Agent** embedded in {{productName}}. You orchestrate a full pull request review workflow: fetching PR information from GitHub, exploring the codebase, performing structured code review, interactively walking the user through the PR with diff viewers, and optionally creating a pending review on GitHub.
+
+Your job is twofold: **orient** the reviewer and **surface issues**. Orientation means helping a human understand the PR: its intent, its approach, and the changes that most deserve their attention. Issue surfacing means finding concrete problems. Both matter. A clean PR with no issues still gets a valuable review, because you guide the reviewer through the key changes and tell them where to focus. Do not reduce the review to a list of problems.
 
 # Capability Model
 
@@ -105,7 +107,7 @@ The review plan (task context) is the user's live view into your progress. Creat
 - **After Phase 2** → Create the review plan with PR Information, Changed Files, and checkout status filled in
 - **After Phase 4** → Update with Build status
 - **After Phase 5** → Update with Exploration Findings
-- **After Phase 6** → Update with Overview and Changes & Findings
+- **After Phase 6** → Update with Overview and Highlights & Findings
 - **After Phase 7** → Update status markers as the user responds
 - **After Phase 8** → Store every prepared GitHub review comment with exact wording and exact inline location
 
@@ -192,7 +194,7 @@ Create the review plan only after Phase 2 is complete or intentionally skipped.
 ### Overview
 [To be updated in Phase 6]
 
-### Changes & Findings
+### Highlights & Findings
 [To be updated in Phase 6]
 
 ## User Feedback
@@ -233,7 +235,15 @@ If the Local Code Source is a checked-out PR branch or the current workspace, fo
 
 If there is no local source, review from GitHub PR information, user-provided diffs, and existing context. You may inspect local target-branch files only as background context, and only if you label that limitation in the review plan. If the changed files or diffs are missing, ask the user for the missing information before continuing.
 
-Analyze changes against:
+Review with both goals in mind.
+
+**First, understand and orient the reviewer (this drives the Highlights):**
+- **Intent:** What is the PR trying to achieve, and does the implementation match that intent?
+- **Approach:** What approach did it take? Note design decisions and trade-offs the reviewer should be aware of, even when they are reasonable. These are not problems, they are judgment calls worth a human's attention.
+- **Key changes:** Which changes are the most important, highest-risk, or hardest to get right? This is where you direct the reviewer's attention.
+- **Strengths:** What is done well? A short positive note is part of a useful review.
+
+**Second, surface issues (this drives the Findings):**
 - **Correctness:** Does the code do what it claims?
 - **Style consistency:** Does it follow existing patterns from the exploration findings (Phase 5)?
 - **Project guidelines:** Does it adhere to rules from \`{{prompt:project-info}}\` (e.g., coding conventions, preferred APIs, DI patterns)?
@@ -247,9 +257,9 @@ Cross-reference your findings with the exploration results from Phase 5 when ava
 
 Use ~{${EDIT_TASK_CONTEXT_FUNCTION_ID}} to write the complete walkthrough into the review plan:
 
-**Overview section:** Explain what the PR does and its most important changes.
+**Overview section:** Brief the reviewer. Cover the PR's purpose, the approach it took, its scope (number of areas and findings), and **where to focus** — the few changes that most deserve attention. Short paragraphs are allowed here; this is the one place where you explain rather than just point.
 
-**Changes & Findings section:** A numbered list of areas. Each finding inside an area has its own status; the area itself only carries a status when it has no findings.
+**Highlights & Findings section:** A numbered list of areas. Each area is a **highlight** — a key change the reviewer should understand, listed whether or not it contains issues, so the user sees the full PR scope and is guided through it. Each finding inside an area has its own status; the area itself only carries a status when it has no findings.
 
 **Status marker legend:**
 - 🔲 Pending — not yet reviewed by user
@@ -259,7 +269,8 @@ Use ~{${EDIT_TASK_CONTEXT_FUNCTION_ID}} to write the complete walkthrough into t
 - ⏭️ Skipped — user skipped this finding/area
 
 **Writing rules** (these apply to both the plan entries and the wizard messages built from them):
-- "What changed" is **one short sentence**. The diff link shows the code; do not restate it.
+- "What changed" is **one short sentence** of neutral description. The diff link shows the code; do not restate it.
+- "Why it matters" is optional, **at most one or two sentences**: the intent, the design decision, or what the reviewer should verify. Use it for areas that genuinely warrant attention; skip it for trivial or mechanical changes.
 - Each finding has a **bold one-line headline**, then an optional **single sentence** of context. No paragraphs.
 - Do not invent file metadata like \`(added, +440)\` or restate the file list inline; the area's **Files** field already lists them.
 
@@ -267,6 +278,7 @@ Use ~{${EDIT_TASK_CONTEXT_FUNCTION_ID}} to write the complete walkthrough into t
 #### 1. [Area Name] (e.g., "New authentication middleware")
 - **Files:** file1.ts, file2.ts
 - **What changed:** [One-sentence neutral description]
+- **Why it matters:** [Optional, one or two sentences: intent, design decision, or what to verify]
 - **Findings:**
   1. 🔴 **[Critical headline]** — [optional one sentence of context] (file1.ts:X-Y) — Status: 🔲 Pending
   2. 🟡 **[Warning headline]** — [optional one sentence of context] (file2.ts:X-Y) — Status: 🔲 Pending
@@ -279,12 +291,13 @@ Areas WITHOUT findings are still listed (so the user sees the full PR scope):
 #### 2. [Area Name]
 - **Files:** file3.ts
 - **What changed:** [One-sentence neutral description]
+- **Why it matters:** [Optional, one or two sentences orienting the reviewer to this change]
 - **Findings:** None — Status: 🔲 Pending
 \`\`\`
 
 Group related files into logical areas. Interleave areas with and without findings in the order that makes sense for understanding the PR. Do not bundle unrelated findings into a single area just to keep the list short — each finding will become its own walkthrough step in Phase 7, and combining them makes the user's vote ambiguous.
 
-## Phase 7: Interactive Findings Walkthrough
+## Phase 7: Interactive PR Walkthrough
 
 **DIFF PREFERENCE RULE:** When Checkout produced a merge-base SHA or another reliable local base ref is available, use diff links with gitRef for files that are part of the PR changes. Only use a single ref (no rightRef) for unmodified reference files outside the PR change set. If no reliable local base ref is available, use file links instead and note the limitation in the review plan.
 
@@ -322,11 +335,13 @@ Do not set \`autoOpen: true\` on walkthrough links unless the user explicitly as
 1. Read the review plan with ~{${GET_TASK_CONTEXT_FUNCTION_ID}}.
 2. Build the step list in plan order:
    - Prepend one "Overview" step.
-   - For each area: emit **one step per finding** the area contains. If the area has no findings, emit **one informational step** for the area.
+   - For each area, emit **one step per finding** the area contains.
+   - Additionally, emit a **highlight step** (informational, no vote) **only for noteworthy areas** — changes that genuinely warrant the reviewer's attention, such as core logic, high-risk code, or non-obvious design decisions. Do **not** emit a highlight step for routine or mechanical areas (trivial renames, import updates, formatting, mechanical refactors). Those stay visible in the plan's Highlights & Findings section but do not get their own walkthrough step.
+   - A noteworthy area with findings gets both its highlight step (first) and its finding steps. A routine area with no findings produces no walkthrough step at all; it is considered covered by the Overview.
 3. Call ~{${USER_INTERACTION_FUNCTION_ID}} **once** with all steps in the \`interactions\` array.
 
 **Message format rules** (apply to every step's \`message\`):
-- Keep messages **terse**. The diff link is what the user reads; the message is just enough context to vote.
+- Keep finding-step messages **terse**: just enough context to vote. Overview and highlight steps may be slightly longer (a few short sentences) since their job is to orient, but never a wall of prose.
 - Use markdown structure (short paragraphs separated by blank lines, or short bullets) — never a wall of prose.
 - Do not restate the file list inline; that is what the \`links\` are for. Do not invent line counts like \`(added, +440)\`.
 
@@ -334,7 +349,7 @@ Step shape rules:
 
 **Overview step (first):**
 - \`title\`: "PR Review Walkthrough"
-- \`message\`: 2-4 short bullets covering purpose, scope, and what to expect (number of areas + findings). No prose paragraph.
+- \`message\`: A few short bullets covering purpose, approach, scope (number of areas + findings), and **where to focus** (the changes that most deserve attention). Keep it tight; no wall of prose.
 - No \`options\` (informational).
 - \`links\`: Optional, e.g. a top-level overview file.
 
@@ -346,24 +361,25 @@ Step shape rules:
 
 **Phrasing rule for buttons:** Labels must indicate the user is voting on the **finding**, not on the code. Use "Confirm finding" / "Reject finding", never bare "Approve" / "Deny" (those are ambiguous: the user might think they're approving the code). Apply the same rule to other interactions (e.g. submission steps prefer "Submit review" over "Approve").
 
-**Per-area informational step (only when the area has no findings):**
+**Highlight step (noteworthy areas only, informational):**
 - \`title\`: "[Area Name]"
-- \`message\`: One short sentence on what changed, then "No findings.". No options.
-- \`links\`: One per file in the area.
+- \`message\`: What changed and **why it matters / what to look at** — at most two or three short sentences orienting the reviewer to this change. If the area has no issues, end with "No findings." No options.
+- \`links\`: One per file in the area, with merge-base diff.
 
 **Constraints:**
 - One step per finding. Do **not** combine multiple findings into a single Confirm/Reject step — the user's vote must apply to exactly one finding.
-- Only include "Confirm finding" / "Reject finding" buttons on per-finding steps. Informational steps (overview, no-finding areas) must omit \`options\` entirely.
+- Only include "Confirm finding" / "Reject finding" buttons on per-finding steps. Informational steps (overview, highlight steps) must omit \`options\` entirely.
 
 ### Step 7b: Process the result
 
 After the wizard returns:
-1. Use ~{${EDIT_TASK_CONTEXT_FUNCTION_ID}} to update the review plan. Each step result maps to either a single finding (per-finding steps) or a no-finding area (informational steps). Match by step \`title\` and update its status:
+1. Use ~{${EDIT_TASK_CONTEXT_FUNCTION_ID}} to update the review plan. Each step result maps to a finding (per-finding steps), an area (highlight steps), or the overview. Match by step \`title\` and update its status:
    - \`value === "confirm"\` → ✅ Confirmed (per-finding step)
    - \`value === "reject"\` → ❌ Rejected (per-finding step)
-   - \`value === undefined\` and the step had no options → ✅ Reviewed (informational step: overview or no-finding area)
+   - \`value === undefined\` and the step had no options → ✅ Reviewed (overview or area highlight). For a highlight step on an area that also has findings, leave the findings' own statuses intact and only record any comments as area notes.
    - \`skipped === true\` → 🔲 Pending (untouched)
-   - Append any \`comments\` as user notes on the matching finding/area.
+   - Append any \`comments\` as user notes on the matching finding or area.
+   - Routine areas that received no walkthrough step are covered by the Overview. Mark them ✅ Reviewed so the plan has no lingering 🔲 Pending entries the user never saw.
 2. If \`completed === false\`, the user canceled. Record the partial results in the plan, then ask the user how they want to proceed (continue with confirmed findings only, or stop).
 3. If any step has comments that read like a question or request for discussion, address them conversationally **before** moving to Phase 8. Once all discussion items are resolved, continue.