@mechanai/deepreview 2.6.1 → 2.7.0

package/.opencode/agents/deepreview-planner.md

@@ -23,6 +23,22 @@ You will receive a path to a synthesis file. Read it.
 2. For each finding, read ONLY the specific function or block referenced (use the Read tool with offset/limit to read ~50 lines around the referenced line — do NOT read entire files)
 3. Write exact code changes for each fix
 
+## Documentation Drift handling
+
+If the synthesis contains a "Documentation Drift" section with a batched checklist, consolidate all those items into a **single** fix entry in the plan. Do not create separate fix entries for each documentation item. Use this format:
+
+```
+### Fix [N]: Documentation Updates
+**File(s):** [list all affected files]
+**Priority:** suggestion
+**Approach:** Batch update stale/verbose documentation
+**Code changes:**
+[Group changes by file. For each file, show the exact text replacement.]
+**Verification:** Confirm updated docs match current code behavior
+```
+
+Critical documentation findings (which appear individually in the "Critical Issues" section, not in "Documentation Drift") should still get their own fix entries.
+
 ## Quality rules
 
 - **One clean solution per fix.** Do not include your reasoning process, rejected approaches, or self-corrections in the output. If you are unsure which approach is best, pick the simplest one and add a one-line "Alternative:" note.

package/.opencode/agents/deepreview-synthesizer.md

@@ -25,8 +25,20 @@ If your prompt begins with a "Prior Findings" preamble, reviewers were instructe
 
 1. Read all validated review files
 2. Deduplicate: if multiple validators confirmed the same issue, merge into one entry and note agreement
-3. Rank by severity (critical first, then warning, then suggestion)
-4. Within each severity level, rank by confidence (high before medium)
+3. Batch non-critical documentation findings into a single grouped checklist (see "Documentation finding batching" below)
+4. Rank remaining findings by severity (critical first, then warning, then suggestion)
+5. Within each severity level, rank by confidence (high before medium)
+
+## Documentation finding batching
+
+Documentation findings (stale comments, outdated counts, dead references, verbose docs) at **warning** or **suggestion** severity should be collapsed into a single "Documentation Drift" section rather than appearing as individual top-level entries in the severity sections.
+
+Rules:
+
+- **Critical** doc findings (false claims that would cause API misuse) remain as individual entries in "Critical Issues" — they are NOT batched
+- **Warning** and **suggestion** doc findings are batched into a checklist in the dedicated "Documentation Drift" section
+- Each checklist item gets one line: `- [ ] [what to fix] in \`path/to/file:line\``
+- If there are zero non-critical doc findings, omit the "Documentation Drift" section entirely
 
 ## Output format
 
@@ -42,10 +54,16 @@ Write your synthesis to the output path provided. Use this structure:
 [All critical severity items, deduplicated and ranked by confidence]
 
 ## Warnings (should fix)
-[All warning severity items, deduplicated]
+[All warning severity items, deduplicated — excludes documentation findings, which are batched below]
 
 ## Suggestions (nice to have)
-[All suggestion items, grouped by theme]
+[All suggestion items, grouped by theme — excludes documentation findings, which are batched below]
+
+## Documentation Drift
+The following doc/comment updates were identified (suggestion-level):
+- [ ] [description of fix] in `path/to/file:line`
+- [ ] [description of fix] in `path/to/file:line`
+[Omit this section if there are no non-critical documentation findings]
 
 ## Points of Agreement
 [Issues confirmed by multiple validators — these are highest confidence]

package/.opencode/commands/deepreview-loop.md

@@ -134,7 +134,19 @@ Task — Use the Task tool with subagent_type="general":
 
 ## Prior Findings (already reported — do not re-report or verify)
 
-- [Short Issue Title] ([category]) — [file:line]
+For each finding, include the title, category, location, AND a 1-sentence mechanism description explaining what the underlying problem is:
+
+- [Short Issue Title] ([category]) — [file:line] — [1-sentence description of the underlying mechanism/problem]
+
+Example:
+
+- Missing semaphore guard (architecture) — src/module.rs:245 — concurrent operations share mutable state without synchronization
+
+## Known Issue Locations (same file:line = likely same issue — justify if reporting again)
+
+List every file:line from Prior Findings in a condensed location-first index:
+
+- [file:line] — [condensed mechanism] ([category])
 
 ## Applied Fixes (changes made by previous iterations — new bugs here are regressions)
 
