review-draft-spec

name

review-draft-spec

description

Multi-agent review of a draft spec in `context/plans/drafts/`. Spawns two parallel reviewers — a broad reviewer and a codebase-anchor reviewer that fact-checks every named identifier against source. Auto-applies mechanical fixes via a GPT 5.5 worker with medium reasoning effort unless --no-auto-apply is set. Recommends apply / re-review / promote. Use after a draft session, or when a human wants to validate before promoting to ready/.

Review Draft Spec

Two reviewers in parallel. One broad, one anchored to source. Aggregate findings, auto-apply mechanical fixes, recommend whether to apply more, re-review, or promote.

Process

1. Locate the spec

Argument is the plan folder name (e.g. entity-model-foundation) or a full path. If absent, list drafts and ask which one:

!`ls context/plans/drafts/`

Resolve to context/plans/drafts/<name>/index.md.

2. Read the spec once

Read the full spec yourself before delegating. Decisions about which reviewers to run depend on what the spec contains. Reviewer prompts inline the spec content — don't pass paths and assume agents will read them. Paths drift.

3. Run reviewers in parallel

One message, two Agent tool calls. No sequential rounds.

Broad reviewer (GPT 5.5 high reasoning effort)

Receives:

• Full spec content inline
• The relevant context/lib/ slices for subsystems the spec touches (route via context/lib/index.md)
• Instructions to find:
  • Contradictions within the spec
  • Casing or boundary inconsistencies
  • AC ↔ task gaps in either direction
  • Scope-boundary violations
  • Plumbing handwaves — "edit X to do Y" without stating how X gets access
  • Missing wire-format or FFI pins
  • Anything else that forces an implementer to guess

Output: list of { location, problem, fix } triples. "No issues found" if clean. No padding, no praise.

Codebase-anchor reviewer (GPT 5.5 high reasoning effort)

Receives:

• Full spec content inline
• Instruction: "For every Rust/TS/Lua identifier the spec names — function, struct, type, field, enum variant, module path — open the file in source, confirm the spec's claim, report any divergence between the spec and current code reality. First step: extract the identifier list from the spec. Then resolve files via Glob/Grep. Then batch-read."

Output: same { location, problem, fix } triples. Each fix references the source location that contradicts the spec.

4. Aggregate

Collect both reports. Dedupe — when the same issue surfaces from both lenses, keep the codebase-anchor framing (more precise).

Triage by severity:

Severity	Meaning
Blocker	Implementer cannot proceed without guessing
Complicates	Implementer can guess but might guess wrong
Nit	Style, voice, minor inconsistency

Then split into two buckets:

Bucket	Examples	Default action
Mechanical	Casing fix, missing AC bullet, wire-format pin, deletion of stale phrase	Auto-apply via model: "gpt-5.5" with reasoning_effort: "medium" (unless --no-auto-apply)
Architectural	Reshape a contract, decide between two paths, change scope	Surface to caller; do not auto-apply

Triage is a 30-second judgment, not a heuristic. Make the call inline. Don't delegate it to a sub-agent.

5. Apply mechanical fixes

If any mechanical findings exist and --no-auto-apply is not set:

Spawn one worker agent with model: "gpt-5.5" and reasoning_effort: "medium", passing a numbered list of { location, problem, fix } items. One Edit per item. Match the existing prose voice — terse, direct, no rewrites of surrounding paragraphs.

After the agent reports back, re-read the spec to confirm edits landed.

6. Decide next action

Outcome	Recommendation
No findings, or only nits already auto-applied	Promote to ready/
Mechanical fixes applied, no architectural findings	Re-run this skill once to verify fixes are clean
Architectural findings present	Surface to caller with locations and suggested directions. Do not auto-apply. Do not recommend promotion.
Findings only emerge from source-reading; spec text alone reveals nothing	Spec has hit diminishing returns. Promote.

Last row is the explicit stopping rule.

7. Report

Concise. Include:

• What reviewers ran
• Total finding count by severity (Blocker / Complicates / Nit)
• What was auto-applied (count, not full list — caller can read the diff)
• What needs the caller's attention (architectural findings, full text)
• The recommendation

Cap at ~15 lines unless architectural findings demand more.

Flags

• --no-auto-apply — surface mechanical findings to caller instead of editing. Default for human-in-the-loop use.

Working rules

• Don't pad. Every sentence earns its place.
• No emojis anywhere — skill or prompts.
• Reviewer prompts inline the spec content. Paths drift.
• Tables for mappings, prose for behavior.
• Voice match draft-plan.