mcouthon/agents/phase-review

Phase Plan Review

This skill has two modes. Pick by what you were asked to review.

Mode 1 — Single phase (default)

This is the only review pass this plan gets — never ask to be re-run on the same plan. Go over the plan for the provided phase in the linked task and make sure it has no flaws; make suggestions if there are changes you'd consider (keep the full context for the task in mind). Anything unresolved goes to the human as BLOCKING.

Plan Summary — produce this before the findings. After reading the plan, write a summary so a human can understand what the plan does without opening the plan file:

• What it does — 1-3 sentences in plain language: what the plan accomplishes and the

approach it takes. No file paths, symbol names, or jargon.

• Risks — 0-3 bullets: technical risks (regression, complexity, fragile dependencies),

security or data-loss exposure, or anything a human should weigh before approving. Write "None identified" if nothing qualifies.

• Customer-facing changes — 0-3 bullets: what end users, API consumers, or other teams

will observe. Write "None — internal only" if purely internal.

Return the summary as part of your response — the orchestrating agent presents it at the plan checkpoint. Persist it to the plan file alongside the findings (see ## File access).

Tag every finding High / Medium / Low (same scale defined under ## File access below), one line per finding.

High is decided by criteria, not by judgement. A finding is High if any of these is true — and is otherwise not High:

• (a) It cannot work as written. A named anchor, file, path, symbol or section does

not exist in the live tree, or a step depends on something no earlier step creates.

• (b) It contradicts an explicit instruction in task.md, AGENTS.md, or an ADR the

task is bound by.

• (c) Parallel/dependency conflict. ## Files Modified intersects another phase in

the same batch, or after / Deps disagree between the task's phases (task_read) and task.md. (Already High under Mode 1's mechanical check below — this keeps the two scales consistent.)

• (d) A required plan section is missing — ## Verification (with success criteria

and a demo statement), ## Tests for any behaviour change, or ## Files Modified.

• (e) A verification step is wrong against the live files — a stated command or grep

that fails before the change lands, or passes whether or not it lands. A guard that cannot fail, or fails on arrival, is not a guard.

• (f) It widens a tool permission, grant, hook or `agents:` scope not named in the

task's approved scope.

`## Tests` content (Mode 1): a weak ## Tests section is a finding — Medium — when its test list mirrors method names one-for-one, mocks internal collaborators (mocks are for system boundaries), verifies mock calls instead of outcomes, or has no behavioral assertion per test (no expected outcome per Given/When/Then). These are the testing skill's Self-Test failures caught at plan time — building them is likely rework.

Binding rule — the verdict is computed, not chosen:

• one or more High findings → BLOCKING, always;
• no High, at least one Medium or Low → APPROVED WITH SUGGESTIONS;
• no findings → APPROVED.

Close with exactly one of APPROVED, APPROVED WITH SUGGESTIONS, or BLOCKING — [what must change, in one line a non-author can act on]. If the tags and the verdict disagree, the tags win — re-derive the verdict.

In your JSON report (the Reviewer's ## Final report block): verdict is pass for APPROVED, pass_with_notes for APPROVED WITH SUGGESTIONS, needs_work for BLOCKING; each finding is one issues entry with severity red for High and yellow for Medium or Low, line a string or null, and its tag kept at the start of text ([Medium] …).

Do not tune the tag to reach a preferred verdict. Never soften a High to avoid BLOCKING; never tag a nitpick High to force attention. Cosmetic, stylistic and count-off-by-a-few findings are Low, never High. The criteria above are the whole test — a confidence percentage is not a severity and does not substitute for one.

If other phases can run in parallel with this one (no after edge between them), additionally check:

• File overlap (mechanical): Read the ## Files Modified section from each

parallel phase's plan. Compute the intersection of their file lists. Flag any overlap as High severity — parallel phases must not modify overlapping files.

• Shared state: Check if this phase reads state that another parallel phase

writes (e.g., shared config files, database migrations that must be ordered). Flag as Medium severity if detected.

Mode 2 — Cross-phase analyze (opt-in, multi-phase tasks only)

Use when asked to analyze a task across its phases (e.g. "analyze phases", "check consistency across phases"). Skip for single-phase tasks — there is nothing to cross-check.

Read task.md (phase table, overview, goal) and ALL plan/*.md for the task, then cross-check the phases against each other and against the goal for:

• Contradictions — phases that assume conflicting state, ordering, or interfaces.
• Duplication — two phases doing the same work.
• Gaps — a goal/overview item or a stated dependency with no owning phase.
• Ordering/dependency — a phase that depends on the output of a later phase.
• Parallel safety — phases that can run in parallel (no after edge between

them) that modify overlapping files or share mutable state. Severity: High if file overlap, Medium if shared-state risk.

• Dependency consistency — after edges in the task's phases (task_read) match the Deps

column in task.md. Flag mismatches as Medium severity.

• Scope drift — a phase doing work outside the task goal.
• Convention misalignment — phases that diverge from AGENTS.md Learned Patterns /

project conventions (when an AGENTS.md is present).

File access

Do NOT modify `task.md` or any source code file, and never change a plan's own instructions. Write your findings as your response — that is what the orchestrating agent presents to the user for adoption or rejection.

Mode 1 — also persist them when you can edit files. A Reviewer cannot; its issues carry the findings. Before returning, append the full tagged list to the phase plan you reviewed, as its last section (sibling of Builder's ## Verification Evidence), using Edit:

## Plan Review — findings (advisory; NOT implementation steps)

Verdict: [verdict], recorded [YYYY-MM-DD]. The plan above is authoritative — adopted findings may already be applied.

What it does: [summary]

Risks: [risks]

Customer-facing changes: [customer-facing changes]

• [High|Medium|Low] — [finding, one line]

This is the only edit you may make to a plan file, and it is what keeps the findings an orchestrator collapses at a review checkpoint reachable by one path. Replace the section if one is already there rather than adding a second. Write the section even when there are no findings — the plan summary is always useful; omit the findings list when empty. Mode 2 spans phases and has no single owning plan file — response only.

For cross-phase mode, structure findings as a list, each item:

• Severity — High (blocks correct implementation) / Medium (likely rework) / Low (minor).
• Phases involved — the phase numbers.
• Issue — one line.
• Recommended resolution — what to change (a suggestion; you do not apply it).

End with an overall consistency verdict (consistent / issues found) and a one-line summary.