@@ -144,7 +156,7 @@ Task — Use the Task tool with subagent_type="general":
 
 - [file:line-range] (pad each finding's file:line by 20 lines in each direction)
 
-Deduplicate findings that appear in multiple syntheses. Return ONLY these three sections, nothing else."
+Deduplicate findings that appear in multiple syntheses. Return ONLY these four sections, nothing else."
 
 Set PRIOR_CONTEXT to the returned text. Validate that it contains "## Prior Findings" — if not, warn the user ("Helper returned malformed prior context — proceeding without deduplication") and set PRIOR_CONTEXT="". If CONTEXT_FILE exists, prepend:
 "## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n" + contents of CONTEXT_FILE + "\n`\n\n"
@@ -155,7 +167,14 @@ Stage 1 — DISPATCH 5 PARALLEL REVIEWERS:
 Each reviewer prompt MUST include PRIOR_CONTEXT and the novelty-seeking framing below.
 
 The REVIEWER_PREAMBLE for all iter2+ reviewers is:
-"Your goal is to find issues that PREVIOUS reviewers missed. Do NOT re-report, verify, or comment on prior findings. If you find a bug in code listed under 'Applied Fixes', flag it as a regression.
+"Your goal is to find issues that PREVIOUS reviewers missed. Do NOT re-report, verify, or comment on prior findings.
+
+When you encounter a potential issue:
+
+1. Check "Known Issue Locations" — if your finding is at or near a listed location, it is almost certainly already reported. Only report it if the mechanism is genuinely different (not just differently worded).
+2. Check "Prior Findings" — if your finding matches an existing mechanism description (even at a different location), it is a variant of an already-reported issue. Do not report it.
+
+If you find a bug in code listed under 'Applied Fixes', flag it as a regression.
 
 $PRIOR_CONTEXT
 

package/.opencode/commands/deepreview-spec-loop.md

@@ -94,7 +94,19 @@ Task — Use the Task tool with subagent_type="general":
 
 ## Prior Findings (already reported — do not re-report or verify)
 
-- [Short Issue Title] ([category]) — [file:line or section reference]
+For each finding, include the title, category, location, AND a 1-sentence mechanism description explaining what the underlying problem is:
+
+- [Short Issue Title] ([category]) — [file:line or section reference] — [1-sentence description of the underlying mechanism/problem]
+
+Example:
+
+- Missing error recovery path (completeness) — spec.md:§3.2 — no defined behavior when upstream service returns partial data
+
+## Known Issue Locations (same location = likely same issue — justify if reporting again)
+
+List every location from Prior Findings in a condensed location-first index:
+
+- [file:line or section reference] — [condensed mechanism] ([category])
 
 ## Applied Fixes (changes made by previous iterations — new bugs here are regressions)
 
@@ -104,7 +116,7 @@ Task — Use the Task tool with subagent_type="general":
 
 - [file or section references, padded generously around each finding location]
 
-Deduplicate findings that appear in multiple syntheses. Return ONLY these three sections, nothing else."
+Deduplicate findings that appear in multiple syntheses. Return ONLY these four sections, nothing else."
 
 Set PRIOR_CONTEXT to the returned text. Validate that it contains "## Prior Findings" — if not, warn the user ("Helper returned malformed prior context — proceeding without deduplication") and set PRIOR_CONTEXT="". If CONTEXT_FILE exists, prepend:
 "## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n" + contents of CONTEXT_FILE + "\n`\n\n"
@@ -112,6 +124,11 @@ Set PRIOR_CONTEXT to the returned text. Validate that it contains "## Prior Find
 The REVIEWER_PREAMBLE for all iter2+ reviewers is:
 "Your goal is to find issues that PREVIOUS reviewers missed. Do NOT re-report, verify, or comment on prior findings.
 
+When you encounter a potential issue:
+
+1. Check "Known Issue Locations" — if your finding is at or near a listed location, it is almost certainly already reported. Only report it if the mechanism is genuinely different (not just differently worded).
+2. Check "Prior Findings" — if your finding matches an existing mechanism description (even at a different location), it is a variant of an already-reported issue. Do not report it.
+
 $PRIOR_CONTEXT
 
 Find genuinely new issues. You may find different issues in covered regions, but prioritize areas not yet examined. Focus ONLY on objective issues — do NOT flag stylistic preferences."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mechanai/deepreview",
-  "version": "2.6.1",
+  "version": "2.7.0",
   "description": "Multi-agent parallel code/spec review for OpenCode",
   "license": "MIT",
   "repository": {