Skip to main content

Chapter 20: /speckit.specify — Feature Specification

Learning Objectives​

By the end of this chapter, you will be able to:

  • Explain what /speckit.specify does and when to use it
  • Use automatic feature numbering and branch creation in your workflow
  • Understand the specification template structure and how it constrains AI
  • Write specifications that focus on WHAT and WHY, avoiding premature HOW
  • Mark ambiguities with [NEEDS CLARIFICATION] and use completeness checklists
  • Create a complete feature specification using /speckit.specify through a hands-on tutorial
  • Customize the specification template for your project
  • Avoid common mistakes: too much implementation detail, missing edge cases, skipping non-goals

What /speckit.specify Does​

/speckit.specify is the entry point of the Spec Kit workflow. It transforms a simple feature description—often a single sentence or a few bullet points—into a complete, structured specification ready for planning and implementation.

Think of it as the bridge between "I want to build X" and "Here is the formal specification for X that an AI or human can implement from."

The Transformation​

Input: A feature description such as:

  • "Add real-time chat to the app"
  • "Users should be able to export their data as CSV"
  • "Implement password reset flow"

Output: A complete specification document (spec.md) in specs/[branch-name]/ that includes:

  • Problem statement (why this feature exists)
  • User stories and acceptance criteria
  • Functional and non-functional requirements
  • Edge cases and error handling
  • Non-goals (what we are explicitly NOT building)
  • Completeness checklists
  • Placeholders for ambiguities marked [NEEDS CLARIFICATION]

The command does not just "expand" your description—it applies a template, enforces structure, and guides you toward specification best practices that produce better implementations.

Automatic Feature Numbering​

When you run /speckit.specify, the command scans your existing specs/ directory to determine the next feature number. This maintains a consistent, traceable numbering scheme across your project.

How It Works​

specs/
├── 001-user-authentication/
├── 002-password-reset/
├── 003-profile-management/
└── 004-real-time-chat/     ← Next feature gets 005

The command:

  1. Lists all directories under specs/ that match the pattern NNN-* (e.g., 001-, 002-)
  2. Extracts the numeric prefix from each
  3. Assigns the next sequential number to the new feature
  4. Uses that number in the branch name and directory structure

Why Numbering Matters​

  • Traceability: "Feature 004" maps to branch 004-real-time-chat, spec specs/004-real-time-chat/spec.md, and eventually tasks and commits.
  • Ordering: Numbers imply sequence. You can see at a glance which features came before and after.
  • Automation: CI/CD, tooling, and AI can reference features by number without ambiguity.

Edge Cases​

  • First feature: If specs/ is empty, the command uses 001.
  • Gaps: If you have 001, 002, 004 (003 was removed), the next number is typically 005—the highest + 1. Some implementations use the next available gap; document your convention.
  • Custom numbering: If your project uses a different scheme (e.g., F-001, epic-1/feature-a), you may need to customize the numbering logic or pass the number explicitly.

Branch Creation​

/speckit.specify generates a semantic branch name from your feature description. The branch name is derived from the feature number and a slugified version of the feature title.

Branch Name Format​

{number}-{slugified-feature-name}

Examples:

  • "real-time chat" → 004-real-time-chat
  • "Export data as CSV" → 005-export-data-as-csv
  • "Password reset flow" → 006-password-reset-flow

What the Command Does​

  1. Creates the branch: Runs git checkout -b 004-real-time-chat (or equivalent)
  2. Creates the directory: specs/004-real-time-chat/
  3. Places all spec artifacts in that directory

This keeps your git history aligned with your specification structure. Every commit for "real-time chat" lives on 004-real-time-chat, and the spec lives in the matching directory.

Branch Naming Conventions​

  • Lowercase: real-time-chat not Real-Time-Chat
  • Hyphen-separated: export-data-as-csv not export_data_as_csv
  • Concise: password-reset not implement-password-reset-flow-for-users-who-forgot-their-password

The command typically applies these conventions automatically. If your project uses different conventions (e.g., feature/004-real-time-chat), you may need to configure the branch prefix.

Template-Based Generation​

/speckit.specify does not generate specifications from scratch each time. It uses a template—a predefined structure that ensures consistency and completeness.

The Template Location​

Templates are typically stored in:

  • specs/_templates/feature-spec.md (project-specific)
  • Or a built-in template shipped with Spec Kit (fallback)

What the Template Contains​

The template defines:

  1. Section headings (Problem, User Stories, Acceptance Criteria, etc.)
  2. Placeholder text that gets replaced with feature-specific content
  3. Instructions for each section (what to write, what to avoid)
  4. Completeness checklists (items to verify before considering the spec done)

