review-breakdown

name	review-breakdown
description	Audit a breakdown before anyone builds it: dependency ordering, task sizing, coverage gaps, overlapping boundaries, missing tests. Read-only; returns PASS or NEEDS REVISION. Use immediately after breakdown.

Review Task Breakdown

Validate a task breakdown produced by /spec:breakdown before starting implementation. Catch structural issues that would cause failures mid-execution.

Step 0: Parse arguments

Extract the spec file path or task folder from the first token. If given a spec file, locate its child spec directory (sibling directory with matching name, e.g., specs/shared/visual-identity/ for visual-identity.md). If given a directory, locate the parent spec (the .md file in the containing directory whose name matches the directory).

Step 1: Load the breakdown

1. Read the parent spec in full. Parse its YAML frontmatter to extract title, status, depends_on, affects, effort.
2. Read every child spec file in the subdirectory. Parse each child's YAML frontmatter — extract title, status, depends_on, affects, effort, dispatched_task_id.
3. Read specs/README.md for track context and cross-spec dependencies.

Step 2: Check dependency correctness

For each child spec's depends_on list in its YAML frontmatter:

• Verify every path in depends_on resolves to an existing spec file.
• Verify no self-dependency (a spec cannot list itself in depends_on).
• Verify no circular dependencies in the DAG (topological sort must succeed).
• Verify dependency direction: if spec B modifies a function that spec A creates, B must depend on A. Cross-reference affects lists to catch this.
• Flag missing dependencies: if two child specs have overlapping affects paths, check whether they need ordering.
• Verify depends_on edges that cross subtrees or tracks are intentional and the target spec exists.

Report: list of dependency issues, or "Dependencies: OK".

Step 3: Check task sizing

For each child spec, estimate scope by examining the affects list from frontmatter and the "What to do" section in the body:

• Read each file in affects to check its size and complexity.
• Cross-check effort (small/medium/large/xlarge) against actual scope:
  • small with 6+ files in affects is suspicious.
  • xlarge with only 1-2 files may be over-estimated.
• Flag specs whose "What to do" has fewer than 3 steps as potentially too small (might be foldable into a sibling spec).
• Flag specs that create new packages AND refactor existing code (should usually be split).
• Verify leaf specs are small enough for one agent task (2-5 files, one clear goal) per the spec document model.

Report: list of sizing concerns, or "Sizing: OK".

Step 4: Check spec coverage

Compare the spec's implementation plan against the task breakdown:

• For each item in the spec (sections, bullet points, requirements), check that at least one task covers it.
• Flag spec items with no corresponding task.
• Flag tasks that don't trace back to any spec item (scope creep).

Report: uncovered spec items and untraceable tasks, or "Coverage: OK".

Step 5: Check boundary conflicts

For each pair of child specs that have overlapping affects paths in their frontmatter:

• Check that their "Boundaries" sections don't overlap (both claiming to modify the same function or type).
• Check that the later spec's "What to do" accounts for changes made by the earlier spec (follow the depends_on ordering).
• Flag cases where two independent specs (no depends_on edge between them) share affects entries — they may conflict during parallel execution.

Report: list of boundary conflicts, or "Boundaries: OK".

Step 6: Check test completeness

For each task:

• Verify the "Tests" section exists and is non-empty.
• Check that test cases cover the "Goal" (not just the mechanics of "What to do").
• Flag tasks that modify existing behavior but only test new behavior.

Report: list of test gaps, or "Tests: OK".

Step 7: Verify the critical path

Compute the critical path through the dependency graph:

• Identify the longest chain of sequential tasks.
• Flag if the critical path has more than 6 tasks (may indicate missing parallelism opportunities).
• Identify tasks with no dependents that could be reordered earlier.

Report: critical path length, parallelism opportunities.

Step 8: Summary

Present a structured report:

## Breakdown Review: <spec-name>

Tasks: N total, N phases
Critical path: N tasks deep
Parallelism: up to N tasks can run concurrently

### Issues Found
- [ ] <issue description with task references>
- [ ] <issue description>

### Recommendations
- <suggestion for improvement>

### Verdict: PASS / NEEDS REVISION

If issues are found, list specific remediation steps. Do NOT modify any files — this skill is read-only. The user decides whether to revise manually or re-run /spec:breakdown with feedback.