spec-review

Overview

This skill compares what you built against what you planned. It parses a PRD or requirements document into atomic, checkable requirements, scans the codebase for evidence of implementation, and produces a coverage report with gap analysis. On subsequent runs, it detects spec drift — requirements that were added, removed, changed, or reprioritized since the last review.

Why this matters: Projects are non-linear. Requirements drift, features get descoped, priorities shift. Without periodic validation, teams build the wrong thing or miss critical features. The best time to checkpoint is at natural boundaries — review completion, spec update, sprint end.

Required References

Before starting, read these references for detailed strategies:

• references/requirement-decomposition.md — how to parse PRDs into checkable items
• references/coverage-analysis.md — codebase scanning strategies
• references/drift-detection.md — snapshot diffing, drift classification

Mode Detection

Determine the operating mode from the argument and stored state:

Input	Stored requirements.json?	Mode
File path, URL, or text	No	A: Baseline — parse PRD, scan codebase, produce initial coverage
File path, URL, or text	Yes	B: Drift + Coverage — detect spec drift, re-scan, compare
rescan or no argument	Yes	C: Rescan — re-scan codebase against stored spec
No argument	No	Error — ask user for PRD

Storage location in the target project:

.context/spec/
├── spec-snapshot-<timestamp>.md     # Immutable PRD copies
├── requirements.json                 # Decomposed requirements (mutable)
├── coverage-<timestamp>.json         # Coverage scan results
└── drift-log.jsonl                   # Append-only drift entries

Step 1: Parse and Decompose Requirements (Modes A, B)

1. Read the PRD source:
   • If the argument is a file path (contains / or .md or .txt or .pdf): Read with the Read tool
   • If the argument is a URL (starts with http): Fetch with WebFetch
   • Otherwise: treat the argument as inline text