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 (<D>: 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 <D>/console.md and <D>/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.
`<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 `--files` per path).
- **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 |
**Detection:** 1) User prompt wins. 2) Conversation context = `focused`. 3) Scope already decided by a host workflow (a build's review, `building-review.md`) = use it. 4) Standalone with nothing named = scan, then ask (Step 1). Never default to `branch` silently. Ambiguous? Ask.
**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.)
**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 `ask_user_question` (Step 1) — never guess.
3.**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 (`ask_user_question`; a `choice` on 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 under `specs/` (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.
4.**Scan details** — `review-scope.mjs` diffs the branch against its base (`main`, else `master`, or `--base`) plus staged, unstaged and untracked changes: `files`, `counts`, `commits`, `mix`, `batchByRisk`. `empty: true` or exit 3 `not-a-repo`? Ask user what to review. Exit 3 `no-base`? Rerun with `--base <trunk>`, asking which branch is the trunk if unclear.
**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.
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.
**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.
3.**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.
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.
> 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-*` or `overview.md` without `phase-*.md` → `/plan2code-2-document`; unchecked `- [ ]` phase tasks → `/plan2code-3-implement`; all checked → `/plan2code-4-finalize`; archived → complete, summary only. Read the state with `specs.mjs status <spec>` (gitignored `specs/` 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 ` --web` when the routed step offers the web console; else "Review complete -- [summary]."
- **Commit** (code changes): the `command` from `commit-msg.mjs --subject "fix: [desc]" --files <file>` repeated once per fixed file. On Windows PowerShell 5.1 (no `&&`), give `add` and `commit` as two commands.