Reviewing Feature Spec

reviewing-feature-spec — SKILL.md

Variant: standard · When to use: judging a finished feature spec as an acceptance gate — checking it is implementable and testable, then emitting VERDICT: approve|revise with actionable findings. Greenfield, or an amend (delta-scoped).

Overview

This skill is the review half of a producing/judging feature-spec pair. Loaded by a reviewer who holds a finished feature specification — the document below the PRD that says how each feature behaves — it judges that spec against one question: can an engineer build it and a tester verify it without asking the author, so planning can cut tasks from it? It applies a fixed 10-condition implementability + testability checklist (the same bar a feature-spec author produces to, so the produce-bar and the review-bar do not drift), then emits a single machine-parseable verdict plus findings the author can act on in one revision pass. It is an acceptance gate — it does not author, fix, or rewrite the spec; it judges and returns findings, and the producer revises.

The bar is single-sourced with the author. The author's techniques — EARS phrasing, decision tables, use-case flow precision, archetype overlays, the 29148 vocabulary — are aids the reviewer judges by OUTCOME (is the behavior unambiguous? is the rule-set complete? are the AC testable for this feature's nature?), never conditions to demand. Minting a condition the author doesn't produce to (e.g. "must use EARS", "must have a UI section") is the cardinal drift this skill guards against.

When to activate

• A finished feature spec needs an accept/revise decision before engineering plans or builds from it.
• You are the independent reviewer / gate for a feature spec a producer just authored.
• Re-judging a revised feature spec after a prior revise verdict.
• Reviewing an amend — an approved spec + a change request — as a delta-scoped review (cond-10).

Do NOT activate when:

• Authoring or repairing a feature spec → use a feature-spec-authoring skill. This skill never writes the spec.
• Reviewing the upstream PRD (the what/why product doc) → use a PRD-review skill. That gate judges product plannability; this gate judges per-feature implementability one layer down.
• Reviewing an engineering design document — architecture spec, design doc, ADR, or RFC → use a design-review skill. That gate verifies design claims against the codebase; this gate judges a behavior specification against an implementability bar.
• Checking template/section conformance → that is a template concern. This skill judges quality against the bar, not whether every heading is present.
• Reviewing any other document type.

Workflow

Step 1: Read the whole spec with fresh, independent eyes

Read the feature spec end to end as if encountering it for the first time, without the author's framing. Your stance is a gatekeeper for the next step (planning + build): a finding carries weight only when it shows the feature cannot be built as written or tested as written. Keep the upstream PRD (or the requirement list the spec decomposes) at hand — Step 2's first condition checks the spec against it both ways. Is this an amend? If you were handed a change request / delta against an existing spec, run the delta-scoped path (cond-10 active; scope the review to the changed blocks). On a greenfield first build no change request is present — cond-10 is n/a. Note where a behavior, input, edge case, acceptance criterion, state, or NFR is load-bearing; those are the spots the checklist scrutinizes.

Step 2: Run the implementability + testability checklist — judge each condition

For each condition below, decide pass or gap. A condition fails only on a real, named deficiency — "I'd have phrased it differently" is not a gap. For each gap, capture the exact location and what is missing (Step 4 turns it into an actionable finding). The conditions are the single-sourced bar; do not add private ones.

The capability-boundary checklist item (below) applies ONLY when a capability_record was injected into the authoring invocation and is available as review context. When absent, treat it as n/a — do not penalise a document for lacking capability-boundary markers when no boundary was defined.

1. Traced to the upstream need. Every feature maps back to a specific PRD goal / requirement / metric, and every upstream feature line is covered by a spec section — check both directions. A feature with no upstream line is an orphan (scope creep); an upstream line with no feature is a coverage gap. Gap on an orphan, an uncovered line, or unstated/unreconstructable traceability. (Non-collapsing baseline — at any size a feature serving no PRD line is broken.)

