Phase Plan Review

---
name: phase-review-a829736f27a6
description: "Review implementation plans from the .tasks/ directory for flaws before committing — either a single phase (phase mode) or across all phases of a task for consistency (cross-phase analyze mode). Triggers on: 'use phase mode', 'review phase', 'review the plan', 'check phase', 'validate phase', 'review phase N', 'check the plan for phase', 'analyze phases', 'cross-phase review', 'check consistency across phases', 'analyze the task plan'."
allowed-tools: [Read, Grep, Glob, Edit, LSP]
---

# 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 `parallel_group`, or `blocked_by` / `Deps` disagree between state.json 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 the phase has a `parallel_group` assigned, additionally check:

- **File overlap (mechanical):** Read the `## Files Modified` section from each
  phase plan in the same parallel group. 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 group safety** — phases in the same `parallel_group` that modify
  overlapping files or share mutable state. Severity: High if file overlap,
  Medium if shared-state risk.
- **Dependency consistency** — `blocked_by` edges in state.json 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 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.