reviewing-specs

Reviewing specs

Catch coherence problems and collisions with sibling specs before the plan is written. A flawed spec produces a flawed plan; reviewing late is rework.

When you're done

Every section:N in the spec body has been evaluated. The tracker records reviewed sections (status: "reviewed"). The user has either accepted findings (back to writing-specs) or declared the spec ready and you've offered to invoke writing-plans.

Process

1. Run mechanical findings:

   node greymatter/scripts/dev-pipeline.js review-spec <spec-path> [--work-root <dir>]
   

   Returns JSON of file/schema collisions across sibling specs in the same work/<initiative>/ (or roadmap row neighbors).

2. Dispatch the reviewer subagent. Use prompts/reviewing-specs/prompt.md. Pass: spec path, sibling spec paths, and the brainstorm path. The subagent produces judgment findings (internal contradictions, brainstorm drift, untestable success criteria, hidden scope) the verb can't compute.

3. Triage with the user. Two channels: mechanical (verb) + judgment (subagent). Per finding: accept (record in spec) / reject (note why) / defer (move to spec's Open threads).

4. Update the tracker. Sections that survived review unchanged → status: "reviewed". Sections the user changed → stay draft until re-reviewed.

5. Hand off. Accepted → offer writing-plans. Rejected → back to writing-specs. Stop.

Findings the reviewer looks for

• Internal contradictions. Section 3 says X, section 4 implies not-X.
• Collisions with sibling specs. Two specs claim the same module, file path, or DB table without coordination.
• Brainstorm drift. A §2 decision in the brainstorm that the spec silently overrides without surfacing the override.
• Missing rejected alternatives. §5 is empty or rote.
• Scope hidden in non-goals. "Non-goals: see Goal section" is a dodge.
• Untestable success criteria. "Should feel fast" is not a criterion.

Anti-patterns

• Reviewing inline (no subagent). Your context is full of the spec author's reasoning. The reviewer needs a clean read.
• Auto-accepting findings. Findings are proposals; the user adjudicates.
• Skipping collision check. The most common production failure mode is two specs designing for the same surface in incompatible ways. Always pull siblings.