Specify

/specforge:specify — capture WHAT to build

Turn a feature request into a testable specification. This is the Inception phase: describe the problem, users, and requirements — not the implementation. Delegate the drafting to the spec-analyst subagent when the feature is non-trivial.

When to use

• The user describes a new feature or capability to build.
• Trigger words: "specify", "write a spec", "requirements", "user stories", "new feature".

Preconditions

• A specforge/ workspace must exist. If not, run /specforge:init first.

Steps

1. Allocate the feature. Determine the next number NNN (highest existing under specforge/specs/ + 1) and a 3–4 word kebab slug from the request. Create specforge/specs/NNN-slug/ and specforge/specs/NNN-slug/contracts/. You may run the helper ${CLAUDE_SKILL_DIR}/../../scripts/new-feature.sh "<description>" which prints {feature_num, branch, feature_dir, spec_file} and creates the dirs — but doing it manually is fine.
2. Draft spec.md from the template at ${CLAUDE_SKILL_DIR}/../_shared/spec-template.md (or the inline structure below). Fill: Summary, Goals/Non-Goals, User Stories with Given/When/Then acceptance, Functional Requirements (FR-001…, each testable + uniquely IDed), Non-Functional Requirements (NFR-001…), conceptual Data/Domain, Edge Cases, Open Questions.
3. Never guess. For anything underspecified, insert [NEEDS CLARIFICATION: <question>] inline and list it under Open Questions. Do not invent stack, APIs, or file names — that is HOW.
4. Set the feature active in specforge/state.md: change the marker to <!-- active: NNN-slug --> and add/ensure a table row | NNN-slug | specify | done | <date> | (status done, not approved — approval is a separate human step).
5. Audit: append | <today ISO-8601> | NNN-slug | specify | Spec drafted (<n> open questions) |.
6. Tell the user the spec is drafted, how many [NEEDS CLARIFICATION] markers remain, and offer /specforge:clarify to resolve them, or /specforge:approve specify once they've reviewed it.

Spec skeleton (if the shared template is unavailable)

# Feature Specification: <name>
- Feature ID: NNN · Branch: NNN-slug · Status: Draft · Created: <date>
## Summary
## Goals & Non-Goals
## User Stories  (US1 … with Given/When/Then acceptance)
## Functional Requirements  (FR-001 …, testable, uniquely IDed)
## Non-Functional Requirements  (NFR-001 …)
## Data & Domain  (conceptual entities only)
## Edge Cases & Error Handling
## Open Questions  ([NEEDS CLARIFICATION] markers)
## Review Checklist (gate)

Guardrails

• WHAT/WHY only. If you catch yourself naming a library, table, or endpoint, move it to the plan.
• Every requirement must be independently testable and carry a stable ID for traceability.
• Marking specify done does not unblock coding — the gate needs specify approved and plan approved. Approvals are made by the human via /specforge:approve.