2. Unambiguous + observable behavior. Each behavior is interpretable exactly one way, stated as an observable system response, and implementation-free. Flows are coherent (a main success scenario; branches classified alternate-vs-exception). Gap when a behavior could be built two ways from the same words, has no observable output, smuggles in an implementation choice, or rests on a load-bearing requirements-smell (subjective/weak/ambiguous term, comparative without a referent, loophole, open-ended "etc."). (Non-collapsing baseline.)

3. Complete inputs / outputs / states. Every input enumerated with source, type, validation, required/optional; every output with shape/response + side effects; a stateful feature carries a state-transition table (every (state,event) cell a defined next-state or an explicit illegal-marker; initial/terminal named); a combinatorial feature's rule-set is complete (no input combination leaves the behavior undefined). Gap when a validation/output shape is missing, a stateful feature leaves transitions to guess, or a rule combination has no defined action. (Collapse: a stateless feature has no state table; a non-combinatorial feature no decision table — not gaps.)

4. Edge cases + error handling present, each with its response. The standard boundary/failure paths are addressed — null/empty, duplicate/idempotency, concurrency/race, permissions/visibility, limits/overflow (boundary-value at each limit) — and each named edge case states its expected handling. Gap when an applicable edge case is absent, or listed without saying what the system does. (Collapse: a thin feature has a smaller failure surface — fewer edge cases is fine; the edge-carries-handling rule itself is a non-collapsing baseline.)

5. Independently testable acceptance criteria. Each behavior + edge case carries pass/fail criteria a tester could execute without asking the author — Given/When/Then or a rule-based checklist. For a probabilistic/ML feature, a deterministic G/W/T mis-fits the output: a metric-threshold criterion on a named dataset (precision/recall/latency ≥ X) + the low-confidence/fallback behavior is testable and passes; a deterministic "the model is accurate"/"results are relevant" is the vague criterion this condition rejects. Gap on a vague/subjective criterion with no measurable pass/fail, or a behavior with no criterion. 4+ criteria in a section is a split smell — flag, not an auto-block. (Non-collapsing baseline.)

6. Singular + consistent. Each requirement states one idea (split an "and"), terminology is consistent, no internal contradictions. Gap on a compound requirement, a term that shifts meaning, or two sections that contradict. (Collapse: a short spec has fewer surfaces — but consistency holds at any size.)

7. Feasible + plannable. Buildable within stated constraints; inputs/outputs + criteria concrete enough that planning can cut tasks/milestones. Gap when a stated constraint makes a required behavior impossible, or the spec is too abstract to estimate/sequence.

8. Open questions surfaced, not buried. Genuine unknowns are stated openly, not papered as silent assumptions presented as settled fact. Gap when the spec reads as falsely complete — an obvious undecided point is absent or asserted as decided.

