john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(document-review): reduce token cost and latency (#509)

Browse Source 
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Trevin Chow
2026-04-04 23:31:56 -07:00
committed by GitHub
parent b223e39a63
commit 9da73a6091
8 changed files with 179 additions and 216 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -25,15 +25,10 @@ Rules:
- Set `finding_type` for every finding:
- `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. 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.
- 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.
- Set `autofix_class` based on whether there is one clear correct fix, not on severity:
- `auto`: One clear correct fix, applied silently. Three categories: (1) internal reconciliation -- one document part authoritative over another (summary/detail mismatches, wrong counts, stale cross-references, terminology drift); (2) implied additions -- correct content mechanically obvious from the document (missing steps, unstated thresholds, completeness gaps); (3) codebase-pattern-resolved -- an established codebase pattern resolves ambiguity (cite the specific file/function in `why_it_matters`). Always include `suggested_fix`. NOT auto if more than one reasonable fix exists or if scope/priority judgment is involved.
- `present`: Requires user judgment -- strategic questions, tradeoffs, design tensions.
- `suggested_fix` is required for `auto` findings. For `present` findings, include only when the fix is obvious.
- If you find no issues, return an empty findings array. Still populate residual_risks and deferred_questions if applicable.
- Use your suppress conditions. Do not flag issues that belong to other personas.
</output-contract>
@@ -46,13 +41,3 @@ Document content:
{document_content}
</review-context>
```
## Variable Reference
| Variable | Source | Description |
|----------|--------|-------------|
| `{persona_file}` | Agent markdown file content | The full persona definition (identity, analysis protocol, calibration, suppress conditions) |
| `{schema}` | `references/findings-schema.json` content | The JSON schema reviewers must conform to |
| `{document_type}` | Orchestrator classification | Either "requirements" or "plan" |
| `{document_path}` | Skill input | Path to the document being reviewed |
| `{document_content}` | File read | The full document text |