specify

Interactive feature specification discovery through Socratic dialogue and systematic exploration.

/specify - Interactive Feature Specification Discovery

Given that feature description, do this:

  1. Generate a concise short name (2-4 words) for the SPEC_FILE:

    • 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 action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
    • Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
    • Keep it concise but descriptive enough to understand the feature at a glance
    • Examples:
      • "I want to add user authentication" → "user-auth"
      • "Implement OAuth2 integration for the API" → "oauth2-api-integration"
      • "Create a dashboard for analytics" → "analytics-dashboard"
      • "Fix payment processing timeout bug" → "fix-payment-timeout"

  2. Load reference/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 unclear aspects:
      • Make informed guesses based on context and industry standards
      • Only mark with [NEEDS CLARIFICATION: specific question] if:
        • The choice significantly impacts feature scope or user experience
        • Multiple reasonable interpretations exist with different implications
        • No reasonable default exists
      • Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
    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 Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
    6. Define Success Criteria Create measurable, technology-agnostic outcomes Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion) Each criterion must be verifiable without implementation details
    7. Identify Key Entities (if data involved)

  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.

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. Make informed guesses: Use context, industry standards, and common patterns to fill gaps
  2. Document assumptions: Record reasonable defaults in the Assumptions section
  3. Prioritize clarifications: scope > security/privacy > user experience > technical details
  4. Think like a tester: Every vague requirement should fail the "testable and unambiguous" checklist item
  5. Common areas needing clarification (only if no reasonable default exists):
    • Feature scope and boundaries (include/exclude specific use cases)
    • User types and permissions (if multiple conflicting interpretations possible)
    • Security/compliance requirements (when legally/financially significant)

Examples of reasonable defaults (don't ask about these):

  • Data retention: Industry-standard practices for the domain
  • Performance targets: Standard web/mobile app expectations unless specified
  • Error handling: User-friendly messages with appropriate fallbacks
  • Authentication method: Standard session-based or OAuth2 for web apps
  • Integration patterns: RESTful APIs unless specified otherwise

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, not system internals
  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"
  • "95% of searches return results in under 1 second"
  • "Task completion rate improves by 40%"

Bad examples (implementation-focused):

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

Next Step: After initial specification complete, interview user with all NEEDS CLARIFICATION questions.