cpm-review

name	cpm:review
description	Adversarial review of epic docs and stories. Agents from the party roster examine planning artifacts through their professional lens, challenging assumptions, spotting gaps, and flagging risks. Triggers on "/cpm:review".

Adversarial Review

Run a critical review of an epic doc or a specific story using the party agent roster. Each persona examines the artifact through their professional lens — challenging assumptions, spotting gaps, and flagging risks. Produces a structured review document with severity-tagged findings and an optional autofix that generates remediation tasks.

Input

Check for input in this order:

1. If $ARGUMENTS references a file path (e.g. docs/epics/01-epic-auth.md), use that as the epic doc. If it also includes a story number (e.g. docs/epics/01-epic-auth.md 2), note that as the target story for a story-level review.
2. If $ARGUMENTS is a review file path from a previous /cpm:review run (e.g. docs/reviews/01-review-auth.md), read its **Source**: field to resolve the original epic doc. Offer to re-review or continue from the previous findings.
3. If no path given, look for the most recent docs/epics/*-epic-*.md file and ask the user to confirm.
4. If no epic docs exist, tell the user there's nothing to review and stop.

After resolving the epic doc, read it with the Read tool. Then ask the user about review scope:

• Review the entire epic — All stories and tasks will be examined
• Review a specific story — User selects which story to focus on

For story-level review, present the list of stories from the epic doc and let the user choose. If a story number was provided in $ARGUMENTS, skip the selection and use that story directly.

Roster Loading

Follow the shared Roster Loading procedure. After loading, confirm the roster and how many agents are available: "Review roster loaded: {N} agents available. I'll select the most relevant reviewers based on the content."

Retro Check

Follow the shared Retro Awareness procedure before Agent Selection.

Retro incorporation (this skill):

• All categories: Use the selected cross-retro observations (chosen per the shared Retro Awareness procedure, by relevance across all retros — not just the newest file) as adversarial review prompts for the selected agents — "a retro flagged criteria gaps in auth flows; check whether this artifact has the same risk." This makes review actively guard against recurring failure modes, including ones surfaced by older but on-topic retros.
• Codebase discoveries and patterns worth reusing: Pre-load these as context for reviewer agents that critique structure or implementation.
• Scope surprises and complexity underestimates: Use as prompts for the agents critiquing scope and effort.

Library Check

Follow the shared Library Check procedure with scope keyword review. Deep-read selectively when reviewer personas need context from architecture or coding-standards docs — e.g. an architect reviewing structural decisions, or a developer citing coding standards.

Template Hint (Startup)

After the Library Check and before Agent Selection, display:

Output format is fixed (used by downstream skills). Run /cpm:templates preview review to see the format.

Agent Selection

Select agents dynamically based on the review scope and content. The goal is to match reviewer expertise to what's being reviewed.

Selection Rules

• Story-level review: Pick 2-3 agents whose expertise is most relevant to the story's content.
• Epic-level review: Pick 3-4 agents covering the broadest range of concerns across all stories.

Selection Criteria

For each story or epic, assess the content and match agents by relevance:

• Technical implementation (API endpoints, data models, algorithms) → Developer, Architect
• User-facing features (UI flows, forms, notifications) → UX Designer, Product Manager
• Infrastructure and deployment (CI/CD, environments, scaling) → DevOps Engineer, Architect
• Data handling and security (auth, encryption, PII) → QA Engineer, Architect, Developer
• Process and scope (story sizing, dependency chains, delivery risk) → Scrum Master, Product Manager
• Documentation and naming (terminology, clarity, consistency) → Technical Writer

Always include at least one agent who will challenge the business value of the work (PM or Scrum Master) and at least one who will challenge the technical approach (Developer or Architect). This ensures every review has both a "should we?" and a "can we?" perspective.

Named Agent Format

Each agent's review contribution uses the format:

{icon} **{displayName}**: {review content}

This matches the party mode format for consistency across CPM skills.

Process

State tracking: Create the progress file before Step 1 and update it after each step completes. See State Management below for the format and rationale. Delete the progress file once the final review file has been saved.

Step 1: Analyse the Artifact

Read the target artifact (full epic or specific story) and build a structured understanding:

• For epic-level review: Parse all ## story headings, their acceptance criteria, tasks, dependencies, and status. Note the epic's overall structure — how many stories, dependency chains, completion state.
• For story-level review: Parse the target ## story heading, its acceptance criteria, all ### tasks, and any **Blocked by** dependencies. Also note the story's position within the broader epic for context.

Spec discovery: If the epic doc has a **Source spec**: field, read the referenced spec. This enables spec compliance review — checking whether the epic's stories cover the spec's requirements. If no spec exists, skip silently.

ADR discovery: Glob docs/architecture/[0-9]*-adr-*.md. If ADRs exist, read them. This enables ADR compliance review — checking whether stories respect architectural decisions. If no ADRs exist, skip silently.

Present a brief summary to the user: what's being reviewed, how many stories/tasks, current status. If a spec or ADRs were found, note that they'll be used as review context.

Step 2: Conduct Adversarial Review

This is the core of the skill. Each selected agent examines the artifact through their professional lens and produces findings.

Review Dimensions

Agents should look for issues across these concern types:

• Unclear Requirements — Acceptance criteria that are vague, ambiguous, or untestable. Stories where the definition of done is subjective.
• Missing Acceptance Criteria — Important outcomes that aren't captured. Edge cases, error states, or integration points that should have criteria but don't.
• Hidden Complexity — Tasks that look simple but have non-obvious implementation challenges. Underestimated work that will cause delays.
• Architectural Risks — Structural decisions that could cause problems at scale, create tight coupling, or conflict with existing patterns in the codebase.
• Testability Concerns — Stories or tasks that would be difficult to verify. Acceptance criteria that can't be automatically checked.
• Scope Creep — Stories that try to do too much, tasks that go beyond their parent story's acceptance criteria, or work that belongs in a different epic.
• Dependency Risks — Missing or incorrect **Blocked by** declarations. Circular dependencies. Stories that should be sequenced but aren't.
• Spec Compliance — Stories or acceptance criteria that don't align with the spec's requirements. Must-have requirements that aren't covered by any story. Only applicable when a source spec was discovered in Step 1.
• ADR Compliance — Stories or tasks that contradict or ignore architectural decisions from existing ADRs. Implementation approaches that conflict with the rationale or constraints documented in ADRs. Only applicable when ADRs were discovered in Step 1.
• Missing Test Coverage — Stories with acceptance criteria tagged [unit], [integration], or [feature] that lack a corresponding testing task. Stories where criteria warrant automated testing but have no test approach tags. Only applicable when the source spec has a testing strategy or when stories carry test approach tags.

Not every agent reviews every dimension. Each agent focuses on what they'd naturally notice given their role:

• Product Manager: Unclear requirements, scope creep, missing user value, spec compliance
• Architect: Architectural risks, hidden complexity, dependency risks, ADR compliance
• Developer: Hidden complexity, testability concerns, missing acceptance criteria, ADR compliance, missing test coverage
• UX Designer: Unclear requirements from a user perspective, missing edge cases in user flows
• QA Engineer: Testability concerns, missing acceptance criteria, missing error states, missing test coverage
• DevOps Engineer: Architectural risks (deployment, scaling), dependency risks
• Technical Writer: Unclear requirements (naming, terminology), scope creep (documentation gaps)
• Scrum Master: Scope creep, dependency risks, story sizing concerns

Severity Classification

Each finding must be tagged with exactly one severity level:

• Critical — Blocks execution. The story or task cannot be implemented correctly as written. Examples: contradictory acceptance criteria, impossible dependency chain, missing essential requirement.
• Warning — Likely to cause problems. Implementation can proceed but will probably hit issues. Examples: vague acceptance criteria that different developers would interpret differently, hidden complexity that makes time estimates unreliable.
• Suggestion — Improvement opportunity. Not blocking and may not cause problems, but addressing it would improve quality. Examples: acceptance criteria that could be more specific, a task that could be split for clarity.

Review Execution

Subagent fan-out (when 3+ agents are selected): Each agent's review is independent — they examine the same artifact from different perspectives with no shared state. Spawn parallel subagents via the Agent tool, one per reviewer agent — fan-out is the expected path here, not an optional optimisation. Each subagent's prompt should include: the artifact content, the agent's persona (icon, displayName, role, personality), the review dimensions relevant to their role, the severity classification scheme, and the finding format. Consolidate findings from all subagents after they complete.

Inline execution (when 2 agents are selected or fan-out is unavailable): Review with each agent in turn within the main context.

For each agent (whether via subagent or inline):

1. Review the artifact through the agent's professional lens.
2. Produce 2-5 findings (not a comprehensive audit — focus on the most impactful observations).
3. Tag each finding with a concern type and severity.
4. Reference specific stories, tasks, or acceptance criteria by number.
5. If library documents were loaded, reference relevant standards or constraints where they apply.

Format each finding as:

{icon} **{displayName}** [{severity}]: {finding}
→ {story/task reference}: {specific issue and why it matters}

After all agents have reviewed, present the findings to the user grouped by concern type (not by agent). Within each concern type, order by severity (critical first, then warning, then suggestion).

Progress note: capture concern types found and finding counts by severity in the Step 2 summary.

Step 3: Write Review File

Save the review to docs/reviews/{nn}-review-{slug}.md. Create the docs/reviews/ directory if it doesn't exist.

• {nn} is assigned by the shared Numbering procedure (from the CPM Shared Skill Conventions loaded at session start).
• {slug} is derived from the epic doc name (e.g. epic doc 01-epic-auth.md produces review slug auth). For story-level reviews, append the story number: auth-s2.

Format:

# Review: {Epic or Story Title}

**Date**: {today's date}
**Source**: {path to epic doc}
**Scope**: {Epic | Story N: {Story Title}}
**Agents**: {comma-separated list of agent displayNames who participated}
**Findings**: {total count} ({critical count} critical, {warning count} warnings, {suggestion count} suggestions)

## Summary

{2-3 sentence overview of the review — overall assessment, most significant concerns, and whether the artifact is ready for execution or needs attention.}

## Findings

### Unclear Requirements
{findings in this category, ordered by severity}

- **[{severity}]** {icon} **{agent}**: {finding}
  → {story/task reference}: {specific issue}

### Missing Acceptance Criteria
{findings in this category}

### Hidden Complexity
{findings in this category}

### Architectural Risks
{findings in this category}

### Testability Concerns
{findings in this category}

### Scope Creep
{findings in this category}

### Dependency Risks
{findings in this category}

### Spec Compliance
{findings in this category — only if a source spec was discovered}

### ADR Compliance
{findings in this category — only if ADRs were discovered}

### Missing Test Coverage
{findings in this category — only if test approach tags or testing strategy present}

Only include concern type sections that have findings. If a category has no findings, omit the heading entirely.

Step 4 may append a ## Remediation section to this file — see Autofix below.

Tell the user the review file path after saving.

Faithful Render (on request)

A review's findings, grouped and severity-sorted, read well as a navigable HTML view. Produce one only on request — when the user asks for an HTML version of the review (to read or share) — never automatically as part of writing the review file. Follow the shared HTML Output convention for the mechanics; this section states the review-specific particulars.

When requested:

1. Read the saved review Markdown (docs/reviews/{nn}-review-{slug}.md) read-only — the render generates from the Markdown and must never modify or replace it. The Markdown remains the parsed source of truth.
2. Generate a single self-contained HTML view by consuming the shared template (substitute the CPM: tokens — do not fork the <style> block): the Summary and per-category Findings become the CPM:CONTENT; the review title/date become CPM:TITLE/CPM:META. The template ships severity classes (.sev-critical/.sev-major/.sev-minor/.sev-info) and .finding blocks for exactly this content — use them rather than inventing styling.
3. Write it to docs/reviews/html/{nn}-{slug}.html — same {nn} and {slug} as the source review. Tell the user the path.

Regeneration in place. Because that path is a deterministic function of the source's {nn}/{slug}, re-rendering after the review changes overwrites the same file in place — it updates the existing render rather than spawning a duplicate, and the shared path keeps the render traceable to its source.

This is a faithful projection of the review, not an audience-reframed transform (that is cpm:present's job).

Navigation (artifact-appropriate). A review is a list of findings, so group and sort by severity: order findings most-severe-first (critical → major → minor → info) and tag each with the matching template badge class (.sev-critical/.sev-major/.sev-minor/.sev-info) inside a .finding block, so the reader sees the worst problems first. This is static only — ordering and badges via the template's CSS, no JavaScript.

Step 4: Autofix

After writing the review file, offer the user the option to generate remediation tasks from the findings. This step is optional — the user can skip it entirely.

Decision Gate

If the review produced no critical or warning findings, skip autofix entirely — there's nothing actionable to fix. Inform the user: "No critical or warning findings — skipping autofix." Use the Edit tool to append a ## Remediation section to the review file:

## Remediation

No critical or warning findings — autofix not applicable.

If critical or warning findings exist, present the autofix option using AskUserQuestion:

• Generate fix tasks — Create remediation items from critical and warning findings
• Skip autofix — Proceed to pipeline handoff without generating tasks

If the user chooses Skip autofix, use the Edit tool to append a ## Remediation section to the review file before proceeding to Step 5:

## Remediation

Autofix offered but declined. {N} critical and {N} warning findings remain unaddressed.

Suggestions are informational and always remain as-is — only critical and warning findings generate fix tasks.

Adaptive Path Selection

When the user opts into autofix, determine the target based on the epic's status:

1. Read the epic doc's top-level **Status**: field.
2. If Pending or In Progress (active epic): Use the epic amendment path — append a remediation story to the epic doc.
3. If Complete or if the epic doc doesn't exist: Use the standalone task path — create Claude Code tasks directly.

Epic Amendment Path (Active Epics)

When the epic has pending work, append a remediation story to the epic doc. This keeps fix tasks within the planning artifact so cpm:do picks them up naturally.

1. Determine the next story number: Read the epic doc, find the highest **Story**: {N} number, and increment by 1.

2. Build the remediation story: Create a new ## story section from the critical and warning findings. Each finding becomes a task within the story.

   Format:

   ## Address review findings
   **Story**: {next N}
   **Status**: Pending
   **Blocked by**: —
   
   **Acceptance Criteria**:
   - Each critical and warning finding from the review has been addressed
   - Existing acceptance criteria on other stories continue to pass
   
   ### Fix: {finding summary}
   **Task**: {N.1}
   **Description**: [{severity}] {full finding text with story/task reference}
   **Status**: Pending
   
   ### Fix: {finding summary}
   **Task**: {N.2}
   **Description**: [{severity}] {full finding text with story/task reference}
   **Status**: Pending
   
   ---
   

3. Append using Edit tool: Use the Edit tool to append the new story section to the end of the epic doc (before any ## Lessons section if one exists). Always use Edit — it preserves the existing content.

4. Report: Tell the user what was added — story number, task count, and which findings were converted.

5. Update review file: Use the Edit tool to append a ## Remediation section to the review file:

   
   ## Remediation
   
   **Path**: Epic amendment
   **Target**: {epic doc path}
   **Story**: {story number} — Address review findings
   
   | # | Finding | Severity | Task |
   |---|---------|----------|------|
   | 1 | {finding summary} | {severity} | {N.1} |
   | 2 | {finding summary} | {severity} | {N.2} |
   

   Include one row per finding that generated a task. The Task column references the task number within the remediation story.

Standalone Task Path (Complete or Missing Epics)

When the epic is complete or no epic doc exists, create Claude Code tasks directly. This avoids reopening a completed planning artifact.

1. Build tasks from findings: For each critical and warning finding, create a Claude Code task:

   TaskCreate:
     subject: "Fix: {finding summary}"
     description: "[{severity}] {full finding text}\n\nSource review: {review file path}\nOriginal artifact: {epic doc path}\n{story/task reference}"
     activeForm: "Fixing: {finding summary}"
   

2. Set dependencies: If findings have a logical order (e.g. a critical finding should be addressed before a related warning), use TaskUpdate with addBlockedBy to sequence them. Otherwise, leave all tasks independent.

3. Report: Tell the user how many tasks were created and list them briefly.

4. Update review file: Use the Edit tool to append a ## Remediation section to the review file:

   
   ## Remediation
   
   **Path**: Standalone tasks (epic complete)
   **Tasks created**: {count}
   
   | # | Finding | Severity | Task |
   |---|---------|----------|------|
   | 1 | {finding summary} | {severity} | {task subject} |
   | 2 | {finding summary} | {severity} | {task subject} |
   

   Include one row per finding that generated a task. The Task column uses the Claude Code task subject.

Step 5: Pipeline Handoff

After autofix (or after skipping it), offer the user options for what to do next. The options adapt based on the epic's status.

Pre-Execution Epics (Status: Pending or In Progress)

Use AskUserQuestion with these options:

• Continue to /cpm:pivot — Use the review findings to amend the epic doc or its upstream spec. Pass both the review file path and the epic doc path as context.
• Continue to /cpm:do — Proceed to task execution. Pass the epic doc path as context. The review findings serve as informational background.
• Just exit — End the session, no handoff.

Post-Execution Epics (Status: Complete)

Use AskUserQuestion with these options:

• Continue to /cpm:retro — Feed review findings into a retrospective. Pass the review file path and epic doc path as context.
• Continue to /cpm:pivot — Use the review findings to amend the epic doc or upstream artifacts. Pass both paths as context.
• Continue to /cpm:discover — Start a new planning cycle informed by the review. Pass the review file path as context.
• Continue to /cpm:spec — Build requirements informed by the review. Pass the review file path as context.
• Just exit — End the session, no handoff.

Handoff Execution

If the user chooses a pipeline skill, pass the relevant file paths as the input context for that skill. The review file path becomes the $ARGUMENTS equivalent — the next skill should treat it as its starting context.

Delete the progress file after handoff or exit.

State Management

Follow the shared Progress File Management procedure.

Lifecycle:

• Create: before starting Step 1 (ensure docs/plans/ exists).
• Update: after each step completes.
• Delete: only after the final review file has been saved and any autofix/handoff is complete.

Format:

# CPM Session State

**Skill**: cpm:review
**Step**: {N} of 5 — {Step Name}
**Output target**: docs/reviews/{nn}-review-{slug}.md
**Input source**: {path to epic doc}
**Review scope**: {Epic | Story N}
**Agents selected**: {comma-separated agent displayNames}

## Completed Steps

### Step 1: Analyse the Artifact
{Summary — what was reviewed, story/task counts, status}

### Step 2: Conduct Adversarial Review
{Summary — finding counts by severity and concern type, key themes}

### Step 3: Write Review File
{Summary — file path written, finding totals}

### Step 4: Autofix
{Summary — path chosen (epic amendment or standalone tasks), items generated, or skipped}

### Step 5: Pipeline Handoff
{Summary — user's choice, context passed}

{...include only completed steps...}

## Next Action
{What to do next}

The "Completed Steps" section grows as steps complete. Each summary should capture the key findings and decisions in enough detail for seamless continuation.

Graceful Degradation

Every scenario below specifies an explicit action sequence ending with a visible result. No silent fallbacks.

• No roster found → Action: Fall back to single-perspective review without agent personas. Result: Report to the user: "Agent roster not found — running single-perspective review without agent personas."

• No library docs → Action: Proceed with review using only the epic doc and spec as context. Result: Report to the user: "No library documents found — reviewing with epic doc and spec context only."

• Malformed epic doc → Action: Parse what is available. Review the portions that can be parsed. Result: Report to the user: "Epic doc has structural issues: {list of problems}. Reviewing {N} of {M} parseable stories."

• Empty review → Action: Write a review file noting the artifact passed review with no concerns. Skip the autofix phase. Result: Report to the user: "Review complete — no findings. Artifact passes review."

Guidelines

• Adversarial, not hostile. The review should challenge assumptions and find real issues, not manufacture criticism. If something is well-designed, say so. Not every story needs 5 findings.
• Specific over vague. "Story 2's acceptance criteria are unclear" is useless. "Story 2, criterion 3 says 'handles errors gracefully' — what does gracefully mean? Which errors? This will be interpreted differently by different implementers" is actionable.
• Severity matters. Tag each finding at its true severity level. A genuinely critical finding (blocks execution) is rare. Most findings will be warnings or suggestions. That's fine.
• Reference the artifact. Every finding should point to a specific story, task, or acceptance criterion. Reviewers who can't point to what they're criticising aren't being helpful.
• Match depth to scope. A single-story review should take 2-3 agents and produce 3-8 findings. A full epic review should take 3-4 agents and produce 5-15 findings. Scale review depth to artifact size.