- **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.
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.
**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.
- **Plan2Code Workflow Pipeline:** `/plan2code-1-plan` → `PLAN-*` files · `/plan2code-2-document` → `overview.md` + `phase-*.md` (the "spec docs") in `specs/<feature>/` · `/plan2code-3-implement` → checks off phase tasks, one phase per run · `/plan2code-4-finalize` → archives to `specs--completed/`.
- **Find specs (any OS/shell):** `specs/` is gitignored, and search tools (Glob/Grep/project search) skip gitignored paths on many platforms — an empty search result is not evidence either way. Check with a terminal listing: `ls specs/<feature>/` (bash/zsh) · `Get-ChildItem specs/<feature>` (PowerShell) · `dir specs\<feature>` (cmd). Feature dir unknown? List `specs/` first. Command errors? Try another shell's form, then read the expected files directly — file reads see gitignored paths. Conclude "no specs" only after a terminal listing or a failed direct read.
- **Reconcile three signals:** session context (what this conversation was doing — a fresh session may have none), user intent (what they asked reviewed), the disk check above. Disk wins on state; context wins on intent and on disk silence; no context → intent + disk decide.
- **plan2code artifact reviewed (a plan, the spec docs, phases) — route on the reviewed feature's own `specs/<feature>/` state (another feature's specs prove nothing here), to the earliest unmet stage, suggesting only a step whose input exists:**
-`PLAN-*` without `overview.md` → `/plan2code-2-document`
-`overview.md` without `phase-*.md` → `/plan2code-2-document`
- Unchecked `- [ ]` tasks in `phase-*.md` → `/plan2code-3-implement` (checkboxes are ground truth; flag overview conflicts)
- All phase tasks checked → `/plan2code-4-finalize`
- Archived spec → pipeline complete; summary only
- **Anything else** (code/PRs, logs, docs, tickets, emails, a codebase): no pipeline step — close with the summary; add a next action only if the review makes one obvious and actionable.
- **Gates:** unresolved Criticals → fixing them (H/A/S) is the next step. Signals the rules above can't reconcile, or multiple candidate specs → ask one targeted question.
- **Output:** "Next (NEW conversation): `/plan2code-<step>` — [why + how you know]"; otherwise "Review complete -- [summary]."
