speckit-specify-zh

User Input

$ARGUMENTS

Outline

$ARGUMENTS

1. Copy all files (including subdirectories) from

   assets/specify/

   to the

   .specify

   directory under the repository root directory while preserving the original directory structure, skip existing files, do not overwrite existing files with the same name. The -n (--no-clobber) option of the cp command can prevent overwriting existing files. At this stage, your project folder content should be similar to the following:

Repository root directory
└── .specify
    ├── memory
    │  └── constitution.md
    ├── scripts
    │  ├──bash    
    │  │  ├── check-prerequisites.sh
    │  │  ├── common.sh
    │  │  ├── create-new-feature.sh
    │  │  ├── setup-plan.sh
    │  │  └── update-claude-md.sh
    │  ├──powershell    
    │  │  ├── check-prerequisites.ps1
    │  │  ├── common.ps1
    │  │  ├── create-new-feature.ps1
    │  │  ├── setup-plan.ps1
    │  │  └── update-claude-md.ps1    
    ├── specs
    │  └── 001-create-taskify
    │      └── spec.md
    └── templates
        ├── plan-template.md
        ├── spec-template.md
        └── tasks-template.md

1. Generate a concise short name (2-4 words) for the branch:
   • Analyze the feature description and extract the most meaningful keywords
   • Create a 2-4 word short name that captures the essence of the feature
   • Use verb-noun format whenever possible (e.g., "add-user-auth", "fix-payment-bug")
   • Retain technical terms and abbreviations (OAuth2, API, JWT, etc.)
   • Keep it concise yet descriptive enough to understand the feature at a glance
   • Examples:
     • "I want to add user authentication" → "user-auth"
     • "Implement OAuth2 integration for API" → "oauth2-api-integration"
     • "Create analytics dashboard" → "analytics-dashboard"
     • "Fix payment processing timeout error" → "fix-payment-timeout"
2. Check existing branches before creating a new branch:
   a. First fetch all remote branches to ensure you have the latest information:
   bash

   git fetch --all --prune

   b. Find the highest feature number with the short name across all sources:
   • Remote branches:

     git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'

   • Local branches:

     git branch | grep -E '^[* ]*[0-9]+-<short-name>$'

   • Specification directories: Check directories matching

     specs/[0-9]+-<short-name>

   c. Determine the next available number:
   • Extract all numbers from all three sources
   • Find the largest number N
   • Use N+1 for the new branch
   d. Run the script

   create-new-feature.ps1 -Json "$ARGUMENTS"

   using the calculated number and short name:
   • Pass

     --number N+1

     and

     --short-name "your-short-name"

     along with the feature description
   • Bash example:

     create-new-feature.sh -Json "$ARGUMENTS" --json --number 5 --short-name "user-auth" "Add user authentication"

   • PowerShell example:

     create-new-feature.ps1 -Json "$ARGUMENTS" -Json -Number 5 -ShortName "user-auth" "Add user authentication"

   Important:
   • Check all three sources (remote branches, local branches, specification directories) to find the highest number
   • Only match branches/directories with the exact short name pattern
   • If no existing branches/directories with this short name are found, start from number 1
   • Run this script only once per feature
   • JSON is provided as output in the terminal - always refer to it for the actual content you are looking for
   • The JSON output will include BRANCH_NAME and SPEC_FILE path
   • For single quotes in arguments like "I'm Groot", use escape syntax: e.g., 'I'''m Groot' (or use double quotes if possible: "I'm Groot")
3. Load

   .specify/templates/spec-template.md

   to understand the required sections.
4. Follow this execution flow:
   1. Parse the user description from the input If empty: Error "No feature description provided"
   2. Extract key concepts from the description Identify: Actors, Actions, Data, Constraints
   3. For unclear aspects:
      • Make educated guesses based on context and industry standards
      • Only mark [Needs clarification: specific question] if:
        • The choice significantly impacts feature scope or user experience
        • There are multiple reasonable interpretations with different implications
        • No reasonable default exists
      • Limit: Maximum 3 [Needs clarification] marks total
      • Prioritize by impact: Scope > Security/Privacy > User Experience > Technical Details
   4. Fill in the User Scenarios & Testing section If no clear user flow: Error "Unable to determine user scenarios"
   5. Generate functional requirements Each requirement must be testable Use reasonable defaults for unspecified details (document assumptions in the Assumptions section)
   6. Define success criteria Create measurable, technology-agnostic results Include quantitative metrics (time, performance, quantity) and qualitative measures (user satisfaction, task completion rate) Each criterion must be verifiable without implementation details
   7. Identify key entities (if data is involved)
   8. Return: Success (Specification is ready for planning)
