Spec-Kit Baseline

Generate structured feature specifications by analyzing existing source code. Reverse-engineers requirements, user stories, and success criteria from implementation.

When to Use

• Documenting existing features that lack specifications
• Understanding legacy code before refactoring
• Creating specs for inherited or acquired codebases
• Generating documentation from implemented functionality
• Preparing brownfield code for the Spec Kit workflow

Execution Workflow

The user's input after the skill invocation specifies the code to analyze. The workflow:

1. Parse target input: Identify files, directories, or patterns to analyze

   • Accept file paths, glob patterns, or directory paths
   • If empty: ERROR "No code target provided - specify files, directories, or patterns"

2. Discover and read source files:

   • Expand glob patterns to file list
   • Read file contents for analysis
   • Identify primary language(s) and frameworks
   • Map file relationships and dependencies

3. Analyze code structure:

   • Identify entry points and public interfaces
   • Extract function/method signatures and behaviors
   • Find data models and entities
   • Detect API endpoints and routes
   • Identify user-facing functionality

4. Generate short name (2-4 words) from analyzed code:

   • Use action-noun format (e.g., "user-auth", "payment-processing")
   • Base on primary functionality discovered
   • Preserve technical terms where meaningful

5. Check for existing branches/specs and run setup script:

   • Find highest feature number for this short-name
   • Run .specify/scripts/bash/create-new-feature.sh --json with calculated number and short-name
   • Get BRANCH_NAME and SPEC_FILE paths from JSON output

6. Load spec template from .specify/templates/spec-template.md

7. Generate specification content:

   • User Stories: Infer from user-facing code paths and interactions
   • Acceptance Scenarios: Derive from test cases, validation logic, error handling
   • Functional Requirements: Extract from business logic and constraints
   • Key Entities: Identify from data models and schemas
   • Success Criteria: Infer from existing metrics, logging, or performance code
   • Assumptions: Document inferences made during analysis

8. Abstract implementation details:

   • Convert technical patterns to user-focused requirements
   • Remove framework-specific terminology
   • Focus on WHAT the code does, not HOW it does it
   • Express behaviors in technology-agnostic terms

9. Create spec quality checklist at FEATURE_DIR/checklists/requirements.md

10. Report completion with:

    • Branch name and spec file path
    • Summary of analyzed files
    • Key features discovered
    • Areas needing clarification or review

Key Points

• Focus on extracting WHAT and WHY from HOW
• Abstract away implementation details in the generated spec
• Document assumptions made during code analysis
• Flag areas where code behavior is unclear
• Preserve discovered business rules and constraints
• Use [NEEDS CLARIFICATION] for ambiguous code sections (max 3)
• Generated specs should be validated by someone who knows the feature

Example Transformations

Code Pattern → Spec Requirement:

• if (user.role === 'admin') → "System MUST restrict action to administrator users"
• password.length >= 8 → "Passwords MUST be at least 8 characters"
• cache.set(key, value, 3600) → "System MUST cache results for improved performance"
• try { ... } catch (e) { notify(e) } → "System MUST notify users when errors occur"

Code Pattern → User Story:

• Login endpoint with OAuth → "As a user, I can sign in using my social account"
• Shopping cart logic → "As a customer, I can add items to my cart for later purchase"
• Report generation → "As an analyst, I can generate reports on system activity"

Next Steps

After generating spec.md:

• Clarify with domain experts using speckit-clarify
• Plan modernization/refactoring with speckit-plan
• Compare generated spec with actual requirements to identify gaps

See Also

• speckit-specify - Create specs from descriptions (forward direction)
• speckit-clarify - Resolve specification ambiguities
• speckit-plan - Create technical implementation strategy