spec-kit-specify

name	spec-kit-specify
description	Use when a Spec Kit feature needs `spec.md` authored or rewritten from natural-language requirements, especially when the feature has no usable specification or requirements are too vague for planning.

Spec Kit Specify

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

Invocation Notice

• Inform the user when this skill is being invoked by name: spec-kit-specify.

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