5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with specific details derived from the feature description (arguments), while maintaining the section order and titles unchanged.
6. Specification Quality Verification: After writing the initial specification, verify it against quality standards:
   a. Create Specification Quality Checklist: Generate a checklist file in

   FEATURE_DIR/checklists/requirements.md

   using the checklist template structure, refer to: assets/quality-checklist-template.md
   b. Run Verification Checks: Review the specification against each checklist item:
   • For each item, determine if it passes or fails
   • Record specific issues found (reference relevant specification sections)
   c. Handle Verification Results:
   • If all items pass: Mark the checklist as complete and proceed to step 6
   • If any items fail (excluding [Needs clarification]):
     1. List the failed items and specific issues
     2. Update the specification to address each issue
     3. Re-run verification until all items pass (maximum 3 iterations)
     4. If still failing after 3 iterations, record remaining issues in the checklist comments and issue a warning to the user
   • If [Needs clarification] marks exist:
     1. Extract all [Needs clarification: ...] marks from the specification
     2. Limit Check: If there are more than 3 marks, only keep the top 3 most important ones by scope/security/user experience impact, and make educated guesses for the rest
     3. For each clarification needed (maximum 3), present options to the user by referring to assets/clarification-template.md
     4. Critical - Table Formatting: Ensure markdown tables are correctly formatted:
        • Use consistent spacing, aligned pipes
        • Each cell should have spaces around content:

          | Content |

          instead of

          |Content|

        • Header separators must have at least 3 dashes:

          |--------|

        • Test that tables render correctly in markdown preview
     5. Number the questions in order (Q1, Q2, Q3 - maximum 3 total)
     6. Present all questions together before waiting for a response
     7. Wait for the user's response with their choices for all questions (e.g., "Q1: A, Q2: Custom - [Details], Q3: B")
     8. Update the specification by replacing each [Needs clarification] mark with the user's selected or provided answer
     9. Re-run verification after all clarifications are resolved
   d. Update Checklist: After each verification iteration, update the checklist file with the current pass/fail status
7. Report completion status, including branch name, specification file path, checklist results, and readiness for the next phase (

   speckit-clarify

   or

   speckit-plan

   ).

General Guidelines

Quick Guide

• Focus on what the user needs and why
• Avoid how to implement (no tech stack, APIs, code structure)
• Write for business stakeholders, not developers
• Do not create any checklists embedded in the specification. That will be a separate command

Section Requirements

• Required Sections: Must be completed for every feature
• Optional Sections: Include only if relevant to the feature
• When a section is not applicable, delete it entirely (do not leave "N/A")

For AI Generation

1. Make educated guesses: Fill gaps using context, industry standards, and common patterns
2. Document assumptions: Record reasonable defaults in the Assumptions section
3. Limit clarifications: Maximum 3 [Needs clarification] marks - only for those:
   • Critical decisions that significantly impact feature scope or user experience
   • Situations with multiple reasonable interpretations with different implications
   • Cases where no reasonable default exists
4. Prioritize clarifications: Scope > Security/Privacy > User Experience > Technical Details
5. Think like a tester: Every ambiguous requirement should fail the "testable and clear" checklist item
6. Common areas needing clarification (only if no reasonable default exists):
   • Feature scope and boundaries (including/excluding specific use cases)
   • User types and permissions (if multiple conflicting interpretations are possible)
   • Security/compliance requirements (when legally/financially important)

• Data retention: Industry standard practices in the domain
• Performance targets: Standard web/mobile application expectations, unless specified otherwise
• Error handling: User-friendly messages and appropriate fallbacks
• Authentication methods: Standard session-based or OAuth2-based web applications
• Integration patterns: RESTful API, unless stated otherwise

Success Criteria Guidelines

1. Measurable: Include specific metrics (time, percentage, count, ratio)
2. Technology-agnostic: Do not mention frameworks, languages, databases, or tools
3. User-centric: Describe results from the user/business perspective, not internal system mechanisms
4. Verifiable: Testable/verifiable without knowing implementation details

• "Users can complete checkout within 3 minutes"
• "System supports 10,000 concurrent users"
• "95% of searches return results within 1 second"
• "Task completion rate increases by 40%"

• "API response time is less than 200ms" (too technical, should use "Users see results instantly")
• "Database can handle 1000 TPS" (implementation detail, should use user-centric metrics)
• "React components render efficiently" (framework-specific)
• "Redis cache hit rate is higher than 80%" (technology-specific)