fix(document-review): promote pattern-resolved findings to auto (#507)

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

plugins/compound-engineering/skills/document-review/SKILL.md

@@ -174,20 +174,32 @@ Specific conflict patterns:
 - Feasibility says "this is impossible" + product-lens says "this is essential" -> P1 finding framed as a tradeoff
 - Multiple personas flag the same issue -> merge into single finding, note consensus, increase confidence
 
-### 3.6 Route by Autofix Class
+### 3.6 Promote Pattern-Resolved Findings
+
+Scan `present` findings for codebase-pattern-resolved auto-eligibility. Promote `present` -> `auto` when **all three** conditions are met:
+
+1. The finding's `why_it_matters` cites a specific existing codebase pattern -- not just "best practice" or "convention," but a concrete pattern with a file, function, or usage reference
+2. The finding includes a concrete `suggested_fix` that follows that cited pattern
+3. There is no genuine tradeoff -- the codebase context resolves any ambiguity about which approach to use
+
+The principle: when a reviewer mentions multiple theoretical approaches but the codebase already has an established pattern that makes one approach clearly correct, the codebase context settles the question. Alternatives mentioned in passing do not create a real tradeoff if the evidence shows the codebase has already chosen.
+
+Do not promote if the finding involves scope or priority changes where the document author may have weighed tradeoffs invisible to the reviewer.
+
+### 3.7 Route by Autofix Class
 
 **Severity and autofix_class are independent.** A P1 finding can be `auto` if the correct fix is obvious. The test is not "how important?" but "is there one clear correct fix, or does this require judgment?"
 
 | Autofix Class | Route |
 |---------------|-------|
-| `auto` | Apply automatically -- one clear correct fix. Includes both internal reconciliation (one part authoritative over another) and additions mechanically implied by the document's own content. |
+| `auto` | Apply automatically -- one clear correct fix. Includes internal reconciliation (one part authoritative over another), additions mechanically implied by the document's own content, and codebase-pattern-resolved fixes where codebase evidence makes one approach clearly correct. |
 | `present` | Present individually for user judgment |
 
 Demote any `auto` finding that lacks a `suggested_fix` to `present`.
 
-**Auto-eligible patterns:** summary/detail mismatch (body is authoritative over overview), wrong counts, missing list entries derivable from elsewhere in the document, stale internal cross-references, terminology drift, prose/diagram contradictions where prose is more detailed, missing steps mechanically implied by other content, unstated thresholds implied by surrounding context, completeness gaps where the correct addition is obvious. If the fix requires judgment about *what* to do (not just *what to write*), it belongs in `present`.
+**Auto-eligible patterns:** summary/detail mismatch (body is authoritative over overview), wrong counts, missing list entries derivable from elsewhere in the document, stale internal cross-references, terminology drift, prose/diagram contradictions where prose is more detailed, missing steps mechanically implied by other content, unstated thresholds implied by surrounding context, completeness gaps where the correct addition is obvious, codebase-pattern-resolved fixes where the reviewer cites a specific existing pattern and the suggested_fix follows it. If the fix requires judgment about *what* to do (not just *what to write*) and the codebase context does not resolve the ambiguity, it belongs in `present`.
 
-### 3.7 Sort
+### 3.8 Sort
 
 Sort findings for presentation: P0 -> P1 -> P2 -> P3, then by finding type (errors before omissions), then by confidence (descending), then by document order (section position).
 

plugins/compound-engineering/skills/document-review/references/findings-schema.json

@@ -98,7 +98,7 @@
     },
     "autofix_classes": {
       "_principle": "Autofix class is independent of severity. A P1 finding can be auto if the fix is obvious. The test: is there one clear correct fix, or does resolving this require judgment?",
-      "auto": "One clear correct fix -- applied silently. Includes both internal reconciliation (summary/detail mismatches, wrong counts, stale cross-references, terminology drift) and additions mechanically implied by other content (missing steps, unstated thresholds, completeness gaps where the correct content is obvious). Must include suggested_fix.",
+      "auto": "One clear correct fix -- applied silently. Three categories: internal reconciliation (summary/detail mismatches, wrong counts, stale cross-references, terminology drift), additions mechanically implied by other content (missing steps, unstated thresholds, completeness gaps where the correct content is obvious), and codebase-pattern-resolved fixes (the reviewer cites a specific existing codebase pattern that makes one approach clearly correct, regardless of theoretical alternatives). Must include suggested_fix.",
       "present": "Requires individual user judgment -- strategic questions, design tradeoffs, or findings where reasonable people could disagree on the right action."
     },
     "finding_types": {

plugins/compound-engineering/skills/document-review/references/subagent-template.md

@@ -26,11 +26,12 @@ Rules:
   - `error`: Something the document says that is wrong -- contradictions, incorrect statements, design tensions, incoherent tradeoffs.
   - `omission`: Something the document forgot to say -- missing mechanical steps, absent list entries, undefined thresholds, forgotten cross-references.
 - Set `autofix_class` based on whether there is one clear correct fix, not on severity. A P1 finding can be `auto` if the fix is obvious:
-  - `auto`: One clear correct fix. Applied silently without asking. The test: is there only one reasonable way to resolve this? If yes, it is auto. Two categories:
+  - `auto`: One clear correct fix. Applied silently without asking. The test: is there only one reasonable way to resolve this? If yes, it is auto. Three categories:
     - Internal reconciliation: one part of the document is authoritative over another -- reconcile toward the authority. Examples: summary/detail mismatches, wrong counts, missing list entries derivable from elsewhere, stale cross-references, terminology drift, prose/diagram contradictions where prose is authoritative.
     - Implied additions: the correct content is mechanically obvious from the document's own context. Examples: adding a missing implementation step implied by other content, defining a threshold implied but never stated, completeness gaps where what to add is clear.
-    Always include `suggested_fix` for auto findings.
-    NOT auto (the gap is clear but more than one reasonable fix exists): choosing an implementation approach when the document states a need without constraining how (e.g., "support offline mode" could mean service workers, local-first database, or queue-and-sync -- there is no single obvious answer), changing scope or priority where the author may have weighed tradeoffs the reviewer can't see (e.g., promoting a P2 to P1, or cutting a feature the document intentionally keeps at a lower tier).
+    - Codebase-pattern-resolved: the reviewer investigated the codebase and found an established pattern that resolves any ambiguity about the correct fix. The suggested_fix follows that pattern. The test: does the codebase context make one approach clearly correct, regardless of how many alternatives exist in theory? If yes, it is auto. Examples: adding a nil guard using the same early-return pattern found elsewhere in the codebase, applying the naming convention the codebase already follows, promoting a step from conditional to required when code-path analysis proves it is always needed.
+    Always include `suggested_fix` for auto findings. For codebase-pattern-resolved findings, `why_it_matters` must name the specific codebase pattern (file, function, or usage) that makes the fix unambiguous -- `evidence` still quotes the document passage showing the issue.
+    NOT auto (the gap is clear but more than one reasonable fix exists): choosing an implementation approach when the document states a need without constraining how (e.g., "support offline mode" could mean service workers, local-first database, or queue-and-sync -- there is no single obvious answer), changing scope or priority where the author may have weighed tradeoffs the reviewer can't see (e.g., promoting a P2 to P1, or cutting a feature the document intentionally keeps at a lower tier). Note: mentioning alternatives in passing does NOT disqualify a finding from auto -- the test is whether codebase evidence or document context makes one approach clearly superior, not whether other approaches were discussed.
   - `present`: Requires judgment -- strategic questions, tradeoffs, design tensions where reasonable people could disagree, findings where the right action is unclear.
 - `suggested_fix` is required for `auto` findings. For `present` findings, `suggested_fix` is optional -- include it only when the fix is obvious, and frame as a question when the right action is unclear.
 - If you find no issues, return an empty findings array. Still populate residual_risks and deferred_questions if applicable.