Customization Flow​

  1. Command loads the template
  2. Replaces {{FEATURE_NAME}}, {{FEATURE_NUMBER}}, {{BRANCH_NAME}} with actual values
  3. Uses AI (or rules) to fill in section content based on your feature description
  4. Writes the result to specs/[branch-name]/spec.md

If you customize the template, the command will use your version. This allows teams to enforce project-specific specification standards.

Directory Structure​

All specification documents for a feature live under a single directory:

specs/
└── 004-real-time-chat/
    ├── spec.md           # Main specification (required)
    ├── plan.md           # Generated by /speckit.plan (Chapter 20)
    ├── data-model.md     # Generated by /speckit.plan
    ├── tasks.md          # Generated by /speckit.tasks (Chapter 21)
    ├── contracts/        # API contracts (from plan)
    │   ├── chat-api.yaml
    │   └── events.yaml
    ├── research.md       # Optional: library research
    └── quickstart.md     # Optional: quick validation scenarios

When you run /speckit.specify, only spec.md is created. The other files are produced by later commands in the pipeline.

Why This Structure?​

  • Single source of truth: Everything for "real-time chat" is in one place
  • Traceability: spec.md → plan.md → tasks.md forms a clear chain
  • AI context: When implementing, AI loads the entire directory. No hunting for scattered documents.

The Specification Template Structure​

The template structure is designed to constrain AI (and human) behavior. It enforces focus on WHAT and WHY, avoids premature HOW, and surfaces ambiguities explicitly.

Section 1: Problem Statement​

Purpose: Why does this feature exist? Who experiences the pain? What is the cost of not solving it?

Template guidance:

## Problem

[1-3 sentences describing the problem]
- **Who**: [User role or persona]
- **Pain**: [What they experience]
- **Impact**: [Consequence of not solving]

Constrains AI: The AI must articulate the problem before proposing solutions. This prevents solution-first thinking.

Section 2: User Stories​

Purpose: Concrete scenarios from the user's perspective. "As a [role], I want [goal] so that [benefit]."

Template guidance:

## User Stories

- As a [role], I want [capability] so that [benefit]
- As a [role], I want [capability] so that [benefit]

Constrains AI: User stories keep the spec grounded in user value. They are not implementation tasks.

Section 3: Functional Requirements​

Purpose: What the system must do. Capabilities, not implementation.

Template guidance:

## Functional Requirements

- FR-001: [Requirement]
- FR-002: [Requirement]

Constrains AI: Requirements are testable. "The system must X" not "We will use technology Y to implement X."

Section 4: Acceptance Criteria​

Purpose: Testable conditions that define "done." Given/When/Then format preferred.

Template guidance:

## Acceptance Criteria

- AC-001: Given [context], when [action], then [observable outcome]
- AC-002: Given [context], when [action], then [observable outcome]

Constrains AI: Acceptance criteria must be verifiable. Vague criteria like "works well" are rejected by the template instructions.

Section 5: Edge Cases and Error Handling​

Purpose: Boundary conditions, error paths, unusual inputs.

Template guidance:

## Edge Cases

- [Scenario]: [Expected behavior]
- [Scenario]: [Expected behavior]

## Error Handling

- [Error condition]: [System response]

Constrains AI: The template prompts for edge cases. AI that skips this section produces implementations that fail on boundaries.

Section 6: Non-Goals​

Purpose: What we are explicitly NOT building. Prevents scope creep.

Template guidance:

## Non-Goals

- Not [out of scope item]
- Not [out of scope item]

Constrains AI: Non-goals create boundaries. When AI is tempted to add "helpful" features, non-goals say "no."

Section 7: Ambiguity Markers​

Purpose: Surfaces uncertainty. When something is unclear, mark it.

Template guidance:

[NEEDS CLARIFICATION]: [What is ambiguous and what decision is needed]

Constrains AI: The template instructs: "If you are unsure, mark it. Do not guess." This produces specs that trigger human review instead of wrong implementations.

Section 8: Completeness Checklist​

Purpose: Verification before considering the spec complete.

Template guidance:

## Completeness Checklist

- [ ] Problem statement is clear
- [ ] All user stories have acceptance criteria
- [ ] Edge cases are documented
- [ ] Non-goals are explicit
- [ ] No [NEEDS CLARIFICATION] markers remain (or they are documented as deferred)
- [ ] Specification focuses on WHAT/WHY, not HOW

Constrains AI: The checklist forces a final pass. Incomplete specs are visible.

Focus on WHAT and WHY, Avoid HOW​

The most important constraint the template enforces: specifications describe what users need and why—not how to implement.

What Goes in a Spec (WHAT/WHY)​

  • "Users can send messages and see them appear in real time"
  • "Messages are delivered within 2 seconds under normal load"
  • "Only participants in a conversation can see its messages"

