speckit-baseline

speckit-baseline

Source note: Thespec structureproduced by this skill follows the GitHub Spec Kit template conventions (MIT License, Copyright GitHub, Inc., full text in the same directory LICENSE.txt）。 "Reverse-extract requirements from existing code" execution flowis original to this project and is not part of the official Spec Kit command set.

When to Use

• The codebase lacks requirement documentation and a credible spec needs to be filled in.
• Before refactoring, migration, or handover, first solidify theexisting actual behaviorinto a reviewable baseline.
• When taking over an undocumented legacy system, it is necessary to distinguish "current behavior" from "intended behavior."

Inputs

• Target scope: paths, file lists, module names, or glob patterns.
• Codebase context: source code must be readable; if a .specify/ directory exists, also read the templates and scripts within it.
• Optional business background: domain terminology, user roles, external dependencies.

If the target scope is missing or ambiguous, ask one focused question before continuing.

Workflow

Step 1 — Define the scope

Confirm the smallest complete unit to analyze: one module, one set of interfaces, or one end-to-end flow. Too large a scope produces a vague spec; too small a scope cannot form complete requirements.

Step 2 — Extract observable behavior

Collect facts from the code, recording for each item theevidence location(file and line number):

• Entry points: HTTP routes, CLI arguments, event consumers, public APIs.
• Inputs and validation: accepted fields, types, constraints, default values.
• Outputs and side effects: response structures, storage writes, emitted events, external calls.
• Error paths: thrown exceptions, returned error codes, retry and fallback logic.
• State and lifecycle: persistence models, state machines, concurrency assumptions.

Record only the behavior that isobservablein the code. Do not infer design intent from naming or comments.

Step 3 — Synthesize into requirements

Aggregate the scattered behavioral facts into statements of "what the user/system can do":

• Each requirement must betestable— given an input, it is possible to judge whether it is satisfied.
• Preserve the distinction betweenintentional designandhistorical baggagein the existing behavior: when uncertain, classify it as an assumption or item to be clarified, and do not make excuses on behalf of the code author.
• Gaps discovered (such as unhandled edge cases) should be listed separately and not written directly as requirements.

Step 4 — Produce spec.md following the Spec Kit structure

Write to specs/<feature>/spec.md, following the Spec Kit conventions for section structure (see the next section). If .specify/templates/spec-template.md exists, it takes precedence.

Step 5 — Mark uncertainties and assumptions

• Keep at most 3 [NEEDS CLARIFICATION] markers, only for key disagreements affecting scope, safety, or user experience.
• Record all other uncertainties in the Assumptions section, documenting the reasonable defaults adopted.

Specification structure (following Spec Kit conventions)

• Mandatory sections: Every feature must complete this.
• Optional sections: Include only when relevant.
• When a section is not applicable,delete the entire section, do not leave "N/A".

Quality requirements(consistent with Spec Kit):

1. Prefer filling gaps with context and industry conventions rather than asking questions.
2. Record the defaults adopted in the Assumptions section.
3. Sort clarifying questions by priority: scope > safety/privacy > user experience > technical details.
4. Review from a tester's perspective: vague requirements should fail the "testable and unambiguous" check.

Success Criteria

Success criteria must satisfy:

1. Measurable —— include specific metrics (time, percentage, quantity, ratio).
2. Technology-agnostic —— do not mention frameworks, languages, databases, or tools.
3. User-centered —— describe outcomes from the user/business perspective, not internal system structure.
4. Verifiable —— can be checked without knowing implementation details.

Example (good): "Users can complete checkout within 3 minutes", "95% of searches return results within 1 second". Example (bad): "API response time under 200ms", "Redis cache hit rate above 80%".

Outputs

• specs/<feature>/spec.md —— baseline specification generated in reverse.
• If implementation gaps are found: list "differences from the existing implementation" separately in the report, do not write them into the specification body.

Guardrails

• Do not speculate about intent: Do not write requirements for things the code does not do.
• Distinguish baseline from target: What this skill produces is a "current behavior baseline", not a "desired state".
• Evidence is traceable: Every requirement should be traceable to a specific code location.
• Do not modify code: This is a read-only analysis process, and the only output is the specification document.