Spec Review

Purpose

Stage: Spec — the last skill before the human Spec sign-off. In the autonomy model the downstream run is fully autonomous: acceptance.md (plus the rest of the signed bundle) is the sole human-anchored oracle the agent cannot out-vote. A human reviewing a spec littered with stray file paths, dangling ADR refs, placeholder TODOs, and coverage gaps burns scarce attention on mechanical defects instead of the judgment calls only a human can make. spec-review is a fresh, code-cold agent (maker≠checker) — never the agent that authored the spec — that fixes the spec before the human sees it: decidable facts are silently corrected; contestable judgment is corrected and flagged inline. The human then reviews a clean spec and spends attention where it counts. The silent-re-authoring risk is resolved by making judgment changes visible, not by withholding the fix.

When to use / when to skip

Use: runs last in Spec, after spec-grilling (ADRs/CONTEXT.md), to-prd (prd.md), acceptance-criteria (acceptance.md), environment-manifest (environment.md), and — when the feature has UI — frontend-design (the signed design contract) have all landed; immediately before the human Spec sign-off.

Skip / boundaries (depth: lite escape hatch):

• It is not a third gate. It signs nothing and blocks nothing; the human still reviews and signs.
• Do not skip because "the spec looks clean" — the entire value is a fresh code-cold relational read

that catches what the author cannot see in their own work.

• For a one-artifact trivial fix with no cross-artifact relation, a single inline pass without the full

bundle is acceptable — but the default is the full relational grade anchored on intent.md.

Inputs

Read the full Spec bundle in this order — intent.md first (everything is graded relationally against what the user actually asked for):

1. intent.md (interview-me / idea-refine) — Outcome · User · Why · Success · Constraints · Out-of-scope.

Read first; it is the oracle of intent.

1. ADRs (docs/adr/ADR--*.md) + CONTEXT.md (spec-grilling) — referenced design substrate.
2. prd.md (to-prd) — Problem · Solution · User Stories · Implementation Decisions · Testing Decisions ·

Out of Scope.

1. acceptance.md (acceptance-criteria) — Given/When/Then scenarios, behavioral-only, feature-namespaced ids

(e.g. PWR-A1) back-referencing a story id.

1. environment.md (environment-manifest) — typed rows, closed kind enum {env-var|mcp|service|runtime-dep|fixture|

account}; no value column, no command column.

1. design contract (frontend-design) — only if the feature has UI; the 5th signed Spec artifact.

Refuse to run if the minimum bundle (intent.md + prd.md + acceptance.md) cannot be resolved — without intent.md there is no oracle to grade against. Missing optional items (ADRs, or the design contract on a non-UI feature) are soft warnings; proceed. Run as a fresh, code-cold subagent: the agent that authored these artifacts must NOT be the one reviewing them (maker≠checker; cr-evaluator §"Why this stage exists").

Process

1. Dispatch a fresh, code-cold subagent. No author memory, no conversation history from spec-grilling/

to-prd. Read the bundle in the order above — intent.md first.

1. Grade relationally. For each downstream artifact ask: does it deliver what intent.md asked for?

Walk the four classic axes (placeholders · internal consistency · scope · ambiguity) PLUS the artifact-boundary rules and the coverage ledger.

1. Classify every issue as Decidable (fact) or Contestable (judgment) — see the split table.
2. Decidable facts → auto-fix in place, then re-run the deterministic re-check (grep) until it

converges. Greppable, so it converges cheaply. No inline flag — it was simply wrong.

1. Contestable judgment → apply your best correction in place too, but mark each change inline:

``. No loop — one pass; the human is the convergence point.

1. Hand back the cleaned spec + write spec-review.md (auto-fixes, flagged judgment changes, coverage

ledger, "open the referenced ADRs" list). Tell the human: review the fixed spec, judgment changes are flagged inline, you keep final authority — revert any.

The fact / opinion split