What Does NOT Go in a Spec (HOW)​

  • "Use WebSockets for real-time delivery"
  • "Store messages in Redis for pub/sub"
  • "Implement with Socket.io on the backend"

Why This Matters​

When HOW leaks into the spec:

  1. Premature commitment: You lock in technology before understanding requirements
  2. AI confusion: AI may treat "use WebSockets" as a requirement, not a possible implementation
  3. Reduced flexibility: The plan phase (Chapter 20) is where technology decisions belong. The spec should not preempt them.

The Test​

Before adding anything to a spec, ask: "If we implemented this differently, would we still satisfy the requirement?" If yes, you're in WHAT/WHY territory. If no, you might have implementation detail—move it to the plan.

Marking Ambiguities with [NEEDS CLARIFICATION]​

When the spec author (human or AI) encounters uncertainty, they mark it explicitly:

## Functional Requirements

- FR-001: Users can create chat rooms with a name and optional description.
- FR-002: [NEEDS CLARIFICATION] Maximum participants per room: product owner to decide. Options: 10, 50, 100, unlimited.
- FR-003: Users receive notifications when they are mentioned in a message.

Why Mark Ambiguities?​

  • Visibility: Stakeholders see what needs a decision
  • No silent guessing: AI (or implementer) does not fill in the blank with an arbitrary choice
  • Traceability: When the decision is made, you update the spec and remove the marker

Resolving [NEEDS CLARIFICATION]​

  1. Decide: Product owner or tech lead makes the call
  2. Update: Replace the marker with the decided value
  3. Document: If the decision is significant, add an ADR (Architectural Decision Record) in the plan phase

When to Defer​

Some ambiguities can be deferred to the plan phase. Mark them as such:

- FR-002: [NEEDS CLARIFICATION - DEFER TO PLAN] Message retention policy. Plan phase will evaluate: 30 days, 90 days, indefinite.

Tutorial: Create a "Real-Time Chat" Feature Specification​

This tutorial walks you through using /speckit.specify to create a complete specification for a real-time chat feature.

Prerequisites​

  • Spec Kit installed and configured
  • A project with a specs/ directory (can be empty)
  • Git repository initialized

Step 1: Run the Command with a Feature Description​

Open your terminal or AI coding assistant. Navigate to your project root. Run:

/speckit.specify

Feature: Real-time chat. Users can create chat rooms, send messages, and see messages from other participants in real time. Messages should appear within 2 seconds. Only room participants can see messages. Need to support at least 50 concurrent users per room.

What happens:

  1. Spec Kit scans specs/ for existing feature numbers (e.g., finds 001, 002, 003)
  2. Assigns 004 as the next number
  3. Creates branch 004-real-time-chat
  4. Creates directory specs/004-real-time-chat/
  5. Loads the feature spec template
  6. Uses AI to fill in sections based on your description
  7. Writes specs/004-real-time-chat/spec.md

Step 2: Review the Generated Specification​

Open specs/004-real-time-chat/spec.md. You should see something like:

# Feature 004: Real-Time Chat

## Problem

Users need to communicate in real time within the application. Currently, communication requires leaving the app (email, external chat tools), which disrupts workflow and creates context-switching overhead. The lack of in-app real-time chat increases friction for collaborative tasks and forces users to manage multiple tools.

- **Who**: Authenticated users working on shared projects or tasks
- **Pain**: Cannot communicate quickly without leaving the app; must use external tools
- **Impact**: Reduced collaboration efficiency, context loss, fragmented communication history

## User Stories

- As a user, I want to create a chat room so that I can organize conversations by topic or project
- As a user, I want to send messages and see them appear in real time so that I can have fluid conversations
- As a user, I want to see who is in a room so that I know who can see my messages
- As a participant, I want only other participants to see my messages so that conversations remain private

## Functional Requirements

- FR-001: Users can create chat rooms with a name and optional description
- FR-002: Users can send text messages to a room
- FR-003: Messages are delivered to all room participants within 2 seconds under normal load
- FR-004: Only users who are participants in a room can view its messages
- FR-005: The system supports at least 50 concurrent users per room
- FR-006: Users can see the list of participants in a room

## Acceptance Criteria

- AC-001: Given a user creates a room with name "Project Alpha", when they save, then the room appears in their room list
- AC-002: Given a user sends a message in a room, when they submit, then all other participants see the message within 2 seconds
- AC-003: Given a user who is not a participant, when they request room messages, then they receive an access denied response
- AC-004: Given 50 users in a room, when they send messages concurrently, then all messages are delivered and no messages are lost

## Edge Cases

