- **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 no context available | Branch changes vs main |
| **Full** | "full review" or names a subsystem | Entire codebase/subsystem |
**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.
## 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, use `ask_user_question` — 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:
1.**User prompt** — use it.
2.**Conversation context** — recent work? Those artifacts. Scope: `focused`.
| Full | verification-protocol + dimensions + false-positives |
Read references/verification-protocol.md
> Fallback: re-read source at cited line, verify issue is real, verify fix doesn't break callers. For architectural findings, trace a use case end-to-end.
Read references/dimensions.md (Branch and Full scopes)
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.
### 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.
Work summary — tell user: scope reviewed, findings count by severity (Critical/Warning/Suggestion), fixes applied, unresolved findings.
After approval, select template based on project state:
**Pre-condition check:** Before suggesting implement or finalize, verify that `overview.md` AND at least one `phase-*.md` file exist in the specs directory. If they do NOT exist, the document step has not been run yet.
- **Specs dir exists but NO overview.md / phase-*.md files:** "Next: generate implementation docs. NEW conversation: `/plan2code-2-document`"
- **Specs + overview.md + phase files + more phases:** "Next: Phase X. NEW conversation: `/plan2code-3-implement`"
- **Specs + overview.md + phase files + all complete:** "All complete! NEW conversation: `/plan2code-4-finalize`"
