Feature Spec — Writing feature specification...

Creates a detailed specification for a single feature including user story, acceptance criteria, user flows, edge cases, API definitions, dependencies, and effort estimate.

Activation

When this skill activates, output:

Feature Spec — Writing feature specification...

Then execute the protocol below.

Context Guard

Context	Status
User says "feature spec", "spec this feature", "write a spec"	ACTIVE
User says "functional requirements" for a specific feature	ACTIVE
User needs a detailed breakdown of ONE feature for engineering	ACTIVE
User wants a full product requirements document	DORMANT — use PRD Writer
User wants multiple user stories for sprint planning	DORMANT — use User Story Generator

Common Mistakes

Mistake	Why It's Wrong
"Spec the happy path only"	Edge cases cause 80% of bugs. Spec them upfront or pay for them in QA.
"Skip the API contract"	Frontend and backend need to agree on the contract before building in parallel.
"No acceptance criteria"	Without testable criteria, "done" is subjective. Define done before starting.
"Spec the UI, not the behavior"	UIs change. Behavior specs survive redesigns. Focus on what happens, not what it looks like.
"Forget to list what's out of scope"	Ambiguity invites scope creep. Explicitly list what this feature does NOT include.

Protocol

Step 1: Gather Feature Context

If the user hasn't provided details, ask:

1. Feature name — what are you building?
2. User problem — what problem does this feature solve?
3. Target user — which persona uses this feature?
4. Context — is this part of a larger project? What already exists?
5. Constraints — timeline, tech stack, or design constraints?

Step 2: Write Feature Brief

## Feature Brief

**Feature:** [Feature name]
**Owner:** [Product owner / author]
**Date:** [Date]
**Status:** [Draft / In Review / Approved]

### Summary
[2-3 sentences: what this feature does and why it matters]

### User Story
As a [persona], I want to [action] so that [outcome].

### Business Value
- [Why this matters for the business — revenue, retention, efficiency]
- [Metric this feature is expected to move]

### Scope
**In scope:**
- [Specific capability 1]
- [Specific capability 2]
- [Specific capability 3]

**Out of scope:**
- [Explicitly excluded capability 1]
- [Explicitly excluded capability 2]

Step 3: Define User Flows

Primary flow (happy path):

### Primary Flow: [Action Name]

**Entry point:** [Where/how the user accesses this feature]
**Preconditions:** [What must be true — logged in, has permission, etc.]

1. User [action — clicks, enters, selects]
   → System [response — shows, loads, validates]
2. User [action]
   → System [response]
3. User [action — confirms, submits]
   → System [response — saves, sends, updates]
4. User sees [confirmation — success message, updated state, redirect]

**Exit state:** [What the system looks like after completion]

Alternative flows:

### Alternative Flow: [Variation Name]

**Trigger:** [When this flow happens instead of the primary]

1. [Step that diverges from primary flow]
2. [How the system handles the variation]
3. [Where it rejoins the primary flow, or how it terminates]

Step 4: Document Edge Cases & Error States

#	Scenario	Expected Behavior	Priority
E1	User submits empty form	Show inline validation errors on required fields	Must handle
E2	Network request fails	Show error toast, preserve form state, offer retry	Must handle
E3	User double-clicks submit	Disable button after first click, prevent duplicate submission	Must handle
E4	Session expires during flow	Save draft state, redirect to login, restore after auth	Should handle
E5	Concurrent edit by another user	Show conflict notification, offer merge or overwrite	Should handle
E6	Input exceeds character limit	Enforce limit in UI, validate server-side, show remaining count	Must handle
E7	User navigates away with unsaved changes	Show "Unsaved changes" confirmation dialog	Should handle

Edge case discovery checklist:

• What happens with empty/null input?
• What happens with maximum-length input?
• What happens with special characters or Unicode?
• What happens if the user has no permission?
• What happens offline or with slow network?
• What happens with concurrent actions?
• What happens if a dependency (API, service) is down?

Step 5: Define API Contract (if applicable)

### API Endpoints