- **User joins mid-conversation**: User sees messages from when they joined forward; [NEEDS CLARIFICATION] whether to show message history before join
- **User goes offline**: Messages sent while offline are not delivered; user sees them when they reconnect (if within retention window)
- **Room at capacity**: [NEEDS CLARIFICATION] Maximum participants per room—50 minimum per spec; upper limit TBD
- **Empty message**: System rejects empty or whitespace-only messages with validation error
- **Very long message**: [NEEDS CLARIFICATION] Maximum message length (e.g., 4000 characters)

## Error Handling

- **Room not found**: Return 404 with clear error message
- **Unauthorized access**: Return 403 when non-participant requests messages
- **Network failure**: Client receives connection error; can retry or show offline state
- **Rate limiting**: [NEEDS CLARIFICATION] Messages per minute per user limit

## Non-Goals

- Not building: voice/video calls, file attachments, message editing, message reactions
- Not building: end-to-end encryption (messages stored in plaintext server-side for MVP)
- Not building: read receipts or typing indicators (future phase)
- Not building: chat history search (future phase)

## Dependencies

- Existing user authentication system (users must be authenticated to create rooms and send messages)
- [NEEDS CLARIFICATION] Whether rooms are tied to projects, teams, or are standalone

## Completeness Checklist

- [ ] Problem statement is clear
- [ ] All user stories have acceptance criteria
- [ ] Edge cases are documented
- [ ] Non-goals are explicit
- [ ] No [NEEDS CLARIFICATION] markers remain (or they are documented as deferred)
- [ ] Specification focuses on WHAT/WHY, not HOW

Step 3: Refine Ambiguities​

Review each [NEEDS CLARIFICATION] marker. For each, either:

  • Decide now: Replace with the decided value
  • Defer to plan: Mark as [DEFER TO PLAN] and let the plan phase resolve it
  • Leave for stakeholder: Keep the marker and assign an owner

Example refinement for "Message history before join":

- **User joins mid-conversation**: User sees messages from when they joined forward. Message history before join is out of scope for MVP; future phase may add "load history" feature.

Step 4: Complete the Specification​

Work through the Completeness Checklist. Ensure:

  • Every user story maps to at least one acceptance criterion
  • Edge cases have expected behavior (or explicit deferral)
  • Non-goals are comprehensive enough to prevent scope creep
  • No implementation details (no "use WebSockets", "use Redis", etc.)

When all items are checked, the specification is ready for /speckit.plan.

Step 5: Validate Against Quality Heuristics (Optional)​

Before moving to planning, run your spec through the quality heuristics from earlier in this chapter:

  • Stranger Test: Would a new team member understand what to build?
  • Implementation Test: Could implementation proceed without you?
  • Scope Test: Are boundaries clear?
  • Testability Test: Is every acceptance criterion verifiable?

Address any gaps before proceeding.

Step 6: Commit and Proceed​

Commit your specification to the feature branch:

git add specs/004-real-time-chat/spec.md
git commit -m "spec(004): add real-time chat feature specification"

You are now ready to run /speckit.plan to generate the implementation plan.

Example: Complete Generated Specification Output​

Below is a condensed example of a complete, refinement-free specification for the real-time chat feature (ambiguities resolved):

# Feature 004: Real-Time Chat

## Problem

Users need to communicate in real time within the application. Currently, communication requires leaving the app, which disrupts workflow. The lack of in-app real-time chat increases friction for collaborative tasks.

- **Who**: Authenticated users working on shared projects
- **Pain**: Cannot communicate quickly without leaving the app
- **Impact**: Reduced collaboration efficiency, fragmented communication

## User Stories

- As a user, I want to create a chat room so that I can organize conversations by topic
- As a user, I want to send messages and see them in real time so that I can have fluid conversations
- As a user, I want to see who is in a room so that I know who can see my messages
- As a participant, I want only other participants to see my messages so that conversations remain private

## Functional Requirements

- FR-001: Users can create chat rooms with a name and optional description
- FR-002: Users can send text messages to a room (max 4000 characters)
- FR-003: Messages are delivered to all room participants within 2 seconds under normal load
- FR-004: Only room participants can view messages
- FR-005: System supports at least 50 concurrent users per room (max 100 per room)
- FR-006: Users can see the list of participants in a room
- FR-007: New participants see messages from join time forward (no history before join for MVP)

## Acceptance Criteria

- AC-001: Given a user creates a room, when they save, then the room appears in their room list
- AC-002: Given a user sends a message, when they submit, then all participants see it within 2 seconds
- AC-003: Given a non-participant, when they request room messages, then they receive 403
- AC-004: Given 50 users in a room sending concurrently, then all messages are delivered
- AC-005: Given a message over 4000 characters, when user submits, then validation error is returned

## Edge Cases

