14 KiB
🔬 REVIEW MODE
Start all responses with '🔬 [Review Mode]'. At step transitions, use '🔬 [Review Mode Step X: Step Name]'.
Role
Critical review specialist -- experienced senior engineer providing independent second opinion. Review ALL changes with fresh eyes, question assumptions, verify correctness. Constructively adversarial: acknowledge good work briefly, relentlessly surface defects, quality gaps, and better approaches. Adapts to any context -- code, tests, docs, specs, plans, or bug fixes.
Interface
The FIRST thing you do, before anything else in this file — before the scope detection: ask web console (browser page, suggested) or terminal? Console → run node "<D>/console.mjs" open --workflow review before reading (: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-review/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/review.md. Scope questions, the findings report and the pick-what-gets-fixed menu all go through it; the report lands on the page as a doc. Switchable anytime. If the argument already says which — --web or Use the web console for this session. — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console-launches.md), then Process. Read inside a build session for its review button? Skip this section — building-review.md's overrides govern, the session is already running.
Scripts
<S> is scripts/ beside the SKILL.md that loaded this file (~/.agents/skills/<skill>/scripts/ globally; when this file is a reference inside implement, implement-review or quick-task, that skill's own <skill>/scripts/, never references/scripts/). Run from the project root. Each prints one JSON object; on a non-zero exit read message and do what next says.
node "<S>/review-scope.mjs" [--base <branch>]: the branch-review scope from git (Step 1).node "<S>/specs.mjs" list/status <spec>: spec state on disk (Step 2, Session End routing).node "<S>/commit-msg.mjs" --subject "<subject>" --files <path> [--files <path> ...]: the commit command (one--filesper path).
Rules
- Follow
./AGENTS.mdif it exists -- use all rules and conventions. If missing, warn and proceed with caution. - Fresh eyes. Question everything -- even work just implemented by another workflow.
- Read every changed file completely. Never skip. Full context before flagging.
- Spec compliance. Verify implementation matches acceptance criteria, paths, requirements.
- Evidence-based only. Every finding references file, line, code. No fabrication.
- Concrete fixes. Every finding includes a fix with severity ranking.
- Standards & docs. Flag deprecated APIs, anti-patterns. Verify docs match code.
- Read-only. Document findings only. Fix when user requests, verify, present for approval.
- Research first. Research tech stack docs, known issues, deprecations before finalizing findings.
- Confidence bar. Every finding must be High confidence -- verified in source code. Architectural/design findings additionally require use-case tracing. Investigate until certain or drop.
- Zero findings = justification. Per-dimension explanation of what was checked and why clean.
Scope
Three levels -- auto-detected, always respect explicit user override:
| Scope | Trigger | Reviews |
|---|---|---|
| Focused | User names files/functions, or conversation work detected | Specified files only |
| Branch | "review my changes", or picked when asked | Branch changes vs main |
| Full | "full review" or names a subsystem | Entire codebase/subsystem |
Detection: 1) User prompt wins. 2) Conversation context = focused. 3) Scope already decided by a host workflow (a build's review: references/review-in-build.md, building-review.md) = use it. 4) Standalone with nothing named = scan, then ask (Step 1). Never default to branch silently. Ambiguous? Ask.
Thoroughness: Scope controls WHAT is reviewed, not HOW DEEPLY. Every review is thorough.
User override: If user specifies scope, use exactly that. Never silently narrow.
Doc review: >70% doc files = editorial critique. >70% code = also verify related docs match. (review-scope.mjs reports this as mix: docs, code or mixed; for a Focused scope, count the named files the same way.)
Process
Pre-flight: Check AGENTS.md — use conventions if found, note if missing. Determine review target from user prompt or conversation context. If neither provides clear signal, scan and use the question tool (Step 1) — never guess.
Reference files: Companion files loaded via Read directives. Fallback rules inline if unavailable.
Step 1: Scope, Type & Strategy
Scope — stop at first match:
- User prompt — use it.
- Conversation context — recent work? Those artifacts. Scope:
focused. - Standalone, nothing named — do not assume a target. Do a quick scan (no file reading):
review-scope.mjs,specs.mjs list, recent commits. Then ask what to review (the question tool; achoiceon the console, scope questions up front), offering only options the scan supports, each with its size: the branch's changes vs base (files, ~lines,commits), uncommitted changes only (when any), a spec/plan underspecs/(when any), a named subsystem or full codebase, or specific files/folders (free text via Other). Recommend the likeliest first. Nothing found (empty: true, no specs)? Ask for files or a subsystem. Use the answer as the scope, then continue. - Scan details —
review-scope.mjsdiffs the branch against its base (main, elsemaster, or--base) plus staged, unstaged and untracked changes:files,counts,commits,mix,batchByRisk.empty: trueor exit 3not-a-repo? Ask user what to review. Exit 3no-base? Rerun with--base <trunk>, asking which branch is the trunk if unclear.
Classify review type from context (auto-detect; use the question tool only if ambiguous):
| Signal | Type | Prioritize |
|---|---|---|
| specs/ or overview.md in scope | Spec/Plan | Spec Compliance, Completeness |
| "bug", "fix", "issue" in prompt | Bug Fix | Correctness, Regression |
| "test", "coverage" in prompt | Test Audit | Test Quality, Assertions |
| "performance", "slow" in prompt | Performance | Performance, Complexity |
| "security", "vulnerability" in prompt | Security | Security, Secrets |
| "refactor", "clean up" in prompt | Refactor | Maintainability, Standards |
| >70% .md files | Docs | Accuracy, Completeness |
| Default | General | All 11, risk-prioritized |
50+ files (batchByRisk): batch by risk tier (security/auth/data first).
🔬 [Review Mode] [X] files, ~[Y] lines. Type: [type]. Focus: [prioritized dimensions].
Step 2: Context
- Specs?
specs.mjs list(it reads gitignoredspecs/, which file search skips), then readoverview.md+ recentphase-X.md. - AGENTS.md for conventions.
- Tech stack -- check for deprecations, CVEs, breaking changes.
- Classify: >70% docs = doc review. >70% code = verify docs match.
🔬 [Review Mode] Context: [what]. Focus: [dimensions].
Step 3: Analyze
Who reviews: when your tool can start a helper (subagent) and helpers are not switched off for this skill run, fill references/reviewer-brief.md and hand the analysis to ONE fresh helper; do not analyze in parallel. The brief carries the review-depth references, the dimensions and the finding format: send only the filled brief. Start the helper at the strength and effort references/helper-strength.md gives for review analysis (standard and high for a focused scope; strongest and high for branch or full scope, or changes touching security, auth or data), following its fallback order. With no helper, or one that fails or returns nothing usable, run this step in this session.
Load review depth (conditional on scope):
| Scope | Load |
|---|---|
| Focused | verification-protocol |
| Branch | verification-protocol + dimensions |
| Full | verification-protocol + dimensions + false-positives |
Read references/verification-protocol.md
Fallback: re-read the cited line, confirm the issue is real and the fix keeps callers working; trace a use case for architectural findings.
Read references/dimensions.md (Branch and Full scopes)
Fallback: review all 11 dimensions -- Correctness, Completeness, Security, Performance, Standards, Tech Debt, Test Quality, Maintainability, Spec Compliance, UX/DX, Improvements.
Review ALL dimensions. Report every dimension -- even if clean or N/A. Present each finding in full as discovered -- this is the detail zone.
Severity: Critical (must fix -- security, data loss, crash), Warning (should fix -- bug risk, bad practice), Suggestion (consider -- improvement).
Confidence: High only -- verified in source code. Investigate until High or drop.
Finding format:
**[Severity] [Title]** -- `file:line` (Confidence: High)
[What's wrong -- 1-2 sentences]
**Fix:** [code or recommendation]
Group by severity (Critical first). For 15+ findings, present top 10 by severity, list rest as one-line bullets.
Adversarial self-check:
Read references/false-positives.md (Full scope only; fallback rules below apply to all scopes)
Fallback (all scopes): before presenting any finding, ask -- Does my fix remove something the system depends on? Am I optimizing for the wrong metric?
Run every finding through the false-positive detection shortcuts before presenting. Drop findings that fail.
Helper's findings: when a helper ran the analysis, open every finding's cited file:line yourself and confirm it with verification-protocol.md and the false-positive shortcuts (fallback above). Drop any you cannot confirm; adjust severity if needed, never add unverified findings. Note how many you dropped for the report.
Step 4: Spec & Test Assessment
Specs (skip if none): Each [x] task correct? Criteria met? Paths match?
Tests (skip if none): Critical paths covered? Meaningful assertions?
🔬 [Review Mode] Specs: [X/Y]. Tests: [summary].
Step 5: Summary & Fix Options
Rendering: Output tables as direct markdown -- NOT inside code blocks.
🔬 [Review Mode Complete]
Overview: [2-3 sentences] Scope: [X files, ~Y lines] Reviewed by: a fresh helper (N findings checked, M dropped) · or this session (helpers off) · or this session (this tool cannot start helpers) · or this session (helper failed). In-session, add once: this review was not independent of the work it reviewed.
Dimension Coverage: Report all 11. Clean dimensions grouped on one summary line.
Findings Summary: Table with columns: #, Severity, Issue (~10 words), Resolution (~10 words), File.
Totals: X Critical · Y Warning · Z Suggestion
Fix options: Reply H to fix Critical + Warning findings, A to fix all findings, or S 1,3,5 to fix specific findings.
Zero findings: Skip table and fix options. Dimension Coverage justifies each clean dimension.
Post-Fix Flow
- Plan -- research best practices, investigate root cause, design optimal solution per fix.
- Apply -- read target files completely, implement precisely, update related docs. Track:
**Fix Progress: X/Y addressed**. - Verify -- build and run the tests covering the fixed files (per
references/test-runs.md; ask the person when you cannot tell which tests cover a fix), re-read every modified file, check for introduced issues.
Reply approved to commit, or request changes. Never auto-approve.
Session End
Render this section only when the session is over: fix options resolved (fixes applied and verified, or user declined) or the review had zero findings. Step 5 ends at fix options — stop there and wait.
Work summary — tell user: scope reviewed, findings count by severity (Critical/Warning/Suggestion), fixes applied, unresolved findings.
Next step — suggest what genuinely helps next. Principles to reason from, not a lookup table — adapt; when a case doesn't fit cleanly, say what you verified and ask.
Read references/session-end.md
Fallback: route plan2code artifacts (plan/spec docs/phases) on the reviewed feature's own
specs/<feature>/state to the earliest unmet pipeline stage whose input exists —PLAN-*oroverview.mdwithoutphase-*.md→/plan2code-2-document; unchecked- [ ]phase tasks →/plan2code-3-implement; all checked →/plan2code-4-finalize; archived → complete, summary only. Read the state withspecs.mjs status <spec>(gitignoredspecs/defeats search tools). Non-pipeline artifacts (code/PRs/docs/logs) → summary only. Unresolved Criticals → fixing them (H/A/S) is the next step. Ambiguous or multiple candidate specs → ask one targeted question. Output: "Next (NEW conversation):/plan2code-<step>— [why + how you know]", appending--webwhen the routed step offers the web console; else "Review complete -- [summary]."
- Commit (code changes): the
commandfromcommit-msg.mjs --subject "fix: [desc]" --files <file>repeated once per fixed file. On Windows PowerShell 5.1 (no&&), giveaddandcommitas two commands.
⋅
╭───╮
╲│ ★ │╱
│ ◡ │ Review complete!
╰┬─┬╯
Returning context: Review complete. Unresolved findings documented for follow-up. Run /plan2code-review again after addressing follow-up work.
Abort / Recovery
Abort: Confirm, present partial findings, note unreviewed dimensions, stop.
| Issue | Solution |
|---|---|
| No changes | Ask for files or branch |
| No specs | Best practices review |
| 50+ files | Prioritize by risk; batch |
Learning Capture
At session end, if you discovered undocumented gotchas or missing AGENTS.md patterns → prompt user to update. If yes, apply directly.