#### POST /api/[resource]
**Purpose:** [What this endpoint does]
**Auth:** Required — [Bearer token / API key / session]
**Rate limit:** [X requests per minute]

**Request:**
```json
{
  "field1": "string (required) — [description]",
  "field2": "number (optional) — [description, default: X]",
  "field3": "enum (required) — [allowed values: a, b, c]"
}

Response (200):

{
  "id": "string — [description]",
  "field1": "string",
  "createdAt": "ISO 8601 datetime"
}

Error responses:

Status	Code	Message	When
400	VALIDATION_ERROR	"field1 is required"	Missing required field
401	UNAUTHORIZED	"Authentication required"	No/invalid token
403	FORBIDDEN	"Insufficient permissions"	User lacks permission
409	CONFLICT	"Resource already exists"	Duplicate creation
429	RATE_LIMITED	"Too many requests"	Rate limit exceeded

### Step 6: Write Acceptance Criteria

Use Given/When/Then format for each criterion:

```markdown
### Acceptance Criteria

**AC-1: [Primary happy path]**
Given [precondition]
When [user action]
Then [expected outcome]
And [additional verification]

**AC-2: [Validation]**
Given [precondition]
When [user submits invalid input]
Then [error message] is displayed
And [form state is preserved]

**AC-3: [Permission check]**
Given [user without permission]
When [user attempts action]
Then [access denied response]
And [appropriate error shown]

**AC-4: [Edge case]**
Given [edge condition]
When [action]
Then [graceful handling]

Acceptance criteria rules:

• Write criteria for EVERY in-scope item (not just the happy path)
• Each criterion must be independently testable
• Include at least one criterion for: happy path, validation, error, and permission
• QA should be able to write test cases directly from these criteria

Step 7: Estimate Effort & Dependencies

Effort estimate:

Component	Effort	Confidence	Notes
Frontend UI	[X days]	High/Med/Low	[Notes]
Backend API	[X days]	High/Med/Low	[Notes]
Database changes	[X days]	High/Med/Low	[Notes]
Testing (unit + integration)	[X days]	High/Med/Low	[Notes]
Code review + QA	[X days]	High/Med/Low	[Notes]
Total	[X days]

Dependencies:

Dependency	Owner	Status	Blocking?
[Design mockups for X]	Design	[Done/In Progress/Not Started]	Yes/No
[API from service Y]	Backend team	[Done/In Progress/Not Started]	Yes/No
[Third-party SDK setup]	DevOps	[Done/In Progress/Not Started]	Yes/No

Technical considerations:

• [Any architectural decisions needed]
• [Migration requirements]
• [Performance implications]
• [Security considerations]

Output Format

# Feature Spec: [Feature Name]

**Owner:** [Name]
**Date:** [Date]
**Status:** [Draft / In Review / Approved]
**Estimated effort:** [X days]

## 1. Feature Brief
[From Step 2 — summary, user story, scope]

## 2. User Flows
### Primary Flow
[From Step 3]
### Alternative Flows
[From Step 3]

## 3. Edge Cases & Error States
[Table from Step 4]

## 4. API Contract
[From Step 5]

## 5. Acceptance Criteria
[From Step 6]

## 6. Effort & Dependencies
[From Step 7]

## 7. Open Questions
[Anything that needs design, engineering, or stakeholder input]

Completion

Feature Spec — Complete!

Feature: [Name]
User story: As a [persona], I want to [action] so that [outcome]
Acceptance criteria: [Count]
Edge cases documented: [Count]
API endpoints: [Count]
Estimated effort: [X days]

Next steps:
1. Review with engineering for technical feasibility
2. Review with design for UX validation
3. Get stakeholder approval on scope
4. Break into tasks/subtasks for sprint planning
5. Write unit tests based on acceptance criteria

Level History

• Lv.1 — Base: Feature brief template (summary, user story, scope), primary + alternative user flow documentation, edge case table with discovery checklist, API contract template (request, response, errors), Given/When/Then acceptance criteria, effort estimation table with confidence levels, dependency tracking. (Origin: MemStack Pro v3.2, Mar 2026)