- User joins mid-conversation: Sees messages from join forward
- User goes offline: Messages queued; delivered on reconnect (24-hour retention)
- Room at 100 participants: New join attempts receive "room full" error
- Empty message: Rejected with validation error
- Rate limit: 60 messages per minute per user; excess receive 429

## Non-Goals

- No voice/video, file attachments, message editing, reactions
- No end-to-end encryption for MVP
- No read receipts or typing indicators
- No chat history search

## Completeness Checklist

- [x] Problem statement is clear
- [x] All user stories have acceptance criteria
- [x] Edge cases are documented
- [x] Non-goals are explicit
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Specification focuses on WHAT/WHY, not HOW

Customizing the Specification Template​

Your project may have different needs. You can customize the template.

Template Location​

Create or edit specs/_templates/feature-spec.md in your project.

What to Customize​

  1. Section order: Add or remove sections to match your process
  2. Required sections: Mark certain sections as mandatory (e.g., Security Requirements)
  3. Project-specific sections: Add "Compliance" or "Localization" if relevant
  4. Constitution alignment: Add a section that references your project constitution
  5. ID format: Change FR-001 to REQ-001 or use a different scheme

Example: Adding a Security Section​

## Security Requirements

- All chat endpoints require authentication
- Messages are scoped to room membership; no cross-room data leakage
- PII in messages: [reference to global PII handling policy]

Example: Constitution Reference​

## Constitution Alignment

This specification complies with:
- [CONST-001] Library-First: Prefer existing libraries over custom implementation
- [CONST-002] Simplicity Gate: No abstractions without 3+ use cases

When you run /speckit.specify, it will use your customized template.

Specification Templates in Practice​

Different project types may need different templates. Here are variations:

API-First Projects​

Add sections for:

  • API Surface: List of endpoints (without implementation details)
  • Request/Response Shape: High-level structure (e.g., "returns list of messages with id, content, timestamp, sender")
  • Error Codes: Standard error responses (400, 401, 403, 404, 429, 500)

Mobile App Features​

Add sections for:

  • Platform Considerations: iOS vs. Android differences (if any)
  • Offline Behavior: What works without network
  • Accessibility: Screen reader support, contrast requirements

Data Pipeline Features​

Add sections for:

  • Data Sources: Where data comes from
  • Data Sinks: Where data goes
  • Latency/SLA: How fresh must the data be
  • Idempotency: Can the pipeline run twice safely?

Customize your template once, and every generated spec inherits the structure.

When to Run /speckit.specify​

Run it when:

  • Starting a new feature
  • Formalizing an informal feature request
  • Converting a ticket or user story into a full spec
  • Onboarding: creating a spec from a verbal description

Do not run it when:

  • The feature is a trivial bug fix (no new behavior)
  • The change is purely refactoring (no user-visible change)
  • You already have a complete spec and only need to update it (edit directly)

For small changes, editing the existing spec may be faster than regenerating.

Common Mistakes​

Mistake 1: Too Much Implementation Detail​

The Error: Spec says "Use WebSockets and Redis pub/sub for real-time delivery."

Why It's Wrong: Technology choices belong in the plan phase. The spec should say "Messages are delivered within 2 seconds" and let the plan decide how.

The Fix: Remove technology references. Keep only observable behavior and measurable requirements.

Mistake 2: Missing Edge Cases​

The Error: Spec covers happy path only. No mention of: user offline, room full, empty message, rate limits.

Why It's Wrong: Implementations (and AI) will make ad-hoc decisions for edge cases. Inconsistent behavior and bugs result.

The Fix: Add an Edge Cases section. For each "what if?" scenario, document expected behavior. Use [NEEDS CLARIFICATION] if the decision is deferred.

Mistake 3: Skipping Non-Goals​

The Error: Spec lists what we're building but not what we're not building.

Why It's Wrong: Scope creep. AI (or eager developers) add "helpful" features: read receipts, typing indicators, file upload—none of which were requested.

The Fix: Always include a Non-Goals section. Be explicit: "Not building X, Y, Z in this phase."

Mistake 4: Vague Acceptance Criteria​

The Error: "Messages should be fast" or "Users can chat."

Why It's Wrong: "Fast" and "chat" are not testable. Implementation has no clear target.

The Fix: Use Given/When/Then. "Given 50 users in a room, when they send messages, then all messages are delivered within 2 seconds."

Mistake 5: Guessing Instead of Marking Ambiguity​

The Error: Spec says "Max 50 participants" when the product owner never decided.

Why It's Wrong: The spec author (human or AI) guessed. Wrong guess means rework.

The Fix: Use [NEEDS CLARIFICATION] and list options. Let the decision-maker choose.

Mistake 6: Inconsistent ID Schemes​

