Write Feature Specification

You are creating a formal feature specification from a natural language description. Specifications describe WHAT the system should do and WHY, never HOW it should be implemented.

Upstream source: github/spec-kit — run /spec-kit:check-updates to check for methodology updates.

Prerequisites

• .speckit/ directory must exist. If not, instruct the user to run /spec-kit:init first.
• .speckit/constitution.md should exist with filled-in principles. If not, suggest running /spec-kit:constitution first (but don't block).

Workflow

Step 1: Get Feature Description

If the user hasn't provided a feature description with the command invocation, ask them:

What feature would you like to specify? Describe it in natural language.

Step 2: Determine Feature Name and Number

1. Extract a concise short name from the description: 2-4 words, action-noun format, kebab-case (e.g., user-authentication, export-reports, batch-upload)
   • Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
   • Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
2. Scan the specs/ directory for existing feature directories (format: ###-feature-name)
3. Assign the next available number (001, 002, 003...)
4. Create the feature directory: specs/[###-feature-name]/
5. Also create a specs/[###-feature-name]/checklists/ directory for quality checklists

Step 3: Read Templates and Constitution

• Read .speckit/spec-template.md for the specification structure
• Read .speckit/constitution.md to understand project principles (if available)

Step 4: Generate Specification

Create specs/[###-feature-name]/spec.md following this structure:

# Feature Specification: [FEATURE NAME]

**Feature Branch**: `[###-feature-name]`
**Created**: [TODAY'S DATE]
**Status**: Draft
**Input**: User description: "[original user description]"

## User Scenarios & Testing

<!--
  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
  Each user story/journey must be INDEPENDENTLY TESTABLE.
-->

### User Story 1 - [Brief Title] (Priority: P1)

[Describe this user journey in plain language]

**Why this priority**: [Explain the value and why it has this priority level]

**Independent Test**: [How to verify this story independently]

**Acceptance Scenarios**:

1. **Given** [initial state], **When** [action], **Then** [expected outcome]
2. **Given** [initial state], **When** [action], **Then** [expected outcome]

---

### User Story 2 - [Brief Title] (Priority: P2)

[Describe this user journey in plain language]

**Why this priority**: [Explain the value]

**Independent Test**: [How to verify this story independently]

**Acceptance Scenarios**:

1. **Given** [initial state], **When** [action], **Then** [expected outcome]

---

### User Story 3 - [Brief Title] (Priority: P3)

[Describe this user journey in plain language]

**Why this priority**: [Explain the value]

**Independent Test**: [How to verify this story independently]

**Acceptance Scenarios**:

1. **Given** [initial state], **When** [action], **Then** [expected outcome]

---

[Add more user stories as needed, each with an assigned priority]

### Edge Cases

- What happens when [boundary condition]?
- How does system handle [error scenario]?

## Requirements

### Functional Requirements

- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
- **FR-005**: System MUST [behavior, e.g., "log all security events"]

*Example of marking unclear requirements:*
- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]

### Key Entities *(include if feature involves data)*

- **[Entity 1]**: [What it represents, key attributes without implementation]
- **[Entity 2]**: [What it represents, relationships to other entities]

## Success Criteria

### Measurable Outcomes

- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]

## Assumptions

- [Assumption about target users, e.g., "Users have stable internet connectivity"]
- [Assumption about scope boundaries, e.g., "Mobile support is out of scope for v1"]
- [Assumption about data/environment, e.g., "Existing authentication system will be reused"]
- [Dependency on existing system/service, e.g., "Requires access to the existing user profile API"]

Writing rules:

• Make informed guesses using context, industry standards, and common patterns to fill gaps
• Document assumptions in the Assumptions section
• Limit [NEEDS CLARIFICATION] markers to maximum 3 — use only for decisions that significantly impact feature scope, have multiple reasonable interpretations, or lack any reasonable default
• Prioritize clarifications: scope > security/privacy > user experience > technical details
• Focus on WHAT and WHY, never HOW (no technology specifics)

Step 5: Specification Quality Validation

After writing the initial spec, create and run a quality checklist:

Create specs/[###-feature-name]/checklists/requirements.md:

# Specification Quality Checklist: [FEATURE NAME]

**Purpose**: Validate specification completeness and quality before proceeding to planning
**Created**: [TODAY'S DATE]
**Feature**: ../spec.md

## Content Quality

- [ ] No implementation details (languages, frameworks, APIs)
- [ ] Focused on user value and business needs
- [ ] Written for non-technical stakeholders
- [ ] All mandatory sections completed

## Requirement Completeness

- [ ] No [NEEDS CLARIFICATION] markers remain (or ≤3 critical ones documented)
- [ ] Requirements are testable and unambiguous
- [ ] Success criteria are measurable
- [ ] Success criteria are technology-agnostic (no implementation details)
- [ ] All acceptance scenarios are defined using Given/When/Then
- [ ] Edge cases are identified
- [ ] Scope is clearly bounded
- [ ] Assumptions are documented

## Feature Readiness

- [ ] All functional requirements have clear acceptance criteria
- [ ] User scenarios cover primary flows
- [ ] Each user story is independently testable
- [ ] No implementation details leak into specification

## Notes

- Items marked incomplete require spec updates before `/spec-kit:clarify` or `/spec-kit:plan`

Review the spec against each checklist item and mark them [x] (pass) or [ ] (fail):

• Update the checklist file with current pass/fail status
• If items fail, update the spec to address them (max 3 iterations)
• If [NEEDS CLARIFICATION] markers remain (>3 or critical ones): present them to the user for resolution before proceeding

Handling clarification questions (if any [NEEDS CLARIFICATION] markers exist):

• Present each question with 2-5 option choices and your recommended option
• Number questions sequentially (Q1, Q2, Q3 — max 3 total)
• Present all questions together, then wait for responses
• Update the spec by replacing each marker with the user's answer
• Re-validate after clarifications are resolved

Step 6: Output Summary

Specification Created: specs/[###-feature-name]/spec.md

  Feature: [FEATURE NAME]
  User Stories: [count] (P1, P2, P3...)
  Requirements: [count] functional requirements
  Success Criteria: [count] measurable outcomes
  Clarifications Pending: [count] (must resolve before /spec-kit:plan)

Quality Checklist: specs/[###-feature-name]/checklists/requirements.md
  Passed: [count]/[total] items

Next steps:
  - If clarifications needed: Run /spec-kit:clarify
  - Otherwise: Run /spec-kit:plan to create the implementation plan

Important Rules

• Write for non-technical stakeholders. Use plain language.
• Focus on WHAT the system does and WHY, never HOW.
• Each user story must be independently testable, deployable, and demonstrable.
• Functional requirements use RFC 2119 keywords: MUST, SHOULD, MAY.
• Never include code snippets, database schemas, or API specifications in the spec.
• Success criteria must be technology-agnostic and measurable.
• If the description is too vague to produce 3 user stories, ask the user for more detail.

Success Criteria Guidelines

Success criteria must be:

1. Measurable: Include specific metrics (time, percentage, count, rate)
2. Technology-agnostic: No mention of frameworks, languages, databases, or tools
3. User-focused: Describe outcomes from user/business perspective
4. Verifiable: Can be tested/validated without knowing implementation details

Good examples: "Users can complete checkout in under 3 minutes", "System supports 10,000 concurrent users"

Bad examples: "API response time is under 200ms" (too technical), "React components render efficiently" (framework-specific)