/spec-kitty.specify - Create Mission Specification
Version: 0.11.0+
📍 WORKING DIRECTORY: Stay in the repository root checkout
IMPORTANT: Specify works in the repository root checkout. NO worktrees are created.
# Run from the repository root checkout:
cd /path/to/project/root # Your repository root checkout
# All planning artifacts are created in the project root and committed:
# - kitty-specs/<mission_slug>/spec.md → Created in project root
# (use the mission_slug returned by `mission create`; the numeric NNN- prefix
# is display-only and is assigned at merge time)
# - Committed to target branch (from create JSON: target_branch/base_branch)
# - NO worktrees created
Worktrees are created later during /spec-kitty.implement, after task finalization computes execution lanes.
Mission Handle Rule
Before mission create, there is no mission handle yet.
- Do not pass
--mission to spec-kitty agent mission branch-context.
- Do not pass
--mission to spec-kitty agent mission create.
- After
create succeeds, use --mission <handle> for commands that operate on
the created mission.
<handle> can be the mission's mission_id (ULID), mid8 (first 8 chars of
the ULID), or mission_slug.
- The resolver disambiguates by
mission_id and returns a structured
MISSION_AMBIGUOUS_SELECTOR error on ambiguity — there is no silent fallback.
User Input
The content of the user's message that invoked this skill (everything after the skill invocation token, e.g. after /spec-kitty.<command> or $spec-kitty.<command>) is the User Input referenced elsewhere in these instructions.
You MUST consider this user input before proceeding (if not empty).
Primary Invariant: What Are We Building?
This workflow answers "What are we building?" before it creates artifacts. The
raw invocation text is only a starting point for discovery, not the final truth.
Before mission create, before writing spec.md, and before committing
anything, you MUST have one of these:
- A completed discovery interview with an acknowledged Intent Summary.
- A brief-intake summary and extracted requirement set explicitly confirmed by
the user.
- An explicit user instruction to minimize or skip discovery; even then, record
the minimal confirmed scenario and assumptions in the Intent Summary.
For non-trivial work, the confirmed Intent Summary must cover the primary actor,
trigger, desired outcome, one rule or invariant, and any canonical domain term
or boundary that materially affects the work.
Branch Strategy Confirmation (MANDATORY)
Before discovery, resolve branch intent through the Python helper, not by probing git directly:
spec-kitty agent mission branch-context --json
If the user already told you the intended landing branch, pass it explicitly:
spec-kitty agent mission branch-context --json --target-branch <intended-branch>
Parse the JSON and, in your next reply, explicitly tell the user:
- Current branch at workflow start:
current_branch
- Default planning/base branch if you create the mission right now:
planning_base_branch
- Final merge target for completed changes:
merge_target_branch
- Whether
branch_matches_target is true or false
- If that is not the intended landing branch, stop and ask which branch should receive this feature before you run
create
Never talk generically about main or "the default branch". Name the actual branch values from the helper JSON. Do not shell out to git for this prompt.
Commit Boundary (issue #846)
spec-kitty agent mission create no longer auto-commits spec.md. The empty
template is written to disk untracked at create time; you are responsible
for committing it after writing substantive content.
"Substantive content" for spec.md means at least one Functional
Requirements row (FR-###) whose description is real (not a template
placeholder like [NEEDS CLARIFICATION …], [e.g., …], or a bare user-story
scaffold). Section presence is the only signal — adding 300 bytes of arbitrary
prose without an FR row does not count as substantive.
Workflow:
- Run
spec-kitty agent mission create …. Note that spec.md is left
untracked.
- Populate
spec.md with real Functional / Non-Functional / Constraint rows.
- Commit
spec.md yourself: git add <feature_dir>/spec.md && git commit -m "Add spec for <slug>".
- Only then will
spec-kitty agent mission setup-plan accept the spec phase
as complete; otherwise it returns phase_complete=false with a
blocked_reason mentioning "committed AND substantive".
Reference: kitty-specs/charter-e2e-827-followups-01KQAJA0/contracts/specify-plan-commit-boundary.md.
DO NOT
- Do not mix functional, non-functional, and constraint requirements in one list.
- Do not emit requirements without stable IDs (
FR-###, NFR-###, C-###).
- Do not leave requirement status fields empty.
- Do not write non-functional requirements without measurable thresholds.
- Do not proceed to planning with unresolved requirement quality checklist failures.
Charter Context Bootstrap (required)
Before discovery questions, load charter context for this action:
spec-kitty charter context --action specify --json
- If JSON
mode is bootstrap, treat JSON text as the initial governance context and consult referenced docs as needed.
- If JSON
mode is compact, proceed with concise governance context.
- If no charter exists yet, note that and continue. Missing charter is not a
blocker for
/spec-kitty.specify.
Brief Context Detection (check before discovery)
Before starting discovery, check for a pre-existing mission brief:
ls .kittify/mission-brief.md 2>/dev/null && echo "MISSION_BRIEF_FOUND"
ls .kittify/ticket-context.md 2>/dev/null && echo "TICKET_CONTEXT_FOUND"
Check in priority order:
.kittify/mission-brief.md — general plan intake (written by spec-kitty intake)
.kittify/ticket-context.md — tracker ticket (written by mission create --from-ticket)
If a brief file is found → Enter Brief-Intake Mode
BRIEF DETECTED: .kittify/<filename> (source: <source_file>)
Read the full brief. Do not skim.
Summarise for the user. Present a single paragraph: what the brief says the goal is, who it is for, and what the key constraints are. Example: "I found a plan document from Claude Code plan mode. Here's what I understand the goal to be: [summary]. I'll extract the spec from this brief rather than running a full discovery interview."
Extract requirements directly. Map the brief's content to FR-###, NFR-###, and C-### IDs. Do not ask questions the brief already answers. Specifically extract:
- Objective → Functional Requirements
- Constraints and non-goals → Non-Functional Requirements and Constraints
- Acceptance criteria → FR status and Definition of Done markers
- Risks and open questions → Assumptions or
[NEEDS CLARIFICATION: <text>] <!-- decision_id: <id> --> markers (max 3; use decision defer before writing each marker)
Ask gap-filling questions only. Scale to brief quality:
| Brief quality |
Discovery questions |
| Comprehensive (objective + constraints + approach + ACs) |
0–1 gap-filling questions |
| Good (objective + constraints, no ACs) |
2–3 questions |
| Partial (goal statement only) |
4–5 questions |
| Empty / missing |
Proceed to normal Discovery Gate below |
Show the extracted requirement set. Present the full FR/NFR/C table to the user: "I extracted X functional requirements and Y non-functional requirements. Does this look right?" Wait for one round of confirmation. This confirmation is the discovery gate for brief-intake mode; do not write or commit spec.md before it happens unless the user explicitly asks to minimize or skip discovery. The user may correct or supplement before you write the spec.
Write spec.md normally. Apply the same quality checklist and readiness gate as standard specify. Brief-intake mode does NOT lower the quality bar — spec.md must still pass all validation items.
After spec.md is committed, delete all brief files (each only if present):
rm -f .kittify/mission-brief.md
rm -f .kittify/brief-source.yaml
rm -f .kittify/ticket-context.md
rm -f .kittify/pending-origin.yaml
What brief-intake mode does NOT do:
- Does not copy brief prose verbatim into spec.md — it extracts and structures requirements
- Does not skip the quality checklist
- Does not skip the readiness gate
- Does not require the brief to be in any particular format — Markdown prose is fine
If no brief file is found → Proceed with normal Discovery Gate
No change to current behaviour. Continue to the Discovery Gate section below.
Decision Moment Protocol
Before asking any interview question during this command, you MUST:
Run spec-kitty agent decision open to mint a decision_id:
spec-kitty agent decision open \
--mission <mission-slug> \
--flow specify \
--slot-key specify.<section>.<question-slug> \
--input-key <snake_case_key> \
--question "<question text>" \
[--options '["option1","option2","Other"]']
Capture the returned decision_id from the JSON output.
Ask the question to the user in chat.
After the user answers, run exactly one of:
- Resolved answer:
spec-kitty agent decision resolve <decision_id> --mission <slug> --final-answer "<answer>" [--other-answer]
- Deferred / skip:
spec-kitty agent decision defer <decision_id> --mission <slug> --rationale "<reason>"
- Not applicable / cancel:
spec-kitty agent decision cancel <decision_id> --mission <slug> --rationale "<reason>"
When deferring, write the inline marker into spec.md immediately after the
relevant section:
[NEEDS CLARIFICATION: <brief description of what needs answering>] <!-- decision_id: <decision_id> -->
Before declaring the interview phase complete, run:
spec-kitty agent decision verify --mission <slug>
Address any findings (DEFERRED_WITHOUT_MARKER, MARKER_WITHOUT_DECISION,
STALE_MARKER) before proceeding.
Important constraints:
--slot-key format: specify.<section>.<question-slug> (e.g.,
specify.auth.strategy).
--input-key is the snake_case programmatic key (e.g., auth_strategy).
- The
decision_id on the wire is a plain ULID (26 chars). The DM- prefix
appears only in artifact filenames, not in CLI arguments.
- Widening is represented by the CLI/SaaS widen flow; if that flow returns
canonical thread metadata, it must be recorded as
DecisionPointWidened.
- SaaS sync is not required; all operations are local-only.
Discovery Gate (mandatory)
Before running mission create, writing spec.md, committing, or otherwise creating planning artifacts, you must conduct or verify a structured discovery interview.
Scope proportionality (CRITICAL): FIRST, gauge the inherent complexity of the request:
- Trivial/Test Features (hello world, simple pages, proof-of-concept): Ask 1-2 questions maximum, then proceed. Examples: "a simple hello world page", "tic-tac-toe game", "basic contact form"
- Simple Features (small UI additions, minor enhancements): Ask 2-3 questions covering purpose and basic constraints
- Complex Features (new subsystems, integrations): Ask 3-5 questions covering goals, users, constraints, risks
- Platform/Critical Features (authentication, payments, infrastructure): Full discovery with 5+ questions
Scenario-first discovery: For any non-trivial feature, prefer concrete
workflow questions over abstract opinion prompts. Ask for the primary actor,
trigger, happy-path outcome, and the most common exception or branch.
Terminology discipline: If the request introduces business or domain
terms that may drift, ask which term is canonical and which synonyms should
be avoided. When relevant, carry those choices into the optional Domain
Language section of the spec instead of leaving them implicit.
Rule probing: For workflows with approvals, validations, state changes,
or compliance implications, ask what must always be true and which
transitions or checks cannot be skipped.
User signals to reduce questioning: If the user says "just testing", "quick prototype", "skip to next phase", "stop asking questions" - recognize this as a signal to minimize discovery and proceed with reasonable defaults.
First response rule:
- For TRIVIAL features (hello world, simple test): Ask ONE clarifying question, then if the answer confirms it's simple, proceed directly to spec generation
- For other features: Ask a single focused discovery question anchored in the primary user scenario and end with
WAITING_FOR_DISCOVERY_INPUT
If the user provides no initial description (empty command), stay in Interactive Interview Mode: keep probing with one question at a time.
Conversational cadence: After each user reply, decide if you have ENOUGH context for this feature's complexity level. For trivial features, 1-2 questions is sufficient. Only continue asking if truly necessary for the scope.
Discovery requirements (scale to feature complexity):
- Maintain a Discovery Questions table internally covering questions appropriate to the feature's complexity (1-2 for trivial, up to 5+ for complex). Track columns
#, Question, Why it matters, and Current insight. Do not render this table to the user.
- For trivial features, reasonable defaults are acceptable. Only probe if truly ambiguous.
- When you have sufficient context for the feature's scope, paraphrase into an Intent Summary and confirm. For trivial features, this can be very brief. For non-trivial features, include the primary actor, trigger/success outcome, key constraint, and any explicit assumptions or deferred decisions.
- Before leaving the interview loop, do a short playback of the primary scenario, the main exception or edge case, and any rule that must always hold.
- If user explicitly asks to skip questions or says "just testing", acknowledge and proceed with minimal discovery.
Bulk-Edit Detection (mandatory check)
Before finalizing the Intent Summary, ask yourself one question:
Does fulfilling this request require changing the same existing string
(identifier, path, key, label, or term) in more than one file?
Typical shapes: "rename X to Y", "the Blue feature is now the Red feature",
"change the terminology from X to Y", "move package A to package B", "replace
ACME with GlobalCorp everywhere in docs and UI".
If yes or uncertain: load the spec-kitty-bulk-edit-classification skill
and follow it. You will set change_mode: bulk_edit in meta.json after
mission create and produce an occurrence_map.yaml during plan. The user
does not need to know these field names — the skill teaches you the workflow.
If clearly no (a new feature with new identifiers, a bug fix that doesn't
rename anything, a refactor inside one file): proceed normally.
When in doubt, treat as bulk edit. The false-positive cost is drafting one map
the user approves in a pass; the false-negative cost is the silent cross-file
breakage that DIRECTIVE_035 exists to prevent.
Mission Selection
After completing discovery and confirming the Intent Summary, determine the appropriate mission type for this mission run.
Available Missions
software-dev: For building software features, APIs, CLI tools, applications
- Phases: research → design → implement → test → review
- Best for: code changes, new features, bug fixes, refactoring
research: For investigations, literature reviews, technical analysis
- Phases: question → methodology → gather → analyze → synthesize → publish
- Best for: feasibility studies, market research, technology evaluation
Mission Inference
Analyze the feature description to identify the primary goal:
- Building, coding, implementing, creating software → software-dev
- Researching, investigating, analyzing, evaluating → research
Check for explicit mission requests in the user's description:
- If user mentions "research project", "investigation", "analysis" → use research
- If user mentions "build", "implement", "create feature" → use software-dev
Confirm with user (unless explicit):
"Based on your description, this sounds like a [software-dev/research] project.
I'll use the [mission name] mission. Does that work for you?"
Handle user response:
- If confirmed: proceed with selected mission
- If user wants different mission: use their choice
Handle --mission flag: If the user provides --mission <key> in their command, skip inference and use the specified mission directly.
Store the final mission selection in your notes and include it in the spec output. Do not pass a --mission-type flag to mission creation unless the user explicitly overrides the default.
Workflow (0.11.0+)
Planning happens in the repository root checkout - NO worktree created!
- Creates
kitty-specs/<mission_slug>/spec.md directly in project root (the optional NNN- prefix is display-only metadata assigned at merge time)
- Automatically commits to target branch
- No worktree created during specify
Worktrees created later: After /spec-kitty.tasks finishes, run: spec-kitty next --agent <agent> --mission <handle>. The --mission handle can be the mission's mission_id (ULID), mid8 (first 8 chars), or mission_slug; the resolver disambiguates by mission_id and returns a structured error on ambiguity (no silent fallback). Your agent will call spec-kitty agent action implement WP## --agent <name> for each WP. Each lane gets exactly one worktree, for example .worktrees/<human-slug>-<mid8>-lane-a/ (e.g. .worktrees/my-feature-01J6XW9K-lane-a/).
Location
- Work in: Repository root checkout (not a worktree)
- Creates:
kitty-specs/<mission_slug>/spec.md (the NNN- prefix is display-only and assigned at merge time)
- Commits to: target branch (from
create --json → target_branch)
Outline
0. Generate a Friendly Feature Title
- Summarize the agreed intent into a short, descriptive title (aim for ≤7 words; avoid filler like "feature" or "thing").
- Read that title back during the Intent Summary and revise it if the user requests changes.
- Use the confirmed title to derive the kebab-case feature slug for the create command.
The text the user typed after /spec-kitty.specify in the triggering message is the initial feature description. Capture it verbatim, but treat it only as a starting point for discovery—not the final truth. Your job is to interrogate the request, surface gaps, and co-create a complete specification with the user.
Given that feature description, do this:
- Generation Mode (arguments provided): Use the provided text as a starting point, validate it through discovery, and fill gaps with explicit questions or clearly documented assumptions (limit
[NEEDS CLARIFICATION: …] <!-- decision_id: <id> --> to at most three critical decisions the user has postponed; call decision defer before writing each such marker).
- Interactive Interview Mode (no arguments): Use the discovery interview to elicit all necessary context, synthesize the working feature description, and confirm it with the user before you generate any specification artifacts.
Check discovery status:
- If this is your first message or discovery questions remain unanswered, stay in the one-question loop, capture the user's response, update your internal table, and end with
WAITING_FOR_DISCOVERY_INPUT. Do not surface the table; keep it internal. Do not call the creation command yet.
- Only proceed once every discovery question has an explicit answer and the user has acknowledged the Intent Summary.
- Empty invocation rule: stay in interview mode until you can restate the agreed-upon feature description. Do not call the creation command while the description is missing or provisional.
When discovery is complete and the intent summary, title, purpose TLDR, purpose context paragraph, and mission type are confirmed, run the mission creation command from repo root:
spec-kitty agent mission create "<slug>" \
--friendly-name "<title>" \
--purpose-tldr "<purpose_tldr>" \
--purpose-context "<purpose_context>" \
--json
Where <slug> is a kebab-case version of the friendly title (e.g., "Checkout Upsell Flow" → "checkout-upsell-flow").
The command returns JSON with:
result: "success" or error message
mission_id: Canonical ULID machine identity (e.g., 01J6XW9KQT7M0YB3N4R5CQZ2EX). Immutable.
mission_slug: Human-readable mission slug (e.g., checkout-upsell-flow)
mission_number: Display-only numeric prefix, null pre-merge. Assigned at merge time. Never use this as a selector or identity.
mission_type: Mission type key (for example software-dev)
slug: Unnumbered mission slug (e.g., checkout-upsell-flow)
friendly_name: Confirmed mission title
purpose_tldr: One-line stakeholder-facing mission summary
purpose_context: Short stakeholder-facing context paragraph
feature_dir: Absolute path to the feature directory inside the repository root checkout
current_branch: the branch you started from
target_branch / base_branch: deterministic branch contract for downstream commands
planning_base_branch / merge_target_branch: explicit landing-branch aliases
branch_strategy_summary: human-readable summary of the branch contract
Parse these values for use in subsequent steps. All file paths are absolute.
IMPORTANT: You must only ever run this command once. The JSON is provided in the terminal output - always refer to it to get the actual paths you're looking for.
Immediately restate the branch contract to the user after parsing the JSON:
- Current branch at start
- Intended planning/base branch
- Final merge target for later changes
- Whether that matches the user's intended landing branch
Stay in the repository root checkout: No worktree is created during specify.
Read the files created by create:
<feature_dir>/spec.md (already created, may be empty/template-filled)
<feature_dir>/meta.json (already created with feature identity metadata)
Do NOT try to read a template file. The spec structure is defined in this prompt (see sections below). The create command scaffolds an initial spec.md — read it, then update it following the structure in this prompt.
Update <feature_dir>/meta.json only when needed:
- Never modify identity fields from
create (mission_id, slug, mission_slug, created_at, target_branch). mission_id is the canonical ULID and is immutable. mission_number is display-only and is null pre-merge — do not set it by hand.
- Keep
target_branch aligned to the value from create --json output. Never hardcode main.
- Ensure
friendly_name matches the confirmed title.
- Ensure
purpose_tldr matches the confirmed one-line stakeholder summary.
- Ensure
purpose_context matches the confirmed stakeholder context paragraph.
- Ensure
mission_type is correct.
- Optionally add/update
source_description.
- Ensure
vcs exists ("git" default).
Example meta.json schema (identity fields that must be present explicitly):
{
"mission_id": "01J6XW9KQT7M0YB3N4R5CQZ2EX",
"mission_number": null,
"slug": "my-feature",
"mission_slug": "my-feature",
"friendly_name": "My Mission",
"purpose_tldr": "Keep the mission understandable to product and executive stakeholders.",
"purpose_context": "This mission exists to make the purpose of the work immediately legible to stakeholders who should not need to parse technical specification text to understand the value or expected outcome.",
"mission_type": "software-dev",
"target_branch": "<target-branch>",
"vcs": "git",
"created_at": "2026-01-01T00:00:00+00:00"
}
mission_number becomes a concrete integer only at merge time, assigned as
max(existing_numbers)+1 inside the merge-state lock. Selectors disambiguate
by mission_id (or its 8-char prefix mid8), never by mission_number.
Do not regenerate timestamps or directory paths via shell commands.
Generate the specification content by following this flow:
- Use the discovery answers as your authoritative source of truth (do not rely on the raw invocation text)
- For empty invocations, treat the synthesized interview summary as the canonical feature description
- Identify: actors, actions, data, constraints, motivations, success metrics
- Prefer concrete scenario walkthrough facts (actor, trigger, success outcome, exception path) over abstract restatements
- For any remaining ambiguity:
- Ask the user a focused follow-up question immediately and halt work until they answer
- Only use
[NEEDS CLARIFICATION: …] when the user explicitly defers the decision
- Record any interim assumption in the Assumptions section
- Prioritize clarifications by impact: scope > outcomes > risks/security > user experience > technical details
- Fill User Scenarios & Testing section (ERROR if no clear user flow can be determined)
- If terminology precision matters, fill the optional Domain Language section with canonical terms and ambiguous synonyms to avoid
- Generate separated requirement tables: Functional (
FR-###), Non-Functional (NFR-###), and Constraints (C-###)
- Ensure each requirement entry has a status value and testable wording
- Capture rules or invariants that shape acceptance scenarios, edge cases, permissions, or lifecycle boundaries
- Define Success Criteria (measurable, technology-agnostic outcomes)
- Identify Key Entities (if data involved)
Update the existing <feature_dir>/spec.md using the template structure, replacing placeholders with concrete details derived from the feature description while preserving section order and headings.
Specification Quality Validation: After writing the initial spec, validate it against quality criteria:
a. Create Spec Quality Checklist: Generate a checklist file at feature_dir/checklists/requirements.md using the checklist template structure with these validation items:
# Specification Quality Checklist: [FEATURE NAME]
**Purpose**: Validate specification completeness and quality before proceeding to planning
**Created**: [DATE]
**Feature**: [Link to spec.md]
## Content Quality
- [ ] No implementation details (languages, frameworks, APIs)
- [ ] Focused on user value and business needs
- [ ] Written for non-technical stakeholders
- [ ] All mandatory sections completed
## Requirement Completeness
- [ ] No [NEEDS CLARIFICATION] markers remain
- [ ] Requirements are testable and unambiguous
- [ ] Requirement types are separated (Functional / Non-Functional / Constraints)
- [ ] IDs are unique across FR-###, NFR-###, and C-### entries
- [ ] All requirement rows include a non-empty Status value
- [ ] Non-functional requirements include measurable thresholds
- [ ] Success criteria are measurable
- [ ] Success criteria are technology-agnostic (no implementation details)
- [ ] All acceptance scenarios are defined
- [ ] Edge cases are identified
- [ ] Scope is clearly bounded
- [ ] Dependencies and assumptions identified
## Feature Readiness
- [ ] All functional requirements have clear acceptance criteria
- [ ] User scenarios cover primary flows
- [ ] Feature meets measurable outcomes defined in Success Criteria
- [ ] No implementation details leak into specification
## Notes
- Items marked incomplete require spec updates before `/spec-kitty.plan`
b. Run Validation Check: Review the spec against each checklist item:
- For each item, determine if it passes or fails
- Document specific issues found (quote relevant spec sections)
c. Handle Validation Results:
If all items pass: Mark checklist complete and proceed to step 6
If items fail (excluding [NEEDS CLARIFICATION]):
- List the failing items and specific issues
- Update the spec to address each issue
- Re-run validation until all items pass (max 3 iterations)
- If still failing after 3 iterations, document remaining issues in checklist notes and warn user
If [NEEDS CLARIFICATION] markers remain:
Extract all [NEEDS CLARIFICATION: ...] markers from the spec
Re-confirm with the user whether each outstanding decision truly needs to stay unresolved. Do not assume away critical gaps.
For each clarification the user has explicitly deferred, present options using plain text—no tables:
Question [N]: [Topic]
Context: [Quote relevant spec section]
Need: [Specific question from NEEDS CLARIFICATION marker]
Options: (A) [First answer — implications] · (B) [Second answer — implications] · (C) [Third answer — implications] · (D) Custom (describe your own answer)
Reply with a letter or a custom answer.
Number questions sequentially (Q1, Q2, Q3 - max 3 total)
Present all questions together before waiting for responses
Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
Re-run validation after all clarifications are resolved
d. Update Checklist: After each validation iteration, update the checklist file with current pass/fail status
Report completion with feature directory, spec file path, checklist results, and readiness for the next phase (/spec-kitty.plan).
NOTE: The script creates and checks out the new branch and initializes the spec file before writing.
General Guidelines
Quick Guidelines
- Focus on WHAT users need and WHY.
- Avoid HOW to implement (no tech stack, APIs, code structure).
- Written for business stakeholders, not developers.
- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
Section Requirements
- Mandatory sections: Must be completed for every feature
- Optional sections: Include only when relevant to the feature
- When a section doesn't apply, remove it entirely (don't leave as "N/A")
For AI Generation
When creating this spec from a user prompt:
- Make informed guesses: Use context, industry standards, and common patterns to fill gaps
- Document assumptions: Record reasonable defaults in the Assumptions section
- Limit clarifications: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
- Significantly impact feature scope or user experience
- Have multiple reasonable interpretations with different implications
- Lack any reasonable default
- Prioritize clarifications: scope > security/privacy > user experience > technical details
- Think like a tester: Every vague requirement should fail the "testable and unambiguous" checklist item
- Common areas needing clarification (only if no reasonable default exists):
- Feature scope and boundaries (include/exclude specific use cases)
- User types and permissions (if multiple conflicting interpretations possible)
- Security/compliance requirements (when legally/financially significant)
Examples of reasonable defaults (don't ask about these):
- Data retention: Industry-standard practices for the domain
- Performance targets: Standard web/mobile app expectations unless specified
- Error handling: User-friendly messages with appropriate fallbacks
- Authentication method: Standard session-based or OAuth2 for web apps
- Integration patterns: RESTful APIs unless specified otherwise
Success Criteria Guidelines
Success criteria must be:
- Measurable: Include specific metrics (time, percentage, count, rate)
- Technology-agnostic: No mention of frameworks, languages, databases, or tools
- User-focused: Describe outcomes from user/business perspective, not system internals
- Verifiable: Can be tested/validated without knowing implementation details
Good examples:
- "Users can complete checkout in under 3 minutes"
- "System supports 10,000 concurrent users"
- "95% of searches return results in under 1 second"
- "Task completion rate improves by 40%"
Bad examples (implementation-focused):
- "API response time is under 200ms" (too technical, use "Users see results instantly")
- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
- "React components render efficiently" (framework-specific)
- "Redis cache hit rate above 80%" (technology-specific)
1---2name: spec-kitty-specify-23description: Create a mission specification4---5# /spec-kitty.specify - Create Mission Specification67**Version**: 0.11.0+89## 📍 WORKING DIRECTORY: Stay in the repository root checkout1011**IMPORTANT**: Specify works in the repository root checkout. NO worktrees are created.1213```bash14# Run from the repository root checkout:15cd /path/to/project/root # Your repository root checkout1617# All planning artifacts are created in the project root and committed:18# - kitty-specs/<mission_slug>/spec.md → Created in project root19# (use the mission_slug returned by `mission create`; the numeric NNN- prefix20# is display-only and is assigned at merge time)21# - Committed to target branch (from create JSON: target_branch/base_branch)22# - NO worktrees created23```2425**Worktrees are created later** during `/spec-kitty.implement`, after task finalization computes execution lanes.2627## Mission Handle Rule2829Before `mission create`, there is no mission handle yet.3031- Do **not** pass `--mission` to `spec-kitty agent mission branch-context`.32- Do **not** pass `--mission` to `spec-kitty agent mission create`.33- After `create` succeeds, use `--mission <handle>` for commands that operate on34 the created mission.35- `<handle>` can be the mission's `mission_id` (ULID), `mid8` (first 8 chars of36 the ULID), or `mission_slug`.37- The resolver disambiguates by `mission_id` and returns a structured38 `MISSION_AMBIGUOUS_SELECTOR` error on ambiguity — there is no silent fallback.3940## User Input4142The content of the user's message that invoked this skill (everything after the skill invocation token, e.g. after `/spec-kitty.<command>` or `$spec-kitty.<command>`) is the User Input referenced elsewhere in these instructions.4344You **MUST** consider this user input before proceeding (if not empty).45## Primary Invariant: What Are We Building?4647This workflow answers "What are we building?" before it creates artifacts. The48raw invocation text is only a starting point for discovery, not the final truth.4950Before `mission create`, before writing `spec.md`, and before committing51anything, you **MUST** have one of these:5253- A completed discovery interview with an acknowledged Intent Summary.54- A brief-intake summary and extracted requirement set explicitly confirmed by55 the user.56- An explicit user instruction to minimize or skip discovery; even then, record57 the minimal confirmed scenario and assumptions in the Intent Summary.5859For non-trivial work, the confirmed Intent Summary must cover the primary actor,60trigger, desired outcome, one rule or invariant, and any canonical domain term61or boundary that materially affects the work.6263## Branch Strategy Confirmation (MANDATORY)6465Before discovery, resolve branch intent through the Python helper, not by probing git directly:6667```bash68spec-kitty agent mission branch-context --json69```7071If the user already told you the intended landing branch, pass it explicitly:7273```bash74spec-kitty agent mission branch-context --json --target-branch <intended-branch>75```7677Parse the JSON and, in your next reply, explicitly tell the user:7879- Current branch at workflow start: `current_branch`80- Default planning/base branch if you create the mission right now: `planning_base_branch`81- Final merge target for completed changes: `merge_target_branch`82- Whether `branch_matches_target` is true or false83- If that is not the intended landing branch, stop and ask which branch should receive this feature before you run `create`8485Never talk generically about `main` or "the default branch". Name the actual branch values from the helper JSON. Do not shell out to git for this prompt.8687## Commit Boundary (issue #846)8889`spec-kitty agent mission create` no longer auto-commits `spec.md`. The empty90template is written to disk untracked at create time; **you** are responsible91for committing it after writing substantive content.9293"Substantive content" for `spec.md` means **at least one Functional94Requirements row** (`FR-###`) whose description is real (not a template95placeholder like `[NEEDS CLARIFICATION …]`, `[e.g., …]`, or a bare user-story96scaffold). Section presence is the only signal — adding 300 bytes of arbitrary97prose without an FR row does **not** count as substantive.9899Workflow:1001011. Run `spec-kitty agent mission create …`. Note that `spec.md` is left102 untracked.1032. Populate `spec.md` with real Functional / Non-Functional / Constraint rows.1043. Commit `spec.md` yourself: `git add <feature_dir>/spec.md && git commit -m "Add spec for <slug>"`.1054. Only then will `spec-kitty agent mission setup-plan` accept the spec phase106 as complete; otherwise it returns `phase_complete=false` with a107 `blocked_reason` mentioning "committed AND substantive".108109Reference: `kitty-specs/charter-e2e-827-followups-01KQAJA0/contracts/specify-plan-commit-boundary.md`.110111## DO NOT112113- Do not mix functional, non-functional, and constraint requirements in one list.114- Do not emit requirements without stable IDs (`FR-###`, `NFR-###`, `C-###`).115- Do not leave requirement status fields empty.116- Do not write non-functional requirements without measurable thresholds.117- Do not proceed to planning with unresolved requirement quality checklist failures.118119## Charter Context Bootstrap (required)120121Before discovery questions, load charter context for this action:122123```bash124spec-kitty charter context --action specify --json125```126127- If JSON `mode` is `bootstrap`, treat JSON `text` as the initial governance context and consult referenced docs as needed.128- If JSON `mode` is `compact`, proceed with concise governance context.129- If no charter exists yet, note that and continue. Missing charter is not a130 blocker for `/spec-kitty.specify`.131132## Brief Context Detection (check before discovery)133134Before starting discovery, check for a pre-existing mission brief:135136```bash137ls .kittify/mission-brief.md 2>/dev/null && echo "MISSION_BRIEF_FOUND"138ls .kittify/ticket-context.md 2>/dev/null && echo "TICKET_CONTEXT_FOUND"139```140141Check in priority order:1421. `.kittify/mission-brief.md` — general plan intake (written by `spec-kitty intake`)1432. `.kittify/ticket-context.md` — tracker ticket (written by `mission create --from-ticket`)144145### If a brief file is found → Enter Brief-Intake Mode146147**BRIEF DETECTED: `.kittify/<filename>` (source: `<source_file>`)**1481491. **Read the full brief.** Do not skim.1501512. **Summarise for the user.** Present a single paragraph: what the brief says the goal is, who it is for, and what the key constraints are. Example: "I found a plan document from Claude Code plan mode. Here's what I understand the goal to be: [summary]. I'll extract the spec from this brief rather than running a full discovery interview."1521533. **Extract requirements directly.** Map the brief's content to `FR-###`, `NFR-###`, and `C-###` IDs. Do not ask questions the brief already answers. Specifically extract:154 - Objective → Functional Requirements155 - Constraints and non-goals → Non-Functional Requirements and Constraints156 - Acceptance criteria → FR status and Definition of Done markers157 - Risks and open questions → Assumptions or `[NEEDS CLARIFICATION: <text>] <!-- decision_id: <id> -->` markers (max 3; use `decision defer` before writing each marker)1581594. **Ask gap-filling questions only.** Scale to brief quality:160161 | Brief quality | Discovery questions |162 |---------------|---------------------|163 | Comprehensive (objective + constraints + approach + ACs) | 0–1 gap-filling questions |164 | Good (objective + constraints, no ACs) | 2–3 questions |165 | Partial (goal statement only) | 4–5 questions |166 | Empty / missing | Proceed to normal Discovery Gate below |1671685. **Show the extracted requirement set.** Present the full FR/NFR/C table to the user: "I extracted X functional requirements and Y non-functional requirements. Does this look right?" Wait for one round of confirmation. This confirmation is the discovery gate for brief-intake mode; do not write or commit `spec.md` before it happens unless the user explicitly asks to minimize or skip discovery. The user may correct or supplement before you write the spec.1691706. **Write spec.md normally.** Apply the same quality checklist and readiness gate as standard specify. Brief-intake mode does NOT lower the quality bar — spec.md must still pass all validation items.1711727. **After spec.md is committed, delete all brief files** (each only if present):173 ```bash174 rm -f .kittify/mission-brief.md175 rm -f .kittify/brief-source.yaml176 rm -f .kittify/ticket-context.md177 rm -f .kittify/pending-origin.yaml178 ```179180**What brief-intake mode does NOT do:**181- Does not copy brief prose verbatim into spec.md — it extracts and structures requirements182- Does not skip the quality checklist183- Does not skip the readiness gate184- Does not require the brief to be in any particular format — Markdown prose is fine185186### If no brief file is found → Proceed with normal Discovery Gate187188No change to current behaviour. Continue to the Discovery Gate section below.189190## Decision Moment Protocol191192Before asking **any** interview question during this command, you MUST:1931941. Run `spec-kitty agent decision open` to mint a decision_id:195 ```196 spec-kitty agent decision open \197 --mission <mission-slug> \198 --flow specify \199 --slot-key specify.<section>.<question-slug> \200 --input-key <snake_case_key> \201 --question "<question text>" \202 [--options '["option1","option2","Other"]']203 ```204 Capture the returned `decision_id` from the JSON output.2052062. Ask the question to the user in chat.2072083. After the user answers, run **exactly one** of:209 - Resolved answer:210 `spec-kitty agent decision resolve <decision_id> --mission <slug> --final-answer "<answer>" [--other-answer]`211 - Deferred / skip:212 `spec-kitty agent decision defer <decision_id> --mission <slug> --rationale "<reason>"`213 - Not applicable / cancel:214 `spec-kitty agent decision cancel <decision_id> --mission <slug> --rationale "<reason>"`2152164. When deferring, write the inline marker into `spec.md` immediately after the217 relevant section:218 ```219 [NEEDS CLARIFICATION: <brief description of what needs answering>] <!-- decision_id: <decision_id> -->220 ```2212225. Before declaring the interview phase complete, run:223 `spec-kitty agent decision verify --mission <slug>`224 Address any findings (`DEFERRED_WITHOUT_MARKER`, `MARKER_WITHOUT_DECISION`,225 `STALE_MARKER`) before proceeding.226227**Important constraints:**228- `--slot-key` format: `specify.<section>.<question-slug>` (e.g.,229 `specify.auth.strategy`).230- `--input-key` is the snake_case programmatic key (e.g., `auth_strategy`).231- The `decision_id` on the wire is a plain ULID (26 chars). The `DM-` prefix232 appears only in artifact filenames, not in CLI arguments.233- Widening is represented by the CLI/SaaS widen flow; if that flow returns234 canonical thread metadata, it must be recorded as `DecisionPointWidened`.235- SaaS sync is not required; all operations are local-only.236237## Discovery Gate (mandatory)238239Before running `mission create`, writing `spec.md`, committing, or otherwise creating planning artifacts, you **must** conduct or verify a structured discovery interview.240241- **Scope proportionality (CRITICAL)**: FIRST, gauge the inherent complexity of the request:242 - **Trivial/Test Features** (hello world, simple pages, proof-of-concept): Ask 1-2 questions maximum, then proceed. Examples: "a simple hello world page", "tic-tac-toe game", "basic contact form"243 - **Simple Features** (small UI additions, minor enhancements): Ask 2-3 questions covering purpose and basic constraints244 - **Complex Features** (new subsystems, integrations): Ask 3-5 questions covering goals, users, constraints, risks245 - **Platform/Critical Features** (authentication, payments, infrastructure): Full discovery with 5+ questions246247- **Scenario-first discovery**: For any non-trivial feature, prefer concrete248 workflow questions over abstract opinion prompts. Ask for the primary actor,249 trigger, happy-path outcome, and the most common exception or branch.250251- **Terminology discipline**: If the request introduces business or domain252 terms that may drift, ask which term is canonical and which synonyms should253 be avoided. When relevant, carry those choices into the optional Domain254 Language section of the spec instead of leaving them implicit.255256- **Rule probing**: For workflows with approvals, validations, state changes,257 or compliance implications, ask what must always be true and which258 transitions or checks cannot be skipped.259260- **User signals to reduce questioning**: If the user says "just testing", "quick prototype", "skip to next phase", "stop asking questions" - recognize this as a signal to minimize discovery and proceed with reasonable defaults.261262- **First response rule**:263 - For TRIVIAL features (hello world, simple test): Ask ONE clarifying question, then if the answer confirms it's simple, proceed directly to spec generation264 - For other features: Ask a single focused discovery question anchored in the primary user scenario and end with `WAITING_FOR_DISCOVERY_INPUT`265266- If the user provides no initial description (empty command), stay in **Interactive Interview Mode**: keep probing with one question at a time.267268- **Conversational cadence**: After each user reply, decide if you have ENOUGH context for this feature's complexity level. For trivial features, 1-2 questions is sufficient. Only continue asking if truly necessary for the scope.269270Discovery requirements (scale to feature complexity):2712721. Maintain a **Discovery Questions** table internally covering questions appropriate to the feature's complexity (1-2 for trivial, up to 5+ for complex). Track columns `#`, `Question`, `Why it matters`, and `Current insight`. Do **not** render this table to the user.2732. For trivial features, reasonable defaults are acceptable. Only probe if truly ambiguous.2743. When you have sufficient context for the feature's scope, paraphrase into an **Intent Summary** and confirm. For trivial features, this can be very brief. For non-trivial features, include the primary actor, trigger/success outcome, key constraint, and any explicit assumptions or deferred decisions.2754. Before leaving the interview loop, do a short playback of the primary scenario, the main exception or edge case, and any rule that must always hold.2765. If user explicitly asks to skip questions or says "just testing", acknowledge and proceed with minimal discovery.277278## Bulk-Edit Detection (mandatory check)279280Before finalizing the Intent Summary, ask yourself one question:281282> Does fulfilling this request require changing the **same existing string**283> (identifier, path, key, label, or term) in more than one file?284285Typical shapes: "rename X to Y", "the Blue feature is now the Red feature",286"change the terminology from X to Y", "move package A to package B", "replace287ACME with GlobalCorp everywhere in docs and UI".288289**If yes or uncertain**: load the `spec-kitty-bulk-edit-classification` skill290and follow it. You will set `change_mode: bulk_edit` in `meta.json` after291`mission create` and produce an `occurrence_map.yaml` during plan. The user292does not need to know these field names — the skill teaches you the workflow.293294**If clearly no** (a new feature with new identifiers, a bug fix that doesn't295rename anything, a refactor inside one file): proceed normally.296297When in doubt, treat as bulk edit. The false-positive cost is drafting one map298the user approves in a pass; the false-negative cost is the silent cross-file299breakage that DIRECTIVE_035 exists to prevent.300301## Mission Selection302303After completing discovery and confirming the Intent Summary, determine the appropriate mission type for this mission run.304305### Available Missions306307- **software-dev**: For building software features, APIs, CLI tools, applications308 - Phases: research → design → implement → test → review309 - Best for: code changes, new features, bug fixes, refactoring310311- **research**: For investigations, literature reviews, technical analysis312 - Phases: question → methodology → gather → analyze → synthesize → publish313 - Best for: feasibility studies, market research, technology evaluation314315### Mission Inference3163171. **Analyze the feature description** to identify the primary goal:318 - Building, coding, implementing, creating software → **software-dev**319 - Researching, investigating, analyzing, evaluating → **research**3203212. **Check for explicit mission requests** in the user's description:322 - If user mentions "research project", "investigation", "analysis" → use research323 - If user mentions "build", "implement", "create feature" → use software-dev3243253. **Confirm with user** (unless explicit):326 > "Based on your description, this sounds like a **[software-dev/research]** project.327 > I'll use the **[mission name]** mission. Does that work for you?"3283294. **Handle user response**:330 - If confirmed: proceed with selected mission331 - If user wants different mission: use their choice3323335. **Handle --mission flag**: If the user provides `--mission <key>` in their command, skip inference and use the specified mission directly.334335Store the final mission selection in your notes and include it in the spec output. Do not pass a `--mission-type` flag to mission creation unless the user explicitly overrides the default.336337## Workflow (0.11.0+)338339**Planning happens in the repository root checkout - NO worktree created!**3403411. Creates `kitty-specs/<mission_slug>/spec.md` directly in project root (the optional `NNN-` prefix is display-only metadata assigned at merge time)3422. Automatically commits to target branch3433. No worktree created during specify344345**Worktrees created later**: After `/spec-kitty.tasks` finishes, run: `spec-kitty next --agent <agent> --mission <handle>`. The `--mission` handle can be the mission's `mission_id` (ULID), `mid8` (first 8 chars), or `mission_slug`; the resolver disambiguates by `mission_id` and returns a structured error on ambiguity (no silent fallback). Your agent will call `spec-kitty agent action implement WP## --agent <name>` for each WP. Each lane gets exactly one worktree, for example `.worktrees/<human-slug>-<mid8>-lane-a/` (e.g. `.worktrees/my-feature-01J6XW9K-lane-a/`).346347## Location348349- Work in: **Repository root checkout** (not a worktree)350- Creates: `kitty-specs/<mission_slug>/spec.md` (the `NNN-` prefix is display-only and assigned at merge time)351- Commits to: target branch (from `create --json` → `target_branch`)352353## Outline354355### 0. Generate a Friendly Feature Title356357- Summarize the agreed intent into a short, descriptive title (aim for ≤7 words; avoid filler like "feature" or "thing").358- Read that title back during the Intent Summary and revise it if the user requests changes.359- Use the confirmed title to derive the kebab-case feature slug for the create command.360361The text the user typed after `/spec-kitty.specify` in the triggering message **is** the initial feature description. Capture it verbatim, but treat it only as a starting point for discovery—not the final truth. Your job is to interrogate the request, surface gaps, and co-create a complete specification with the user.362363Given that feature description, do this:364365- **Generation Mode (arguments provided)**: Use the provided text as a starting point, validate it through discovery, and fill gaps with explicit questions or clearly documented assumptions (limit `[NEEDS CLARIFICATION: …] <!-- decision_id: <id> -->` to at most three critical decisions the user has postponed; call `decision defer` before writing each such marker).366- **Interactive Interview Mode (no arguments)**: Use the discovery interview to elicit all necessary context, synthesize the working feature description, and confirm it with the user before you generate any specification artifacts.3673681. **Check discovery status**:369 - If this is your first message or discovery questions remain unanswered, stay in the one-question loop, capture the user's response, update your internal table, and end with `WAITING_FOR_DISCOVERY_INPUT`. Do **not** surface the table; keep it internal. Do **not** call the creation command yet.370 - Only proceed once every discovery question has an explicit answer and the user has acknowledged the Intent Summary.371 - Empty invocation rule: stay in interview mode until you can restate the agreed-upon feature description. Do **not** call the creation command while the description is missing or provisional.3723732. When discovery is complete and the intent summary, **title**, **purpose TLDR**, **purpose context paragraph**, and **mission type** are confirmed, run the mission creation command from repo root:374375 ```bash376 spec-kitty agent mission create "<slug>" \377 --friendly-name "<title>" \378 --purpose-tldr "<purpose_tldr>" \379 --purpose-context "<purpose_context>" \380 --json381 ```382383 Where `<slug>` is a kebab-case version of the friendly title (e.g., "Checkout Upsell Flow" → "checkout-upsell-flow").384385 The command returns JSON with:386 - `result`: "success" or error message387 - `mission_id`: Canonical ULID machine identity (e.g., `01J6XW9KQT7M0YB3N4R5CQZ2EX`). Immutable.388 - `mission_slug`: Human-readable mission slug (e.g., `checkout-upsell-flow`)389 - `mission_number`: **Display-only** numeric prefix, `null` pre-merge. Assigned at merge time. **Never** use this as a selector or identity.390 - `mission_type`: Mission type key (for example `software-dev`)391 - `slug`: Unnumbered mission slug (e.g., `checkout-upsell-flow`)392 - `friendly_name`: Confirmed mission title393 - `purpose_tldr`: One-line stakeholder-facing mission summary394 - `purpose_context`: Short stakeholder-facing context paragraph395 - `feature_dir`: Absolute path to the feature directory inside the repository root checkout396 - `current_branch`: the branch you started from397 - `target_branch` / `base_branch`: deterministic branch contract for downstream commands398 - `planning_base_branch` / `merge_target_branch`: explicit landing-branch aliases399 - `branch_strategy_summary`: human-readable summary of the branch contract400401 Parse these values for use in subsequent steps. All file paths are absolute.402403 **IMPORTANT**: You must only ever run this command once. The JSON is provided in the terminal output - always refer to it to get the actual paths you're looking for.404 Immediately restate the branch contract to the user after parsing the JSON:405 - Current branch at start406 - Intended planning/base branch407 - Final merge target for later changes408 - Whether that matches the user's intended landing branch4093. **Stay in the repository root checkout**: No worktree is created during specify.4104114. Read the files created by `create`:412 - `<feature_dir>/spec.md` (already created, may be empty/template-filled)413 - `<feature_dir>/meta.json` (already created with feature identity metadata)414415 **Do NOT try to read a template file.** The spec structure is defined in this prompt (see sections below). The `create` command scaffolds an initial `spec.md` — read it, then update it following the structure in this prompt.4164175. Update `<feature_dir>/meta.json` only when needed:418 - **Never** modify identity fields from `create` (`mission_id`, `slug`, `mission_slug`, `created_at`, `target_branch`). `mission_id` is the canonical ULID and is immutable. `mission_number` is display-only and is `null` pre-merge — do not set it by hand.419 - Keep `target_branch` aligned to the value from `create --json` output. Never hardcode `main`.420 - Ensure `friendly_name` matches the confirmed title.421 - Ensure `purpose_tldr` matches the confirmed one-line stakeholder summary.422 - Ensure `purpose_context` matches the confirmed stakeholder context paragraph.423 - Ensure `mission_type` is correct.424 - Optionally add/update `source_description`.425 - Ensure `vcs` exists (`"git"` default).426427 Example `meta.json` schema (identity fields that must be present explicitly):428 ```json429 {430 "mission_id": "01J6XW9KQT7M0YB3N4R5CQZ2EX",431 "mission_number": null,432 "slug": "my-feature",433 "mission_slug": "my-feature",434 "friendly_name": "My Mission",435 "purpose_tldr": "Keep the mission understandable to product and executive stakeholders.",436 "purpose_context": "This mission exists to make the purpose of the work immediately legible to stakeholders who should not need to parse technical specification text to understand the value or expected outcome.",437 "mission_type": "software-dev",438 "target_branch": "<target-branch>",439 "vcs": "git",440 "created_at": "2026-01-01T00:00:00+00:00"441 }442 ```443444 `mission_number` becomes a concrete integer only at merge time, assigned as445 `max(existing_numbers)+1` inside the merge-state lock. Selectors disambiguate446 by `mission_id` (or its 8-char prefix `mid8`), never by `mission_number`.447448 **Do not regenerate timestamps or directory paths via shell commands.**4494506. Generate the specification content by following this flow:451 - Use the discovery answers as your authoritative source of truth (do **not** rely on the raw invocation text)452 - For empty invocations, treat the synthesized interview summary as the canonical feature description453 - Identify: actors, actions, data, constraints, motivations, success metrics454 - Prefer concrete scenario walkthrough facts (actor, trigger, success outcome, exception path) over abstract restatements455 - For any remaining ambiguity:456 - Ask the user a focused follow-up question immediately and halt work until they answer457 - Only use `[NEEDS CLARIFICATION: …]` when the user explicitly defers the decision458 - Record any interim assumption in the Assumptions section459 - Prioritize clarifications by impact: scope > outcomes > risks/security > user experience > technical details460 - Fill User Scenarios & Testing section (ERROR if no clear user flow can be determined)461 - If terminology precision matters, fill the optional Domain Language section with canonical terms and ambiguous synonyms to avoid462 - Generate separated requirement tables: Functional (`FR-###`), Non-Functional (`NFR-###`), and Constraints (`C-###`)463 - Ensure each requirement entry has a status value and testable wording464 - Capture rules or invariants that shape acceptance scenarios, edge cases, permissions, or lifecycle boundaries465 - Define Success Criteria (measurable, technology-agnostic outcomes)466 - Identify Key Entities (if data involved)4674687. Update the existing `<feature_dir>/spec.md` using the template structure, replacing placeholders with concrete details derived from the feature description while preserving section order and headings.4694708. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:471472 a. **Create Spec Quality Checklist**: Generate a checklist file at `feature_dir/checklists/requirements.md` using the checklist template structure with these validation items:473474 ```markdown475 # Specification Quality Checklist: [FEATURE NAME]476477 **Purpose**: Validate specification completeness and quality before proceeding to planning478 **Created**: [DATE]479 **Feature**: [Link to spec.md]480481 ## Content Quality482483 - [ ] No implementation details (languages, frameworks, APIs)484 - [ ] Focused on user value and business needs485 - [ ] Written for non-technical stakeholders486 - [ ] All mandatory sections completed487488 ## Requirement Completeness489490 - [ ] No [NEEDS CLARIFICATION] markers remain491 - [ ] Requirements are testable and unambiguous492 - [ ] Requirement types are separated (Functional / Non-Functional / Constraints)493 - [ ] IDs are unique across FR-###, NFR-###, and C-### entries494 - [ ] All requirement rows include a non-empty Status value495 - [ ] Non-functional requirements include measurable thresholds496 - [ ] Success criteria are measurable497 - [ ] Success criteria are technology-agnostic (no implementation details)498 - [ ] All acceptance scenarios are defined499 - [ ] Edge cases are identified500 - [ ] Scope is clearly bounded501 - [ ] Dependencies and assumptions identified502503 ## Feature Readiness504505 - [ ] All functional requirements have clear acceptance criteria506 - [ ] User scenarios cover primary flows507 - [ ] Feature meets measurable outcomes defined in Success Criteria508 - [ ] No implementation details leak into specification509510 ## Notes511512 - Items marked incomplete require spec updates before `/spec-kitty.plan`513 ```514515 b. **Run Validation Check**: Review the spec against each checklist item:516 - For each item, determine if it passes or fails517 - Document specific issues found (quote relevant spec sections)518519 c. **Handle Validation Results**:520521 - **If all items pass**: Mark checklist complete and proceed to step 6522523 - **If items fail (excluding [NEEDS CLARIFICATION])**:524 1. List the failing items and specific issues525 2. Update the spec to address each issue526 3. Re-run validation until all items pass (max 3 iterations)527 4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user528529 - **If [NEEDS CLARIFICATION] markers remain**:530 1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec531 2. Re-confirm with the user whether each outstanding decision truly needs to stay unresolved. Do not assume away critical gaps.532 3. For each clarification the user has explicitly deferred, present options using plain text—no tables:533534 ```535 Question [N]: [Topic]536 Context: [Quote relevant spec section]537 Need: [Specific question from NEEDS CLARIFICATION marker]538 Options: (A) [First answer — implications] · (B) [Second answer — implications] · (C) [Third answer — implications] · (D) Custom (describe your own answer)539 Reply with a letter or a custom answer.540 ```541542 4. Number questions sequentially (Q1, Q2, Q3 - max 3 total)543 5. Present all questions together before waiting for responses544 6. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")545 7. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer546 9. Re-run validation after all clarifications are resolved547548 d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status5495509. Report completion with feature directory, spec file path, checklist results, and readiness for the next phase (`/spec-kitty.plan`).551552**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.553554## General Guidelines555556## Quick Guidelines557558- Focus on **WHAT** users need and **WHY**.559- Avoid HOW to implement (no tech stack, APIs, code structure).560- Written for business stakeholders, not developers.561- DO NOT create any checklists that are embedded in the spec. That will be a separate command.562563### Section Requirements564565- **Mandatory sections**: Must be completed for every feature566- **Optional sections**: Include only when relevant to the feature567- When a section doesn't apply, remove it entirely (don't leave as "N/A")568569### For AI Generation570571When creating this spec from a user prompt:5725731. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps5742. **Document assumptions**: Record reasonable defaults in the Assumptions section5753. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:576 - Significantly impact feature scope or user experience577 - Have multiple reasonable interpretations with different implications578 - Lack any reasonable default5794. **Prioritize clarifications**: scope > security/privacy > user experience > technical details5805. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item5816. **Common areas needing clarification** (only if no reasonable default exists):582 - Feature scope and boundaries (include/exclude specific use cases)583 - User types and permissions (if multiple conflicting interpretations possible)584 - Security/compliance requirements (when legally/financially significant)585586**Examples of reasonable defaults** (don't ask about these):587588- Data retention: Industry-standard practices for the domain589- Performance targets: Standard web/mobile app expectations unless specified590- Error handling: User-friendly messages with appropriate fallbacks591- Authentication method: Standard session-based or OAuth2 for web apps592- Integration patterns: RESTful APIs unless specified otherwise593594### Success Criteria Guidelines595596Success criteria must be:5975981. **Measurable**: Include specific metrics (time, percentage, count, rate)5992. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools6003. **User-focused**: Describe outcomes from user/business perspective, not system internals6014. **Verifiable**: Can be tested/validated without knowing implementation details602603**Good examples**:604605- "Users can complete checkout in under 3 minutes"606- "System supports 10,000 concurrent users"607- "95% of searches return results in under 1 second"608- "Task completion rate improves by 40%"609610**Bad examples** (implementation-focused):611612- "API response time is under 200ms" (too technical, use "Users see results instantly")613- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)614- "React components render efficiently" (framework-specific)615- "Redis cache hit rate above 80%" (technology-specific)