The Error: Mixing FR-001, REQ-1, and "Requirement 1" in the same spec.

Why It's Wrong: Traceability breaks. "AC-003" in a task should map to exactly one acceptance criterion.

The Fix: Pick one scheme (FR-001, AC-001, etc.) and use it consistently. Document the scheme in the template.

Integration with the SDD Pipeline​

/speckit.specify is the first step in a four-stage pipeline:

/speckit.specify  →  /speckit.plan  →  /speckit.tasks  →  Implementation
     ↓                     ↓                    ↓
  spec.md              plan.md               tasks.md
  (WHAT/WHY)         (HOW, contracts)      (atomic work)

The specification you create here becomes the primary input for /speckit.plan. A well-written spec produces a clear plan; a vague spec produces a vague plan. The cascade effect means that investing time in specification quality pays dividends in every subsequent phase.

Handoff to Planning​

When you run /speckit.plan, it will:

  1. Read specs/[branch-name]/spec.md
  2. Extract requirements, user stories, acceptance criteria
  3. Check alignment with project constitution
  4. Generate plan.md, data-model.md, contracts/, and related artifacts

If your spec has [NEEDS CLARIFICATION] markers, the plan phase may make assumptions or flag them for resolution. Resolving ambiguities before planning produces better plans.

Specification Quality Heuristics​

How do you know if your specification is "good enough"? Use these heuristics:

The Stranger Test​

Could someone unfamiliar with the project read the spec and understand exactly what to build? If yes, the spec passes. If they would need to ask clarifying questions, those questions point to gaps.

The Implementation Test​

Could an AI (or human) implement the feature from the spec alone, without access to you? If critical decisions are missing, the spec fails. Add them or mark them [NEEDS CLARIFICATION].

The Scope Test​

Does the spec clearly bound what is in and out of scope? Non-goals and explicit boundaries prevent "while I'm here" additions during implementation.

The Testability Test​

Can every acceptance criterion be verified? "Works well" fails. "Delivers within 2 seconds" passes. "Users are happy" fails. "Users can complete the flow in under 3 clicks" passes.

Working with AI-Generated Specifications​

When /speckit.specify uses AI to fill the template, the output is a draft—not a final spec. Your role is to:

  1. Review for accuracy: Does the AI correctly interpret your feature description? Fix misinterpretations.
  2. Add missing context: AI may not know your domain. Add project-specific requirements.
  3. Resolve ambiguities: Replace [NEEDS CLARIFICATION] with decisions or deferrals.
  4. Strengthen weak sections: AI often under-specifies edge cases and non-goals. Expand them.
  5. Remove implementation leakage: AI sometimes adds "use X" or "implement with Y." Strip those out.

The command accelerates specification creation but does not replace human judgment. Budget 15–30 minutes for review and refinement after generation.

Specification Versioning and History​

Specifications evolve. When you update a spec:

  1. Commit changes: Each significant update should be a git commit. Message format: spec(004): add message retention requirement
  2. Document changes: For major changes, add a Changelog section at the bottom of the spec:
## Changelog

| Date       | Change                                      |
|------------|---------------------------------------------|
| 2026-03-09 | Initial specification                       |
| 2026-03-10 | Resolved [NEEDS CLARIFICATION] for max participants |
| 2026-03-11 | Added rate limit (60 msg/min) to edge cases |
  1. Preserve traceability: When requirements change, update the plan and tasks. Stale plans lead to wrong implementations.

Case Study: Specification Evolution​

Consider a team specifying "export data as CSV." First draft:

Draft 1: "Users can export their data as CSV." (Too vague.)

Draft 2 (after /speckit.specify):

  • Problem: Users need to download their data for backup or analysis
  • FR-001: Export produces CSV file
  • AC-001: Given user clicks Export, when complete, then file downloads

Gaps: Which data? All or filtered? Format (columns, encoding)? Size limits? Rate limits?

Draft 3 (after refinement):

  • FR-001: Export produces CSV with columns: id, name, email, created_at
  • FR-002: User can filter by date range (optional)
  • FR-003: Max 10,000 rows per export
  • AC-001: Given user with 500 rows, when they export, then CSV has 500 rows and correct columns
  • AC-002: Given user requests 15,000 rows, when they export, then error "Maximum 10,000 rows"
  • Edge case: Empty result set → CSV with headers only
  • Non-goals: No Excel format, no scheduled exports

The evolution shows how specification improves through iteration. Each draft adds precision. /speckit.specify accelerates the first draft; human refinement completes it.

Specification Anti-Patterns to Avoid​

Anti-Pattern 1: Solution in the Problem Statement​

Bad: "We need to implement a WebSocket-based chat system."

Good: "Users cannot communicate in real time within the app; they must use external tools."

