/feature-specification

name: feature-specification
description: Write a detailed feature spec with requirements, edge cases, and technical constraints. Use when a feature needs formal documentation before engineering begins.

Feature Specification

Detail a feature from concept to builder-ready spec in 30-60 minutes. Claude enumerates the requirements, edge cases, error states, and integration points that humans typically miss. You provide the user context and make the trade-off calls on complexity vs. value.

When to Use

• A feature within an epic needs detailed specification before development
• Engineers or AI coding tools need unambiguous requirements to start building
• The feature touches multiple systems and needs explicit integration requirements
• Design and engineering need a shared reference for what "done" looks like
• A feature is being handed off to another team or contractor

When NOT to Use

• The work is small enough for a single user story — use Story Writing
• You need the full initiative-level document — use PRD Writing
• You're defining the strategic wrapper around multiple features — use Epic Definition

The AI-Native Approach

| Step | Time | Claude Does | You Do | |---|---|---|---| | Define the feature | 10 min | Structure the feature description, user value, and context | Confirm the framing matches intent | | Detail requirements | 15 min | Draft functional and non-functional requirements | Validate with engineering, flag unknowns | | Enumerate edge cases | 10 min | Systematically identify edge cases and error states | Decide which to handle in v1 vs. defer | | Define acceptance criteria | 10 min | Write testable acceptance criteria for each requirement | Confirm they match what "done" means | | Document integration points | 10 min | Map API contracts, data flows, and system dependencies | Verify with engineering leads |

Process

Step 1: Define the Feature (10 minutes)

I need to spec out a feature: [feature name]

Context:
- Epic it belongs to: [epic name/link]
- User segment: [who uses this]
- User value: [what job it does for the user — in their words]
- Business value: [why the business cares]

Current state:
- What exists today: [current experience or workaround]
- What changes: [what's new or different]

Constraints known upfront:
- [Technical constraints, platform limitations, compliance requirements]
- [Timeline constraints — when does this need to ship?]

Step 2: Detail Requirements (15 minutes)

Draft the requirements for this feature:

Functional requirements (what it must do):
- [Requirement 1] — [why]
- [Requirement 2] — [why]
- [Requirement 3] — [why]

For each requirement, specify:
- Input: what triggers this behavior
- Output: what the user sees or what the system does
- Rules: business logic, validation, calculations

Non-functional requirements:
- Performance: [latency, throughput targets]
- Scale: [expected usage volume, growth projections]
- Security: [authentication, authorization, data handling]
- Accessibility: [WCAG level, specific accommodations]
- Compatibility: [browsers, devices, OS versions, screen sizes]

Step 3: Enumerate Edge Cases (10 minutes)

This is where AI adds disproportionate value. Humans tend to spec the happy path. Claude catches the rest.

For each functional requirement, enumerate edge cases:

- Empty states: what does the user see before any data exists?
- Error states: what happens when the request fails, times out, or returns unexpected data?
- Boundary conditions: what happens at the minimum, maximum, and zero values?
- Permission states: what happens when the user doesn't have access?
- Concurrent states: what happens when two users modify the same data?
- Interruption states: what happens when the user abandons mid-flow, loses connection, or navigates away?
- Migration states: what happens for existing users vs. new users?
- Degraded states: what happens when a dependency is slow or unavailable?

For each edge case: what should the user see, and what should the system do?

Step 4: Define Acceptance Criteria (10 minutes)

Write acceptance criteria for each requirement and key edge case:

Format:
Given [precondition]
When [action]
Then [expected result]

Rules:
- Every criterion must be testable — if you can't write a manual or automated test, rewrite it
- Include both positive cases (it works) and negative cases (it handles failure)
- Specify exact values where possible, not "appropriate" or "reasonable"
- Include performance criteria where relevant (e.g., "responds within 200ms")

Step 5: Document Integration Points (10 minutes)

Map the integration points for this feature:

For each system this feature touches:
- System: [name]
- Integration type: [API call, event, webhook, database query, file transfer]
- Direction: [reads from / writes to / both]
- Contract: [endpoint, payload format, authentication]
- Failure mode: [what happens when this integration fails]
- Owner: [team responsible for the other side]

Data flow:
- What data does this feature create, read, update, or delete?
- Where does it come from and where does it go?
- What's the source of truth?
- Any data retention or privacy implications?

Output

• Feature description with user and business value
• Functional and non-functional requirements
• Edge cases and error states enumerated
• Testable acceptance criteria (Given/When/Then)
• Integration map with contracts and failure modes

Common Pitfalls

1. **Happy path only.** The feature works great when everything goes right. What about when it doesn't? Edge cases and error states are where user trust is built or broken. 2. **"Intuitive" as a requirement.** Delete the word "intuitive" from your spec. Replace it with specific, measurable criteria for what the user can accomplish and how. 3. **Missing the migration case.** Existing users with existing data will encounter this feature differently than new users. Spec both paths. 4. **No per