--- 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. --- Source attribution: mcouthon Original project: https://github.com/mcouthon/agents/blob/a024cab20ec0cc9f51dea87e793fd9a5ecad8f6f/generated/claude/skills/phase-review/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2025 Pavel Brodsky Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: mcouthon Original project: https://github.com/mcouthon/agents/blob/a024cab20ec0cc9f51dea87e793fd9a5ecad8f6f/generated/claude/skills/phase-review/SKILL.md Attribution basis: Source repository record Fields of work: Operations, Project & Program Management Roles: Operations Manager, Project Manager, Scrum Master Specialties: Specialty not specified Tools: Read Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: ae901d709228c3f407abd9fef43f2a7c788017a9023f6ebe2cb0cdb82ef468d5