The problem is the pain. The solution belongs in the plan.

Anti-Pattern 2: Acceptance Criteria That Aren't Testable​

Bad: "Chat should feel responsive."

Good: "Messages are delivered to all participants within 2 seconds under normal load."

"Feel" is subjective. "2 seconds" is measurable.

Anti-Pattern 3: Implicit Requirements​

Bad: Assuming "of course we need authentication" without stating it.

Good: "All chat endpoints require authentication. Unauthenticated requests receive 401."

Make the implicit explicit.

Anti-Pattern 4: Scope Creep Through "And Also"​

Bad: "Users can send messages. And also we should add read receipts. And typing indicators."

Good: "Users can send messages." (Read receipts and typing indicators in Non-Goals as "future phase" or separate feature.)

One feature, one spec. Add features as separate specs.

Anti-Pattern 5: Spec as Implementation Guide​

Bad: "First create the Room entity, then the Message entity, then the repository..."

Good: "Users can create rooms. Users can send messages." (Order of implementation is the plan's job.)

Spec is WHAT. Plan is HOW and IN WHAT ORDER.

Appendix: Full Feature Spec Template​

Use this as a starting point for specs/_templates/feature-spec.md:

# Feature {{FEATURE_NUMBER}}: {{FEATURE_NAME}}

## Problem

[1-3 sentences]
- **Who**: 
- **Pain**: 
- **Impact**: 

## User Stories

- As a [role], I want [capability] so that [benefit]
- (repeat as needed)

## Functional Requirements

- FR-001: 
- FR-002: 
- (use sequential numbering)

## Acceptance Criteria

- AC-001: Given [context], when [action], then [outcome]
- AC-002: 
- (each should be testable)

## Edge Cases

- [Scenario]: [Expected behavior]
- (cover boundaries, errors, unusual inputs)

## Error Handling

- [Error condition]: [System response]

## Non-Goals

- Not [out of scope]
- (explicit boundaries prevent scope creep)

## Dependencies

- [What this feature requires from other systems or features]

## Security Considerations

- (if applicable; reference global policies)

## Completeness Checklist

- [ ] Problem statement is clear
- [ ] All user stories have acceptance criteria
- [ ] Edge cases are documented
- [ ] Non-goals are explicit
- [ ] No [NEEDS CLARIFICATION] markers (or documented as deferred)
- [ ] Specification focuses on WHAT/WHY, not HOW

Troubleshooting /speckit.specify​

"Command not found" or "speckit is not recognized"​

Ensure Spec Kit is installed and on your PATH. Check your project's tooling configuration (e.g., package.json scripts, global install, or IDE extension).

"No specs directory found"​

Create specs/ at the project root. The command expects this directory to exist. Some setups auto-create it; others require manual creation.

"Template not found"​

The command looks for specs/_templates/feature-spec.md. If missing, it uses the built-in template. To customize, create the _templates directory and add your template.

"Branch already exists"​

If 004-real-time-chat already exists, you may have run the command twice or have a numbering conflict. Either switch to the existing branch and edit the spec, or use a different feature number if starting fresh.

"AI generated poor content"​

AI output quality depends on your feature description. Be more specific: include user roles, key scenarios, and constraints. If the output is generic, refine your input and re-run. You can also edit the generated spec directly—the command produces a draft, not a final document.

"Numbering is wrong"​

If the next number doesn't match your expectation, check the specs/ directory. The command uses the highest existing number + 1. Remove or rename any directories that shouldn't count (e.g., _templates is typically excluded).

When a feature spans multiple sub-features (e.g., "real-time chat" includes "chat rooms," "messaging," and "participant list"), you have two approaches:

Option A: Single spec with sections

One spec covers all sub-features. Use sections or subsections to organize:

## Feature 004: Real-Time Chat

### 004a: Chat Rooms
### 004b: Messaging
### 004c: Participant List

Option B: Separate specs with dependencies

Create separate specs (004a, 004b, 004c) and reference dependencies:

## Dependencies
- Requires 004a (Chat Rooms) to be implemented first

Choose based on your release strategy. Single spec keeps everything together; separate specs allow independent planning and implementation.

Frequently Asked Questions​

Q: Can I run /speckit.specify without a specs/ directory?
A: The command typically expects a specs/ directory. Create it if missing. Some setups auto-create it.

Q: What if I want to skip branch creation?
A: Some Spec Kit configurations allow a "no-branch" option. Check your tool's documentation. You can also create the branch manually and run the command with an existing branch.

Q: How do I handle features that span multiple specs?
A: Use Option A (single spec with sections) or Option B (separate specs with dependencies) from the "Advanced: Specifying Multiple Related Features" section.

Q: The AI generated implementation details. What do I do?
A: Remove them. Replace "Use WebSockets" with "Messages delivered within 2 seconds." The spec should describe behavior, not technology.

Q: How many [NEEDS CLARIFICATION] markers are acceptable?
A: Resolve critical ones before planning. You can defer non-critical ones to the plan phase. Document deferred items so they're not forgotten.

Try With AI​

Prompt 1: Specification Generation​

"I want to add a feature: [describe your feature in 1-2 sentences]. Run /speckit.specify to create a complete specification. Show me the generated spec.md and explain what each section contains. Identify any [NEEDS CLARIFICATION] markers and suggest how to resolve them."

Prompt 2: Specification Review​

"Review my specification at specs/[branch-name]/spec.md. Check for: (1) Implementation details that should be moved to the plan phase, (2) Missing edge cases, (3) Vague acceptance criteria that need to be more specific, (4) Missing non-goals. For each issue, suggest a concrete fix."

Prompt 3: Ambiguity Resolution​

"My spec has these [NEEDS CLARIFICATION] markers: [paste them]. For each one, list the options and tradeoffs. Help me decide which option to choose, or whether to defer to the plan phase. Then update the spec with the decisions."

Prompt 4: Template Customization​

"I need to add a [Security / Compliance / Localization] section to our feature specification template. What should that section contain? Show me the markdown structure and example content. Integrate it with our existing template at specs/_templates/feature-spec.md."

Practice Exercises​

Exercise 1: Specify from Scratch​

Choose a feature (e.g., "export data as CSV", "dark mode toggle", "in-app notifications"). Run /speckit.specify with a one-sentence description. Review the output. Add at least 2 edge cases and 3 non-goals that the generator missed. Resolve all [NEEDS CLARIFICATION] markers. Submit the completed spec.

Expected outcome: A complete specification with no ambiguities, comprehensive edge cases, and explicit non-goals.

Exercise 2: Specification Audit​

Take an existing specification (from a past project or a sample from the web). Audit it against the template structure: Does it focus on WHAT/WHY? Are there implementation details? Are edge cases documented? Are non-goals explicit? Write a 1-page audit report with specific improvements.

Expected outcome: An audit report identifying at least 5 improvement opportunities with concrete fixes.

Exercise 3: Template Design​

Design a custom specification template for a specific domain (e.g., API design, mobile app feature, data pipeline). Include: (1) Domain-specific sections, (2) Required checklist items, (3) Example content for one section. Document why each addition improves specification quality.

Expected outcome: A custom template with 2-3 new sections and a brief rationale document.

Key Takeaways​

  1. /speckit.specify transforms a simple feature description into a complete, structured specification. It automates feature numbering, branch creation, and template-based generation.

  2. Directory structure keeps all spec artifacts in specs/[branch-name]/. The main output is spec.md; other files (plan, tasks, contracts) come from later commands.

  3. The specification template constrains AI to focus on WHAT and WHY, avoid HOW, mark ambiguities with [NEEDS CLARIFICATION], and use completeness checklists. This produces specs that lead to better implementations.

  4. Focus on WHAT/WHY—requirements, user stories, acceptance criteria, edge cases. Technology decisions belong in the plan phase, not the spec.

  5. Non-goals and edge cases prevent scope creep and inconsistent behavior. Always include them. Use [NEEDS CLARIFICATION] when uncertain—do not guess.

  6. Customize the template for your project. Add domain-specific sections, constitution references, and required checklists. The command uses your template when present.

Quick Reference: /speckit.specify​

AspectDetail
InputFeature description (1–2 sentences or bullet points)
Outputspec.md in specs/[branch-name]/
AutomationFeature numbering, branch creation, template-based generation
Templatespecs/_templates/feature-spec.md (or built-in)
Key sectionsProblem, User Stories, FR, AC, Edge Cases, Non-Goals, Completeness Checklist
Constrains AIWHAT/WHY only; [NEEDS CLARIFICATION] for ambiguities
When to runNew feature, formalizing request, converting ticket to spec
Review time15–30 min after generation

Chapter Quiz​

  1. What are the three main things /speckit.specify automates (feature numbering, branch creation, and what else)?

  2. Why should specifications avoid implementation details (HOW)? What phase is responsible for technology decisions?

  3. What is the purpose of [NEEDS CLARIFICATION]? When should you use it instead of making a decision?

  4. Give an example of a requirement that belongs in a spec (WHAT/WHY) and one that does not (HOW).

  5. Why is the Non-Goals section important? What problem does it prevent?

  6. What directory structure does /speckit.specify create? Where does spec.md live?

  7. Name three common mistakes when writing specifications and how to avoid each.

  8. How do you customize the specification template for your project? Where does the custom template live?