Work Review

Take the approved spec, compare it point-by-point against the code you wrote, and confirm nothing was forgotten — before saying the work is finished. Complements spec-verify (which runs the mechanical checks): this skill is the line-by-line human-readable review that produces evidence (file:line), not just pass/fail.

When to use

• After completing implementation of a spec-driven task, before marking it done.
• Before merging a PR that touches spec-covered code.
• When a stakeholder asks "is this actually finished?"

Steps

1. Find the relevant specs. Identify every capability spec whose targets: match the files changed in this task:

   git diff --name-only HEAD~1
   grep -rl "targets:" openspec/specs/*/spec.md

2. Check each requirement. Walk through every ### Requirement: block in each relevant spec. For each one:

   • Read the target file(s) and confirm the requirement is implemented.
   • Record the file path and line number where it's implemented (e.g. src/auth.py:42).
   • Verify the edge cases described in the requirement's scenarios are handled.
   • Confirm the **Verified by**: [@test] <path> line points to a test that actually exercises this requirement (not just a file that happens to exist).

3. Run the linked tests and record results:

   grep -rhoE '\[@test\] [^ ]+' openspec/specs/*/spec.md | sed 's/\[@test\] //'

   If any test fails, the review cannot pass — diagnose before continuing (this duplicates part of spec-verify Step 1/4 on purpose: a review with stale results is worse than no review).

4. Capture every discovered requirement. Compare the implementation against the spec and identify every behavioral difference — not just missing pieces, but also things the code does that the spec never asked for:

   • Functions, branches, parameters, or events in the code that the spec doesn't mention.
   • Behavior that differs from what the spec describes (e.g. silently skipping vs. raising an error).
   • New error handling paths, default values, or configuration not in the spec.

   For each discovered requirement: hand it to spec-writer to add it to the relevant spec (as ### Requirement: + **Verified by**), and link any test that already covers it or flag the gap if none does.

5. Update spec metadata if structure changed. If the implementation moved, renamed, or added files: update targets: in the owning spec(s), and update any [@test] paths affected by test file moves.

6. Produce the review summary:

   ## Work Review: <capability>
   
   ### Requirements
   - [x] <requirement name> — implemented in src/foo.py:42
   - [x] <requirement name> — implemented in src/bar.py:18
   - [ ] <requirement name> — MISSING: no error handling for empty input
   
   ### Discovered requirements
   - Added: timeout handling for API calls (not in original spec)
   
   ### Test results
   - Linked tests: 5 passed, 0 failed
   
   ### Spec updates
   - Added timeout requirement to openspec/specs/<capability>/spec.md
   - Updated targets to include src/baz.py

Pass criteria

The review passes only when:

• every requirement is checked off with a file:line reference,
• every linked test passes,
• every discovered requirement has been documented in its spec (via spec-writer),
• no requirement is left as "MISSING" without an explicit decision to either fix the code or descope it from the spec.

If any of these is unmet, the work is not done — say so explicitly, do not soften it into "mostly done" or "should be fine."