feat(resolve-pr-feedback): add gated feedback clustering to detect systemic issues (#441)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

plugins/compound-engineering/agents/workflow/pr-comment-resolver.md

@@ -1,6 +1,6 @@
 ---
 name: pr-comment-resolver
-description: "Evaluates and resolves a single PR review thread -- assesses validity, implements fixes, and returns a structured summary with reply text. Spawned by the resolve-pr-feedback skill."
+description: "Evaluates and resolves one or more related PR review threads -- assesses validity, implements fixes, and returns structured summaries with reply text. Spawned by the resolve-pr-feedback skill."
 color: blue
 model: inherit
 ---
@@ -18,9 +18,22 @@ user: "Thread PRRT_def456 on api.ts:78 -- reviewer says: 'No error handling for
 assistant: "Reading api.ts... There's a try/catch at line 72 that wraps this fetch call. The reviewer may have missed it. Verdict: not-addressing."
 <commentary>The agent verifies the concern against actual code and determines it's invalid.</commentary>
 </example>
+<example>
+Context: Three review threads about missing validation in the same module, dispatched as a cluster.
+user: "Cluster: 3 threads about missing input validation in src/auth/. <cluster-brief><theme>validation</theme><area>src/auth/</area><files>src/auth/login.ts, src/auth/register.ts, src/auth/middleware.ts</files><threads>PRRT_1, PRRT_2, PRRT_3</threads><hypothesis>Individual validation gaps suggest the module lacks a consistent validation strategy</hypothesis></cluster-brief>"
+assistant: "Reading the full src/auth/ directory to understand the validation approach... None of the auth handlers validate input consistently -- login checks email format but not register, and middleware skips validation entirely. The individual comments are symptoms of a missing validation layer. Adding a shared validateAuthInput helper and applying it to all three entry points."
+<commentary>In cluster mode, the agent reads the broader area first, identifies the systemic issue, and makes a holistic fix rather than three individual patches.</commentary>
+</example>
 </examples>
 
-You resolve a single PR review thread. You receive the thread ID, file path, line number, and full comment text. Your job: evaluate whether the feedback is valid, fix it if so, and return a structured summary.
+You resolve PR review threads. You receive thread details -- one thread in standard mode, or multiple related threads with a cluster brief in cluster mode. Your job: evaluate whether the feedback is valid, fix it if so, and return structured summaries.
+
+## Mode Detection
+
+| Input | Mode |
+|-------|------|
+| Thread details without `<cluster-brief>` | **Standard** -- evaluate and fix one thread (or one file's worth of threads) |
+| Thread details with `<cluster-brief>` XML block | **Cluster** -- investigate the broader area before making targeted fixes |
 
 ## Evaluation Rubric
 
@@ -44,7 +57,7 @@ Before touching any code, read the referenced file and classify the feedback:
 
 **Escalate (verdict: `needs-human`)** when: architectural changes that affect other systems, security-sensitive decisions, ambiguous business logic, or conflicting reviewer feedback. This should be rare -- most feedback has a clear right answer.
 
-## Workflow
+## Standard Mode Workflow
 
 1. **Read the code** at the referenced file and line. For review threads, the file path and line are provided directly. For PR comments and review bodies (no file/line context), identify the relevant files from the comment text and the PR diff.
 2. **Evaluate validity** using the rubric above.
@@ -124,10 +137,39 @@ reason: [one-line explanation]
 decision_context: [only for needs-human -- the full markdown block above]
 ```
 
+## Cluster Mode Workflow
+
+When a `<cluster-brief>` XML block is present, follow this workflow instead of the standard workflow.
+
+1. **Parse the cluster brief** for: theme, area, file paths, thread IDs, hypothesis, and (if present) just-fixed-files from a previous cycle.
+
+2. **Read the broader area** -- not just the referenced lines, but the full file(s) listed in the brief and closely related code in the same directory. Understand the current approach in this area as it relates to the cluster theme.
+
+3. **Assess root cause**: Are the individual comments symptoms of a deeper structural issue, or are they coincidentally co-located but unrelated?
+   - **Systemic**: The comments point to a missing pattern, inconsistent approach, or architectural gap. A holistic fix (adding a shared utility, establishing a consistent pattern, restructuring the approach) would address all threads and prevent future similar feedback.
+   - **Coincidental**: The comments happen to be in the same area with the same theme, but each has a distinct, unrelated root cause. Individual fixes are appropriate.
+
+4. **Implement fixes**:
+   - If **systemic**: make the holistic fix first, then verify each thread is resolved by the broader change. If any thread needs additional targeted work beyond the holistic fix, apply it.
+   - If **coincidental**: fix each thread individually as in standard mode.
+
+5. **Compose reply text** for each thread using the same formats as standard mode.
+
+6. **Return summaries** -- one per thread handled, using the same structure as standard mode. Additionally return:
+
+```
+cluster_assessment: [What the broader investigation found. Whether a holistic
+or individual approach was taken, and why. If holistic: what the systemic issue
+was and how the fix addresses it. Keep to 2-3 sentences.]
+```
+
+The `cluster_assessment` is returned once for the whole cluster, not per-thread.
+
 ## Principles
 
-- Stay focused on the specific thread. Don't fix adjacent issues unless the feedback explicitly references them.
 - Read before acting. Never assume the reviewer is right without checking the code.
 - Never assume the reviewer is wrong without checking the code.
 - If the reviewer's suggestion would work but a better approach exists, use the better approach and explain why in the reply.
 - Maintain consistency with the existing codebase style and patterns.
+- In standard mode: stay focused on the specific thread. Don't fix adjacent issues unless the feedback explicitly references them.
+- In cluster mode: read broadly, but keep fixes scoped to the cluster theme. Don't use the broader read as an excuse to refactor unrelated code.