9. Non-functional requirements present where the feature warrants them. The load-bearing non-functional categories for the feature (performance, reliability/idempotency, security/authorization, privacy, accessibility WCAG 2.2 AA for UI, limits/quotas, compatibility) carry a numeric/checkable target; a vague "should be fast/secure" on a feature whose nature demands a target is a gap. (Collapse: a trivial feature legitimately needs none; only the applicable few are expected — never demand a category the feature doesn't warrant. A deliberately best-effort NFR, stated as such, is not a gap.)

10. (Amend only) delta is well-scoped, ripple-clean, versioned. When reviewing a change against an existing spec: the delta meets conditions 1–9 on the blocks it touched; the changed/added feature still traces to a PRD line (or an upstream-PRD-amend-needed is explicitly flagged); the document's own version is bumped + a changelog entry (who/when/what/why) present; superseded content is marked, not silently deleted; no internal or downstream trace is left dangling (the affected technical-design/test-plan/api-spec set is named). Gap on an un-scoped delta, a broken trace, missing change history, or a silent deletion. (Collapse: on a greenfield first build this condition is n/a — do NOT full-re-review an unchanged spec, and do NOT demand a changelog on a first draft.)

11. Capability boundary (n/a when no capability_record): all owns entities covered; all publishes events triggered; all consumes events handled; no coverage of refs entities; scope statement negative clause honored.

Proportionality. "Complete enough to build and test from" scales with the feature. A thin feature legitimately collapses sections it does not need — no states → no state table; no combinatorial logic → no decision table; no failure surface → fewer edge cases; trivial → no NFR; first draft → no changelog. Judge completeness-of-decisions, not word count or template-section presence. A small, complete spec that satisfies every applicable condition passes. Do not manufacture a gap from brevity.

Step 3: Decide the verdict

• approve — every applicable condition passes. An engineer can build, and a tester can verify, this feature as written; planning can derive tasks from it. Approve even if you can imagine stylistic improvements; the bar is implementability + testability, not perfection.
• revise — one or more conditions have a real, named gap that blocks building or testing (an orphan feature, an ambiguous behavior, a missing edge-case response, an untestable criterion, an undefined state transition, a missing load-bearing NFR target, an un-scoped/ripple-broken amend, etc.).

Do not revise to signal effort or to request nice-to-haves. A condition is either met or it isn't.

Step 4: Emit the verdict + actionable findings

Emit the verdict as a single line — the literal text VERDICT: approve or VERDICT: revise, on its own line, with no surrounding code fences, quotes, or extra words (the fences here are illustration only):

VERDICT: approve

Then, on the following lines, list findings. On revise, every finding is actionable — the failed condition, the exact location, and how to fix it — so the author can resolve it in one pass. On approve, findings are optional non-blocking notes; do not let them imply a revision is required.

A good finding names the gap and the fix:

revise — Acceptance criteria (cond. 5), "Rank results" feature: the only criterion is "the relevance model is accurate," which a tester cannot run pass/fail. Fix: state a metric threshold on a named dataset, e.g. "on the 2026-Q2 holdout, precision@10 ≥ 0.80," plus the low-confidence fallback.

A bad finding is vague and unactionable:

The acceptance criteria could be more thorough. (Which feature? Why does it fail the bar? What fixes it?)

Rules

Hard rules (never violate):

• Emit exactly one verdict line, VERDICT: approve or VERDICT: revise — that literal token, on its own line, nothing else on it. Downstream tooling parses it.
• Judge, never author. Return findings; do not rewrite, fix, or fill in the spec. The producer revises.
• Single-sourced bar. Judge against the ten conditions in Step 2 — the same bar the author produces to. Do not invent extra conditions or apply a stricter private standard.
• Aids are judged by outcome, never demanded. EARS, decision tables, the use-case format, archetype overlays, the 29148 vocabulary are the author's techniques — judge whether the behavior is unambiguous / the rule-set complete / the AC testable, NEVER "you didn't use EARS / add a UI section / draw a decision table." This is the cardinal no-drift rule.
• No false-revise. A spec that meets every applicable condition is approved, even a thin one for a small feature. Revise only on a real, named gap. A thin feature legitimately omits NFRs, a state table, a decision table, a changelog.
• No false-approve. Never approve over a genuine gap to be agreeable. A blocking gap is a revise.
• Edge case without a response is a gap (cond. 4). The builder must not be left to invent the behavior.
• Judge against the upstreams the document was given. Assess the document against its depends_on set. A not-produced upstream is never a revise trigger. A document that ignored a produced upstream it should have drawn on is a fair finding.
• Amend is delta-scoped. When handed a change against an existing spec, review the delta + its ripple (cond-10) — do NOT full-re-review the unchanged spec, and do NOT demand a changelog on a greenfield first draft.
• Every revise finding is actionable — failed condition + location + concrete fix.

Preferences (override-able):

• Order findings by severity — blocking gaps first, then minor ones.
• Reference the condition number/name in each finding so the author maps it back to the bar.
• Keep approve-notes few and clearly non-blocking.

Gotchas

• Approving for completeness instead of buildability. Every section can be present and the feature still un-buildable (ambiguous behavior, edge cases with no response, untestable criteria). Judge whether the feature can be built and tested, not whether the template is filled.
• The listed-but-unhandled edge case. A spec that enumerates null/empty, duplicate, concurrency, and limit cases looks thorough — but if it does not say what the system does for each, the build is still under-specified (cond. 4).
• Deterministic bar on a probabilistic feature. Don't reject a metric-threshold-on-a-dataset criterion for "not being Given/When/Then" — for a model/ranker that IS the testable form (cond. 5). Conversely, "the model is accurate" is a real gap.
• Inventing conditions (the cardinal drift). Adding a private requirement the bar does not carry ("it should use EARS / have a sequence diagram / a rollout plan / a UI section") drifts the review-bar off the produce-bar and causes spurious revises. The aids are judged by outcome only.
• Systematic over-flagging (false-revise). A reviewer asked to find problems tends to over-correct, judging sound specs as defective. A condition is a gap only on a named, real deficiency, not a sentence you'd have written differently.
• False-revise on a thin feature. A small feature's spec is correctly short; collapsed sections it doesn't need (no states, no NFR, no decision table, no changelog) are not gaps.
• NFR/amend over-demand. Don't demand an NFR category the feature doesn't warrant (cond. 9 is proportional), and don't apply cond-10 to a greenfield draft.
• Confusing this with the PRD gate or design-review. A feature spec is judged for per-feature implementability — one layer below the PRD's product plannability and distinct from an engineering design-doc's code-consistency review.
• Verdict token drift. "Approved", "LGTM", "needs work", or a verdict buried mid-paragraph will not parse. Emit the literal VERDICT: approve|revise on its own line.

Anti-patterns

• Rubber-stamp approve. Skimming and approving to avoid a revise loop — an ambiguous behavior or an unhandled edge case waved through becomes a defect or a mid-build scramble.
• Nit-pick revise. Blocking on wording, formatting, or nice-to-haves dressed up as gaps. Revise is for real implementability/testability blockers only.
• Silent rewrite. "It was easier to just fix it" — authoring inside a review collapses the produce/judge separation.
• Inventing conditions. Adding a requirement the bar does not carry (a named technique, a section demand) — the dominant drift this gate guards against.
• Full-re-reviewing an amend. Re-judging the whole unchanged spec on a small delta — review the delta + its ripple (cond. 10), proportionally.
• Hedged verdict. "Mostly approve but…" or two verdict lines. Exactly one decision, exactly one token.

Output

A single review result for one feature spec:

• One verdict line — VERDICT: approve or VERDICT: revise, verbatim, on its own line.
• Findings — on revise, one actionable finding per blocking gap (failed condition + location + concrete fix); on approve, optional non-blocking notes.

The abstract consumer is whatever orchestrates the produce→review loop: approve accepts the spec for the next phase (planning / build); revise returns the findings to the producer for a bounded revision pass. Medium: the artifact judged is a textual-markdown feature spec today; the bar is medium-independent.

Related

• A feature-spec-authoring skill — the produce half of the pair; it writes the spec to the same 10-condition bar this skill judges against. Pairing them single-sources the bar so produce and review do not drift.
• A PRD-review skill — the gate one layer up, for the product requirements document (what/why). Distinct doc, distinct bar.
• A design-review skill — the gate for engineering design documents (architecture specs, ADRs, RFCs), which verifies claims against the codebase. Distinct gate, distinct bar.
• A feature-spec template / content-template tool — owns the section structure; this skill judges quality against the bar, not structural conformance.

Progressive disclosure

• references/implementability-bar.md — the ten checklist conditions expanded with per-condition pass/gap signals, the standard edge-case checklist, the state-table + decision-table + probabilistic-AC + NFR + delta-scoped-amend signals, and worked finding examples. Load when a borderline condition needs a sharper pass/gap call.
• references/sources.md — research provenance for the review method (requirement-quality standards, EARS, BDD/Gherkin, INVEST, traceability, edge-case + probabilistic-AC + change-impact technique, reviewer-overcorrection evidence).

Body budget

• description ≤ 1,024 chars (agentskills.io cap); combined description + when_to_use truncated at 1,536 chars in the listing.
• Body ~500 lines / 5,000 tokens (soft target — quality takes precedence; flag if consistently over 700 lines / 7,000 tokens) — kept in context every turn.
• Per reference file: warn >10k tokens, error >25k. Total references: warn >25k tokens, error >50k.