Spec Kit Specify

Create or refresh the feature specification for the active Spec Kit feature.

When to Use

• Start a new feature and create the first spec.md.
• Convert free-form requirements into a structured, testable, implementation-agnostic specification.
• Rework an existing spec draft so it is ready for spec-kit-clarify or spec-kit-plan.

When Not to Use

• Clarify ambiguity in an already-written spec without redrafting it (spec-kit-clarify).
• Generate design artifacts or tasks from an approved spec (spec-kit-plan, spec-kit-tasks).
• Reconcile cross-artifact drift in an existing feature (spec-kit-reconcile).

Router Fit

• Primary route from spec-kit when spec.md does not exist yet.
• Downstream: hand off to spec-kit-clarify (if high-impact ambiguity remains) or spec-kit-plan (if spec is ready).

Preconditions

• User provided a non-empty feature description.
• Run from repository root (or a subdirectory inside the repository).

Workflow

1. Normalize input:

   • Treat the full user request as the feature description.
   • If empty, stop: ERROR: No feature description provided.

2. Generate a short branch suffix (2-4 words, kebab-case):

   • Preserve meaningful technical terms/acronyms.
   • Prefer action-noun phrasing (for example user-auth, bulk-export-audit-log).

3. Bootstrap feature branch and spec exactly once:

   • Run scripts/create-new-feature.sh --json --short-name "<short-name>" "<feature description>".
   • Do not manually pre-compute branch numbers; let the script assign the next number.
   • Parse JSON output and capture:
     • BRANCH_NAME
     • SPEC_FILE
     • FEATURE_NUM
   • Derive FEATURE_DIR as dirname(SPEC_FILE).

4. Load template context:

   • Preferred template: {REPO_ROOT}/templates/spec-template.md.
   • Fallback template: assets/spec-template.md.
   • Preserve heading order from the selected template.

5. Draft spec.md content (focus on WHAT/WHY, not HOW):

   • Fill prioritized user stories with independent tests and acceptance scenarios.
   • Write testable functional requirements.
   • Add edge cases and scope boundaries.
   • Add measurable, technology-agnostic success criteria.
   • Include key entities when data is central.
   • Use reasonable defaults and document assumptions when needed.

6. Clarification policy while drafting:

   • First, make informed defaults using domain norms.
   • Add [NEEDS CLARIFICATION: ...] only for high-impact uncertainty.
   • Hard limit: at most 3 clarification markers.
   • Prioritize by impact: scope > security/privacy > UX > technical detail.

7. Write the spec to SPEC_FILE.

8. Create and run requirements quality validation:

   • Create FEATURE_DIR/checklists/requirements.md.
   • Validate spec against this checklist:
     • No implementation details (frameworks, languages, APIs, internal architecture).
     • Mandatory sections are complete.
     • Requirements are unambiguous and testable.
     • Success criteria are measurable and technology-agnostic.
     • User scenarios and edge cases are covered.
     • Scope boundaries, dependencies, and assumptions are explicit.
     • No unresolved [NEEDS CLARIFICATION] markers for plan-ready specs.
   • If non-clarification issues fail, revise spec and re-validate (max 3 passes).

9. If clarification markers remain after validation:

   • Ask up to 3 numbered clarification questions total.
   • For each question, present 2-3 concrete options plus a short custom answer path.
   • Wait for user responses, update spec.md, then re-run validation.

10. Report completion:

• Branch name.
• spec.md path.
• requirements.md path and pass/fail summary.
• Recommended next step:
  • spec-kit-clarify if high-impact ambiguity remains.
  • spec-kit-plan if ready.

Output

• Active feature branch from scripts/create-new-feature.sh
• specs/<feature>/spec.md
• specs/<feature>/checklists/requirements.md
• readiness handoff for spec-kit-clarify or spec-kit-plan

Common Mistakes

• Writing implementation design into the spec instead of user-visible behavior and outcomes.
• Leaving vague requirements that cannot be acceptance-tested.
• Asking too many clarification questions instead of making reasonable defaults.
• Running feature bootstrap script multiple times for one request.

References

• references/spec-kit-workflow.dot
• scripts/create-new-feature.sh
• assets/spec-template.md
• https://github.com/github/spec-kit/blob/9111699cd27879e3e6301651a03e502ecb6dd65d/templates/commands/specify.md