agent-skills/skills/write-feature-specification/SKILL.md

name, description

name	description
write-feature-specification	Use when turning a feature request into a bounded, technology-independent specification before technical planning or implementation begins.

Write a Feature Specification

Write the contract for what users need and why, not how engineers will build it. The result must let a product reviewer judge scope and let a tester derive acceptance tests without choosing a language, framework, database, API shape, or module layout.

1. Extract the request

Read the request and any governing project principles. Write down, internally:

• actors and their goals;
• actions and observable outcomes;
• information created, read, changed, or deleted;
• explicit constraints and exclusions;
• dependencies and stated business outcomes.

If no actor, goal, or observable journey can be recovered, stop and ask for the missing feature intent. Do not manufacture a specification from a technology request alone.

Separate intent from implementation. Preserve domain terms such as OAuth or PDF when they are part of the user-visible requirement, but replace implementation prescriptions with outcomes unless the prescription is itself a binding external constraint.

2. Bound uncertainty

Fill ordinary gaps with reasonable defaults and record each one under Assumptions. Ask only when all three are true:

1. the answer materially changes scope, security/privacy, user experience, or acceptance;
2. at least two reasonable answers have different consequences;
3. no safe, conventional default follows from the request or project context.

Keep at most three unresolved clarification markers in a first draft. Prioritize scope, then security/privacy, then user experience; defer technical choices to planning. Use this exact form:

[NEEDS CLARIFICATION: Which account roles may approve a refund?]

Do not ask about routine error messages, conventional accessibility, or a particular integration style when a documented assumption can bound them.

3. Write prioritized, independent journeys

Order journeys P1, P2, P3 by delivered user value, not implementation order. Each journey must remain a viable demonstrable slice if later journeys do not exist.

### User Journey 1 — Recover access (Priority: P1)

A registered user who cannot sign in can regain access without support staff.

**Why this priority:** Locked-out users cannot use any other account feature.

**Independent test:** Starting from a recoverable account, the user regains access and can sign in without any P2 capability.

**Acceptance scenarios:**

1. **Given** a recoverable account, **When** the user completes the recovery challenge, **Then** the user can set new credentials.
2. **Given** an expired challenge, **When** it is submitted, **Then** access is not changed and the user is told how to request a new challenge.

Reject journeys that are layers (“build database”), components (“create settings page”), or dependencies (“add API”). Split journeys by independently valuable outcomes. For each journey include the priority rationale, an independent-test statement, and Given/When/Then acceptance scenarios.

4. Enumerate edge cases

Cover only relevant classes, but scan all of them:

• empty, first-use, and no-results states;
• minimum/maximum values and volume limits;
• invalid, stale, duplicate, or partial input;
• authorization and ownership boundaries;
• concurrent or conflicting changes;
• dependency failure, timeout, and recovery;
• interruption after partial state mutation;
• accessibility, locale, and time-zone boundaries;
• deletion, retention, and irreversible actions.

State the required outcome, not “handle gracefully.” If the outcome is intentionally undefined or out of scope, say so explicitly.

5. Write testable requirements

Give each requirement a stable ID and one obligation:

- **FR-001:** The system MUST allow an account owner to revoke any active recovery challenge.
- **FR-002:** A revoked or expired challenge MUST NOT change account credentials.

Use MUST, MUST NOT, or MAY deliberately. A requirement is testable only if two reviewers can agree whether an observed outcome satisfies it. Replace vague words such as “fast,” “secure,” “easy,” “appropriate,” and “robust” with a defined outcome, metric, or named governing standard.

Keep these separate:

• requirements describe mandatory behavior;
• acceptance scenarios demonstrate journeys;
• success criteria measure whether the feature achieves its outcome;
• assumptions disclose defaults chosen because the request was silent.

Do not bury new requirements inside prose or edge-case questions.

6. Define entities without designing storage

When the feature manages information, describe domain entities, their identity, essential attributes, relationships, ownership, and lifecycle. Do not name tables, classes, serialization formats, or databases.

- **Recovery challenge:** A time-bounded proof associated with one account; has an issued, used, revoked, or expired state. Only one successful use is permitted.

Omit the section when the feature introduces no meaningful data concept.

7. Define measurable success

Include a balanced set of user, scale/performance, quality, and business outcomes where relevant. Criteria must be measurable, verifiable without knowing the implementation, and phrased from the user or business perspective.

Good:

- **SC-001:** At least 90% of test participants complete account recovery on the first attempt.
- **SC-002:** A recovery attempt produces its next user-visible response within 2 seconds for 95% of attempts under the agreed peak load.

Bad: “the API responds in 200 ms,” “use a cache,” or “React renders efficiently.” Those prescribe or measure internals.

8. Use this artifact shape

# Feature Specification: <name>

## Context and Scope
### In Scope
### Out of Scope

## User Journeys
### User Journey 1 — <title> (Priority: P1)

## Edge Cases

## Requirements
### Functional Requirements
### Key Entities

## Success Criteria
### Measurable Outcomes

## Assumptions and Dependencies
## Clarifications

Remove an optional section rather than leaving placeholders or N/A.

9. Self-check before handoff

Review, revise, and repeat up to three passes:

• no implementation details unless explicitly binding;
• every mandatory section contains concrete content;
• every journey is prioritized and independently testable;
• every requirement is atomic, unambiguous, and traceable by ID;
• acceptance scenarios cover primary and failure outcomes;
• relevant edge cases are explicit;
• scope, dependencies, and assumptions are bounded;
• entities use domain language rather than storage design;
• success criteria are measurable and technology-independent;
• no contradiction, placeholder, or undefined synonym remains;
• no more than three critical clarification markers remain.

If failures remain after three revision passes, list the exact failed checks beside the draft. Do not call the spec ready for planning while a scope-, security-, or acceptance-changing clarification remains unresolved.