reviewing-execution

Reviewing execution

After every chunk in a plan completes, before the work is considered shipped, run an independent review of what was actually built versus what the spec required.

When you're done

Both review channels have run: dev-pipeline.js review-execution (mechanical findings) and the reviewer subagent (judgment findings). The user has triaged each finding (accept / defer / reject). If there are accepted findings requiring code work, you've offered to write a follow-up plan (back to writing-plans). If clean, you've congratulated the user and stopped.

Process

1. Confirm preconditions. All chunks in plan.tracker.json are completed. If not, point at the pending chunk(s) and stop.

2. Run mechanical findings:

   node greymatter/scripts/dev-pipeline.js review-execution <plan-path>
   

   Returns JSON: spec-coverage gaps, drift summary across chunks, cross-chunk consistency checks.

3. Dispatch the reviewer subagent. Use prompts/reviewing-execution/prompt.md. Subagent has no session history — it reviews the artifact (plan, spec, observations, drift summary), not your reasoning, and produces judgment findings (test-coverage thinness, surface-area creep, observation patterns) the verb can't compute.

4. Triage with the user. Two channels: mechanical (verb) + judgment (subagent).

   • Critical (spec requirement missing, security regression, broken contract): must be addressed before considering shipped.
   • Important: should be addressed; can be deferred with explicit user note.
   • Minor: noted for follow-up.

5. Hand off.

   • Findings requiring code → offer writing-plans for a follow-up plan (it'll roll up to the same roadmap row if applicable).
   • Clean → record the plan as shipped (status: shipped at the top of plan.md frontmatter), tell the user, stop.

What the reviewer looks for

• Spec coverage. Every success criterion implemented?
• Drift that matters. Big drift is fine if observations explain it. Big drift with no narrative is a red flag.
• Test coverage. Every chunk that added behavior has a test that fails without it.
• Surface area creep. Did chunks add public API/exports/config beyond what the spec authorized?
• Cross-chunk consistency. A function defined in chunk 2 with a different signature than chunk 7 calls it.
• Observation patterns. If three chunks all noted "had to fudge X," X is a real problem the spec missed.

Anti-patterns

• Skipping because "I reviewed each chunk as we went." Inline review is incremental; this is the integration review. Different work.
• Accepting findings without user adjudication. Findings are proposals.
• Closing out a plan with critical findings deferred. Defer important; do not defer critical. If critical can't be addressed now, the plan is not shipped.