Spec Kit Baseline Skill
When to Use
- You need a spec for existing or legacy code.
- You want to document a feature before refactoring.
- You inherited a codebase without written requirements.
Inputs
- A target path, file list, or glob pattern describing the code to analyze.
- Repo context with
.specify/scripts and templates.
If the target is missing or ambiguous, ask a focused question before continuing.
Goal
Generate a technology-agnostic spec for existing code, then create the feature branch/spec file using the standard Spec Kit templates.
Workflow
- Parse target input: Identify files, directories, or patterns to analyze.
- Accept file paths, glob patterns, or directory paths. - If empty: stop and ask for a concrete target.
- Discover and read source files:
- Expand globs to a file list. - Read file contents for analysis. - Identify primary language(s) and frameworks. - Map key file relationships and dependencies.
- 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.
- Generate a short name (2-4 words) from the analyzed code:
- Use action-noun format (e.g., "user-auth", "payment-processing"). - Base on primary functionality discovered. - Preserve technical terms where meaningful.
- Create the feature branch and spec file:
- Find the highest existing feature number for this short name (branches/specs). - Run .specify/scripts/bash/create-new-feature.sh --json with the calculated number and short name. - Read BRANCH_NAME, FEATURE_DIR, and SPEC_FILE paths from the script JSON output. - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").
- Load the spec template from
.specify/templates/spec-template.md. - Draft the specification using the template structure:
- User Stories: Infer from user-facing code paths and interactions. - Acceptance Scenarios: Derive from validation logic, error handling, and tests. - Functional Requirements: Extract from business rules and constraints. - Key Entities: Identify from data models and schemas. - Success Criteria: Infer from metrics, logging, or performance-related code. - Assumptions: Document inferences made during analysis.
- 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.
- Create spec quality checklist at
FEATURE_DIR/checklists/requirements.md. - Report completion with:
- Branch name and spec file path. - Summary of analyzed files. - Key features discovered. - Areas needing clarification or review.
Outputs
specs/<feature>/spec.mdspecs/<feature>/checklists/requirements.md
Key rules
- 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.
Examples
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 the generated spec with actual requirements to identify gaps.