Authoring Feature Spec

authoring-feature-spec — SKILL.md

> Variant: standard · When to use: elaborating the features a PRD names into a comprehensive, testable feature specification — to a bar the downstream build can be planned and verified from. Greenfield, or a versioned amend of an approved spec.

Overview

This skill is the how-to of writing a strong feature specification — the layer below the PRD. The PRD says what the product does and why, and names its features; the feature spec says how each named feature behaves, in enough detail to build and test. This skill carries the producer's judgment — the research method and the quality bar — not the section list. It assumes two collaborators: a feature-spec template tool that supplies the section structure, and a deep-research capability to ground each feature in evidence. The producer is handed the approved PRD (and any upstream context) and must decompose and elaborate its features — never emit generic boilerplate. The bar to clear: each feature is implementable and testable — an engineer can build it and a tester can verify it without asking the author, and planning can cut tasks from it.

The method spine is unchanged from a strong feature spec; this version deepens how you write unambiguous behavior (EARS, use-case flows, the requirements-smell catalog), makes the state-transition table and decision table explicit, adds a per-feature non-functional-requirement discipline and archetype overlays (a feature's emphasis shifts by its nature), handles probabilistic/ML features (threshold criteria, not "works"), and adds an amend method for the common case of changing an approved spec.

When to activate

• Authoring a feature spec from an approved PRD that names a set of features.
• Elaborating one feature (or a clearly-bounded set) into testable behavior, I/O, states, edge cases, and acceptance criteria.
• Amending an approved feature spec (a delta: a feature/behavior/AC/state changed or added) — you are handed the existing spec + a change request.
• Filling a feature-spec template with researched, decision-complete per-feature content.

Do NOT activate when:

• Authoring the PRD itself (problem, users, metrics, MVP boundary) → use a PRD-authoring skill. The PRD is upstream input here.
• Reviewing or grading a finished feature spec → use a feature-spec-review skill.
• Writing an engineering design doc (ADR, RFC, architecture) — that is the how it's coded layer downstream of this one.

Inputs

Read every document the plan hands you — your depends_on set (the upstream documents discovery determined inform this one) — and trace this document's content back to them. The typical upstream is the approved PRD; a UI feature may also receive user-flows / wireframes / a design-system; a data/ML feature may receive a data spec. These are method guidance, not a fixed cap. Be self-contained — produce from whatever context you actually receive; when an expected informing document is absent, proceed on what you have and surface the gap as an explicit assumption, never fabricate to fill it. And use a research capability where one is available (deep-research) to make the document comprehensive, not merely to fill the template. On an amend, you are additionally handed the existing spec + the change request (and, where the ripple must be checked, the relevant downstream docs).

Capability context (when provided): If a capability_record (a record from capability-map.yaml product_capabilities) is injected by the caller, read it before Step 1. It defines your scope boundary: owns = entities you cover; refs = entities you reference but do not own; publishes/consumes = events you surface; entry_points/exit_points = how users arrive and leave; has_ui/has_api/has_persistence = which surfaces apply. When present, treat it as a hard constraint — do not stray outside the boundary it defines.

Workflow

Step 1: Take the structure from the template tool — don't invent an outline

Get the section structure from your feature-spec template tool (comprehensive variant). Do not restate or re-derive a section list here; this skill supplies the method that fills those sections well. The comprehensive template repeats a per-feature block and carries the version header, behavior (+ a decision table), I/O + data contract, the state-transition table, edge cases, error handling, acceptance criteria, a non-functional-requirements section, dependencies, open questions, and a versioning/changelog section. If no template is available, obtain a comprehensive feature-spec structure (request/forge one, or fall back to the canonical per-feature set), then proceed. Proportionality: the template is comprehensive; your fill is proportional — a thin feature legitimately leaves the state table, decision table, NFR, or changelog empty.

If a capability_record is present: your spec MUST cover the full scope statement, all owns entities, all publishes/consumes events. MUST NOT cover refs entities or content belonging to a depends_on capability (those have separate feature-specs).

Step 2: Load the PRD; drive coverage off its feature list; identify each feature's archetype

Read the approved PRD and any upstream documents it depends on — this is your input, not a blank page. List every feature the PRD names; that list is your coverage checklist. Decompose the PRD into per-feature specs: each feature gets its own block. For each feature, name its archetype (UI · REST/API · data-ML · batch/async-job · integration/webhook · CLI — a feature may be several at once); the archetype shifts which sections carry weight (Step 4). Before drafting a feature, fill knowledge gaps about its behavior — and where the PRD is thin, make the gap an explicit open question or stated assumption, never silently generic. If a PRD feature can't even be credibly elaborated, surface it as a blocker rather than inventing behavior.

Step 3: Research to ground each feature

Use a deep-research pass to ground each feature's behavior, domain rules, and edge cases in evidence — the specific domain of this product, not "feature specs in general." If no research capability is available, do NOT fabricate behavior, limits, or error codes — state them as explicitly-flagged assumptions to validate before build.

Step 4: Apply the per-feature method

Fill the template's per-feature sections to this method. Repeat per feature; collapse a section a thin feature doesn't need (no state → no state table). Depth for each angle is in references/ — load it when a section needs the full treatment.

• Purpose & PRD trace — state the one job this feature does and link it back to a specific PRD requirement / goal / metric (forward+backward traceability). A feature with no PRD line behind it is scope creep; a PRD line with no feature is a coverage gap. Quote/reference the exact PRD item.
• Behavior & interactions — describe how the system responds observably and implementation-free (the what, not the how). Write the main success scenario as ~3–11 steps (each "actor does X → system responds Y"); then alternate flows (a different path where the goal is still met) and exception flows (a path where the goal is not met, each naming its handling). Prefer EARS phrasing per behavior statement ("When `, the system shall "; "While …"; "If , then…") — it makes the behavior atomic and maps 1:1 to an acceptance criterion. Derive the edge-case set by walking each step and asking "what can fail/vary here?". See references/requirement-and-behavior.md`.
• Decision table (combinatorial rules) — when the response depends on a combination of conditions, specify it as a conditions × rules → actions table so every combination has a defined action and missing/contradictory rules surface. (Aid; skip when behavior isn't combinatorial.)
• Inputs / outputs & data — enumerate every input (source, type, validation rule, required/optional) and every output (response shape, side effects, error codes) as a contract a caller validates against; for each input ask "what's valid, what's not, what's the boundary"; for each output, "what does the caller/UI observe." Note entities read/written and persisted vs transient.
• States & transitions — if stateful, specify a state-transition table: current state × event → next state, with a dash for an illegal transition; name initial and terminal states. The table form is what makes illegal transitions checkable.
• Edge cases & error handling — enumerate boundary/failure paths (boundary-value: just below/at/just above each limit; null/empty, duplicate/idempotency, concurrency/race, permissions/visibility, limits/overflow). Every edge case and error names its expected handling — the response/message/recovery — not just its existence. (Edge = valid-but-unusual; error = failure — name both.)
• Acceptance criteria — each behavior and key edge/error case carries criteria a tester can run pass/fail: Given/When/Then (scenario form) or a rule-based checklist. 1–3 per feature; 4+ usually means two features hide inside one — split. For a probabilistic/ML feature a deterministic G/W/T mis-fits the output — write metric-threshold criteria on a named dataset ("precision ≥ 0.85 on the `"), plus the **low-confidence/fallback** behavior and the **data requirements** (sources/ranges/balance). "The model is accurate" is not a criterion. See references/io-states-archetype-amend.md`.
• Non-functional requirements — list the applicable NFR categories for this feature, each with a numeric/checkable target (performance p95; reliability/idempotency; security/authorization; privacy; accessibility WCAG 2.2 AA for UI; limits/quotas; compatibility). Proportional — a trivial feature needs none; "should be fast/secure" is not an NFR.
• Archetype emphasis — apply the overlay for the feature's nature (UI → per-state behavior + a11y + microcopy; API → request/response schema + status/error model + idempotency + rate-limits [hand the wire contract to api-spec]; data-ML → data requirements + threshold AC + drift/fallback; batch → schedule + idempotency + partial-failure/retry; integration → delivery semantics + payload contract; CLI → args/flags + exit codes). The overlay is a what-to-cover aid, kept proportional. See references/io-states-archetype-amend.md.
• Cross-cutting (applies across features, not a section) — one idea per statement (singular), consistent terminology, no contradictions; scan each requirement/AC against the requirements-smell catalog (subjective language, ambiguous adverbs, non-verifiable/weak terms, comparatives without a referent, loopholes, open-ended "etc.") and rewrite any load-bearing hit to a quantifiable/observable statement.

Step 5: Amend an approved spec (when handed a change request)

When the input is an existing approved spec + a change request, do not regenerate the whole spec — amend it in place:

1. Scope the change — state which features/behaviors/AC/states/I-O-fields this delta touches and what is deliberately untouched.
2. Edit in place — change only the affected blocks.
3. Re-make the feature's internal chain consistent — after changing a behavior, update its AC, state table, I/O, and edge cases so the feature stays self-consistent.
4. Analyze the bidirectional ripple — upstream (does it still trace to a PRD line? if it adds an un-traced feature, flag "the PRD must be amended first"), internal (which AC/state/I-O/edge are now stale — fixed in step 3), downstream (which technical-design decisions / test cases / api-spec entries are now stale — list them as the affected set).
5. Version + changelog — bump the document's own version header; add a changelog entry (who/when/what/why).
6. Mark superseded content — mark outdated behaviors/criteria/states superseded with the reason; don't silently delete. See references/io-states-archetype-amend.md.

Step 6: Self-check against the implementability bar before handing off

Confirm all hold (this is the bar a reviewer will assert — author and reviewer share it so they don't drift):

1. Traced to the PRD — every feature maps back to a specific PRD requirement/metric; no orphan features, no uncovered PRD lines.
2. Unambiguous behavior — each behavior is interpretable exactly one way, implementation-free, observable; flows classified (main/alternate/exception); no load-bearing requirements-smell.
3. Complete I/O + states — inputs (with validation) and outputs (with shape/side-effects) enumerated; stateful features carry a state-transition table (legal cells + illegal markers); combinatorial rules carry a complete decision table.
4. **Edge cases covered with handling — null/empty, duplicate/idempotency, concurrency, permissions, limits each named with their expected error/handling**.
5. Testable acceptance criteria — each behavior/edge case has independently-testable pass/fail criteria (G/W/T or rule-based; metric-threshold for a probabilistic feature).
6. Singular + consistent — one idea per requirement, terminology consistent, no internal contradictions.
7. Feasible + plannable — buildable within stated constraints; I/O + criteria concrete enough to cut tasks/milestones from.
8. Open questions surfaced — genuine unknowns + unresolved decisions are stated openly (not papered as settled fact); design assumptions are flagged, never silent guesses.
9. Non-functional targets present where warranted — the feature's load-bearing NFR categories carry numeric targets (proportional).
10. (Amend only) delta is scoped, ripple-clean, versioned — change is in-scope, still PRD-traced (or an upstream PRD amend is flagged), the internal chain is consistent, downstream ripple is surfaced, the version + changelog are updated, superseded content is marked.

Thin-input gate: if a PRD feature's behavior cannot be researched or even credibly assumed, surface it as a blocker ("feature under-defined — needs product decision") rather than papering it with invented behavior.

Rules

Hard rules (never violate):

• Trace every feature to the PRD. No orphan feature and no uncovered PRD feature. Coverage runs off the PRD's feature list.
• Behavior is observable and implementation-free. Specify what the feature does, not how it's coded — that is the downstream design layer.
• Edge cases and errors carry their handling. Listing a case without naming its expected response is not done.
• Acceptance criteria are testable. G/W/T or rule-based (or metric-threshold for a probabilistic feature). A criterion you can't make pass/fail means the behavior isn't specified yet.
• No vague language. Replace subjective words ("fast", "robust", "user-friendly") and the smell-catalog terms with quantifiable/observable statements ("p95 < 200 ms", "returns 409 on duplicate key"). "The model is accurate" is not a criterion.
• Never fabricate behavior. Don't invent limits, error codes, or rules to look complete. With no source, state them as explicitly-flagged assumptions to validate before build.
• Compose, don't duplicate. Take the section structure from the template tool; this skill is the method that fills it.
• Elaborate the PRD, don't re-author it. Don't restate its problem/users/metrics or re-decide which features exist.
• Amend in place, don't regenerate. On a change request, edit the affected blocks, version + changelog, mark superseded, and analyze the bidirectional ripple — never silently re-emit the whole spec.
• Implementable + testable or not done.
• Capability boundary (when capability_record provided). Scope the document output to that r

…

Source & license

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

• Author: bm629
• Source: bm629/agent-skills
• License: MIT

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