spec-kit/templates/commands/specify.md

description, scripts

description	scripts
Create or update the feature specification from a natural language feature description.	sh ps scripts/bash/create-new-feature.sh --json "{ARGS}" scripts/powershell/create-new-feature.ps1 -Json "{ARGS}"

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

The text the user typed after /specify in the triggering message is the feature description. Assume you always have it available in this conversation even if {ARGS} appears literally below. Do not ask the user to repeat it unless they provided an empty command.

Given that feature description, do this:

1. Run the script {SCRIPT} from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute. IMPORTANT You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for.

2. Load templates/spec-template.md to understand required sections.

3. Follow this execution flow:

   1. Parse user description from Input If empty: ERROR "No feature description provided"
   2. Extract key concepts from description Identify: actors, actions, data, constraints
   3. For each unclear aspect: Mark with [NEEDS CLARIFICATION: specific question]
   4. Fill User Scenarios & Testing section If no clear user flow: ERROR "Cannot determine user scenarios"
   5. Generate Functional Requirements Each requirement must be testable Mark ambiguous requirements
   6. Identify Key Entities (if data involved)
   7. Return: SUCCESS (spec ready for planning)

4. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.

5. Specification Quality Validation: After writing the initial spec, validate it against quality criteria:

   a. Create Spec Quality Checklist: Generate a checklist file at FEATURE_DIR/checklists/spec.md using the checklist template structure with these validation items:

   # Specification Quality Checklist: [FEATURE NAME]
   
   **Purpose**: Validate specification completeness and quality before proceeding to planning
   **Created**: [DATE]
   **Feature**: [Link to 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
   - [ ] Requirements are testable and unambiguous
   - [ ] Success criteria are measurable
   - [ ] Scope is clearly bounded
   - [ ] Dependencies and assumptions identified
   
   ## Notes
   
   - Items marked incomplete require spec updates before `/clarify` or `/plan`
   

   b. Run Validation Check: Review the spec against each checklist item:

   • For each item, determine if it passes or fails
   • Document specific issues found (quote relevant spec sections)

   c. Handle Validation Results:

   • If all items pass: Mark checklist complete and proceed to step 6

   • If items fail (excluding [NEEDS CLARIFICATION]):

     1. List the failing items and specific issues
     2. Update the spec to address each issue
     3. Re-run validation until all items pass (max 3 iterations)
     4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user

   • If [NEEDS CLARIFICATION] markers remain:

     1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec

     2. For each clarification needed, present options to user in this format:

        ### Clarification Needed: [Topic]
        
        **Context**: [Quote relevant spec section]
        
        **Question**: [Specific question from NEEDS CLARIFICATION marker]
        
        | Option | Description | Implications |
        |--------|-------------|--------------|
        | A | [First option] | [What this means for the feature] |
        | B | [Second option] | [What this means for the feature] |
        | C | [Third option] | [What this means for the feature] |
        | Custom | Provide your own specification | [Explain how to provide custom input] |
        
        **Your choice**: _[Wait for user response]_
        

     3. Wait for user to respond with their choice (A, B, C, or custom input)

     4. Update the spec by replacing the [NEEDS CLARIFICATION] marker with the user's choice

     5. Repeat for all clarification markers

     6. Re-run validation after all clarifications are resolved

   d. Update Checklist: After each validation iteration, update the checklist file with current pass/fail status

6. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (/clarify or /plan).

NOTE: The script creates and checks out the new branch and initializes the spec file before writing.

General Guidelines

Quick Guidelines

• Focus on WHAT users need and WHY.
• Avoid HOW to implement (no tech stack, APIs, code structure).
• Written for business stakeholders, not developers.
• DO NOT create any checklists that are embedded in the spec. That will be a separate command.

Section Requirements

• Mandatory sections: Must be completed for every feature
• Optional sections: Include only when relevant to the feature
• When a section doesn't apply, remove it entirely (don't leave as "N/A")

For AI Generation

When creating this spec from a user prompt:

1. Mark all ambiguities: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make
2. Don't guess: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it
3. Think like a tester: Every vague requirement should fail the "testable and unambiguous" checklist item
4. Common underspecified areas:
   • User types and permissions
   • Data retention/deletion policies
   • Performance targets and scale
   • Error handling behaviors
   • Integration requirements
   • Security/compliance needs