speckit-baseline

---
name: speckit-baseline
description: "Generate a technology-agnostic feature specification by analyzing existing source code, extracting user stories, functional requirements, and acceptance criteria from code patterns. Use when the user needs to document an existing or legacy codebase, create a spec before refactoring, or reverse-engineer requirements from source files."
---

# 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

1. **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.

2. **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.

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 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.

5. **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").

6. **Load the spec template** from `.specify/templates/spec-template.md`.

7. **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.

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.

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.

## Outputs

- `specs/<feature>/spec.md`
- `specs/<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.