| Issue | Class | Action | |---|---|---| | File path / signature / driver-or-library internal appears in prd.md (prd MUST NOT contain these) | Decidable | Strip it; re-home to an ADR reference. Re-check: grep prd.md for paths/extensions/signatures. | | Dangling see ADR-NNN — referenced ADR file does not exist | Decidable | Fix the ref or create the missing ADR pointer. Re-check: cross every ADR-\d+ in prd.md against docs/adr/. | | CONTEXT.md ## Glossary term used non-verbatim in prd.md | Decidable | Normalize to the exact ## Glossary term (prd uses CONTEXT terms verbatim). | | Placeholder / TODO / TBD / incomplete section | Decidable | Fill from context or remove. | | Value or command embedded in environment.md (no value column, no command column — structurally illegal) | Decidable | Remove. If it is a real secret → also a security STOP (see Red flags). | | acceptance.md scenario contains a file path / signature / table (behavioral-only) | Decidable | Rewrite as an observable outcome. | | Acceptance coverage gap: a prd.md user story or intent.md success-criterion with no scenario (every story must map to ≥1 reachable scenario) | Contestable | Draft the missing scenario; flag it inline. | | ADR-worthiness: a hard-to-reverse ∧ surprising decision buried in prd prose instead of an ADR | Contestable | Propose extracting an ADR; flag. | | One feature or two: intent.md describes two independent subsystems crammed into one spec | Contestable | Propose the split; flag. | | Internal contradiction between prd.md and an ADR or acceptance.md | Contestable | Reconcile to one side; flag the chosen side. |

ADR-open check (risk mitigation / handoff)

Design now lives in referenced ADRs that the single Spec gate does not name — so the gate could rubber-stamp design it never opened. spec-review closes that gap: verify every see ADR-NNN in prd.md (a) resolves to a real ADR file (decidable) and (b) was surfaced inline by to-prd; then put the full list of referenced ADR ids into spec-review.md under ## Open the referenced ADRs so the human opens each at the gate. ADR cross-refs are immutable once written — rename/supersede → update referrers in the same commit.

Rationalizations

• "The spec looks clean, I'll skip the relational pass." → The whole value is a fresh code-cold read;

the author can't see their own gaps. Do the full grade against intent.md.

• "I'll just list the issues for the human." → No. Hand back a cleaned spec, not a punch-list.

Apply the fix.

• "This judgment call is too risky to change." → Apply your best correction and flag it inline; the

human reverts if they disagree. Withholding the fix IS the failure mode.

• "I'll loop on the judgment fixes until they're perfect." → No loop on contestable items — the human

is the convergence point. Only decidable facts get the deterministic re-check loop.

• "I wrote this spec, I can review it." → maker≠checker. A fresh code-cold agent reviews, never the author.

Red flags

• You are the agent that authored the spec → STOP; dispatch a fresh code-cold subagent.
• You are producing a list of complaints instead of edits → STOP; fix in place.
• You are looping on a judgment call → STOP; one pass, flag, move on.
• You silently re-authored a contestable section with no inline flag → STOP; every judgment change

must be visible.

• intent.md is absent → refuse to run; there is no oracle to grade against.
• An embedded value in environment.md looks like a real, committed secret → remove it from the manifest

AND treat the exposure as a security STOP per security.md (hard halt + surface to the human).

Verification (ending criteria)

Done when ALL hold:

• Every decidable check greps clean: no file paths/signatures in prd.md; no dangling ADR-NNN; no

non-verbatim ## Glossary terms; no placeholders/TODO/TBD; no value/command in environment.md; no behavioral-only violations in acceptance.md.

• Every contestable change is applied and carries an inline `` flag.
• Every acceptance.md scenario id back-references a story id, and every story / intent.md

success-criterion maps to ≥1 scenario (coverage ledger has no orphan story).

• spec-review.md written with the four stable sections, including ## Open the referenced ADRs.
• The bundle is handed back cleaned (not a punch-list); the human is told judgment changes are flagged

and they keep final authority.

Outputs & handoff contract

• Emits — fixed spec: the bundle artifacts (prd.md, acceptance.md, environment.md, CONTEXT.md,

ADRs) edited in place; decidable facts silently corrected, contestable judgments corrected + inline-flagged.

• Emits — spec-review.md: ephemeral, OUT of the resume-spine (not a chain link). Stable

sections: ## Auto-fixed (facts) · ## Flagged (judgment — revert if you disagree) · ## Coverage ledger (scenario↔story map + any not-reachable classification) · ## Open the referenced ADRs.

• Not a gate: spec-review does not flip STATE.md feature state. The human Spec sign-off does that

(feature spec → plan); spec-review runs immediately before it.

• Stable-section discipline: it reads consumer artifacts' stable sections (per the registry) and edits

those sections in place — it never invents a new artifact or a new stable section.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: celestialdust
• Source: celestialdust/achilles-skills
• License: MIT

Install and usage instructions live in the source repository linked above.