Feature Specification Process
Create a specification for the following: $ARGUMENTS
Specifications clarify WHAT to build before implementation begins.
Instead of discovering ambiguity mid-implementation (expensive),
surface it upfront through structured exploration and clarification,
where resolving it costs a question instead of a rewrite.
Mapping to the Explore -> Plan -> Code Loop
| Workflow Phase |
Spec Phase |
What Happens |
| Explore |
Phase 1: Explore |
Read files, understand context, check .devloop/domain.md |
| Plan |
Phase 2: Specify |
User stories, acceptance criteria, edge cases |
| Plan |
Phase 3: Clarify |
Interactive disambiguation (max 5 questions) |
| Plan |
Phase 4: Validate |
8-point spec quality checklist |
| Plan |
Phase 5: Handoff |
Summary report, suggest /plan |
When to Use This Process
| Scope |
Approach |
| Trivial (typo, config, rename) |
Don't use this skill -- just do it directly |
| Small (well-understood, single concern) |
Quick spec shortcut (skip clarification) |
| Medium (multi-concern, some ambiguity) |
Full process |
| Large (cross-cutting, unfamiliar domain) |
Full process, thorough clarification |
Quick spec shortcut: For small well-understood changes with
no domain ambiguity, collapse to: Explore -> Specify -> Validate
-> Handoff. Skip clarification entirely. Use when the feature can
be described in one sentence and has no competing interpretations.
Scope negotiation: If the request contains 3+ distinct features,
recommend splitting into separate specs before proceeding. Each spec
should cover one coherent feature with independent user value.
Product vs feature: If the request describes an entire product
or system (multiple independent capabilities, separate components,
its own installation story), treat it as a product-level spec:
- One user story per major capability (not per implementation task)
- Acceptance criteria verify capability, not component details
- Implementation chunking goes in Notes or during TDD, not as
separate specs
- Spec size will exceed the standard guideline, this is expected
If a product spec exceeds 12 stories, consider splitting into a
product spec (overview) + separate feature specs (details).
Product specs with interacting capabilities need explicit
interface contracts, file paths, data formats, handoff
expectations. Document these in Assumptions or a dedicated
section. Without them, components may diverge on implicit
conventions that break silently at integration time.
Supporting Files
Load these on demand, not all upfront:
| File |
When to Load |
| spec-template.md |
Phase 2, when generating the spec |
| clarification-taxonomy.md |
Phase 2 (scanning) and Phase 3 (questions) |
| validation-checklist.md |
Phase 4 (validation) |
Process Overview
Phase 1: Explore
Phase 2: Specify
Phase 3: Clarify (interactive, skippable)
Phase 4: Validate
Phase 5: Handoff
Each phase must complete before the next begins.
Phase 3 is skipped if no ambiguities are found.
Phase 1: Explore
1.1 Understand the Request
- Read the user's feature description carefully
- Identify: new feature, enhancement, bug fix, behavior change,
integration, or workflow change
- Extract key concepts: actors, actions, data, constraints, triggers
- Note initial assumptions about scope and intent
1.2 Explore Current Code
- Read files in the affected area (focus on files mentioned in the
request + 1 layer of direct dependencies)
- Trace the data flow through the application layers
- Identify existing patterns, utilities, and conventions to reference
- Note what already exists, don't spec what you can grep
Greenfield projects: If the codebase doesn't exist yet, explore
the inputs that define WHAT to build: analysis docs, design docs,
reference materials, domain knowledge files, and similar projects.
The goal is the same, understand context before specifying, but
the context lives in documents rather than code.
Context tip: Steps 1.2 and 1.3 are independent. If your harness
supports parallel tool calls or subagents, run them concurrently when
the codebase is large or unfamiliar; otherwise run them sequentially,
that is the default and is correct.
1.3 Read Project Context
- Load the domain config for domain context, architecture overview,
existing patterns, and domain-specific concerns. Resolve it in this
order:
.devloop/domain.md in the project root, else proceed
generically
- These inform edge case detection, affected component identification,
and project-specific validation in Phase 4
domain.md holds only domain knowledge. The one operational path /spec
needs, the spec directory, lives in .devloop/config.md and is read where
it's used (Phase 1.5 and 2.7)
- If neither file exists or the file contains only template
placeholders (
YOUR_*_HERE), proceed without it, the generic
taxonomy categories still apply
- If the project clearly needs a domain config (complex domain,
multiple conventions, domain-specific concerns), note this in
the spec's Notes section as a recommendation. Don't block the
spec process, create the spec first, suggest
.devloop/domain.md after
1.4 Identify Affected Components
- List files and modules that will likely change
- Note their role in the architecture (data layer, domain, UI, etc.)
- This becomes the spec's "Affected Components" section and later
feeds into TDD chunk decomposition
1.5 Check for Existing Spec
- Check the spec directory (the spec-directory setting in
.devloop/config.md, default docs/specs/) for an existing spec
file matching this feature
- If found, load it and show a summary to the user
- Ask: "A spec already exists for this feature. Update it, or
start fresh?"
- Update: Preserve Clarifications history, bump
spec-version,
revise stories and criteria based on new request
- Fresh: Archive old spec with
.bak suffix (overwrite any
existing .bak), generate new one
Phase 2: Specify
2.1 Load Spec Template
Read spec-template.md for the
output format. Use its section structure and frontmatter schema.
2.2 Generate User Stories
For each distinct user-facing behavior:
- Write a user story: As a , I want ,
so that
- Assign priority: P1 (must-have), P2 (should-have), P3 (nice-to-have)
- Include a "Why P_" line justifying the priority
- Ensure P1 stories form a coherent MVP that delivers value alone
- Each story should be independently implementable and testable
2.3 Write Acceptance Criteria
For each user story, write testable acceptance criteria:
- Use Given/When/Then format for every criterion
- P1 stories need both happy-path and error-path criteria
- P2/P3 stories need at least one criterion each
- Scan the domain config's Quality Standards while writing, criteria
categories like accessibility are cheaper to add now than to
discover in Phase 4 validation
- See spec-template.md §Acceptance Criteria for complexity hints
and specificity guidelines
- Depth target: Criteria should be specific enough to write a
test from, but not so specific that they dictate implementation.
"Then the output contains a section for each finding" is testable.
"Then the template uses a Handlebars {{#each}} loop" is
implementation. When in doubt, describe the observable outcome
2.4 Identify Edge Cases
Load clarification-taxonomy.md.
Scan all 9 categories against the feature:
- For each category, assess: Clear / Partial / Missing
- Document edge cases discovered in the spec's Edge Cases section
- Tag each edge case with its taxonomy category:
[Category N]
- At minimum for P1 features: empty state, error state, boundary values
- Check the domain config's domain-specific concerns (Category 9)
2.5 Document Assumptions
Record reasonable defaults for unspecified details. See
spec-template.md §Assumptions for guidelines. Use the taxonomy's
"Reasonable defaults" as a guide.
2.6 Mark Ambiguities
For categories marked Partial or Missing where the ambiguity
materially impacts the spec:
- Add
[NEEDS CLARIFICATION: <specific question>] markers
- Maximum 5 markers across the entire spec
- Prioritize by impact, see
clarification-taxonomy.md §Prioritization
for the full ranking
- Make informed guesses for everything else (document in Assumptions)
- Write the "Out of Scope" section, at least one item for medium+
features
2.7 Write Spec File
- Create the spec directory if it doesn't exist
- Write the spec to the configured location (the spec-directory
setting in
.devloop/config.md, default docs/specs/<feature-name>.md)
using kebab-case for the filename
- Include all sections from the template
- Set frontmatter status to
Draft
- Size check: Standard features should target ~80-150 lines
before Clarifications. If well over, reconsider scope,
it may be multiple features. Apply scope negotiation (see §When
to Use). Product-level specs (see §Product vs feature)
exceed this, up to ~300 lines is expected for products with
6-12 user stories
Phase 3: Clarify
Skip this phase if no [NEEDS CLARIFICATION] markers exist.
Report: "No critical ambiguities detected. Skipping clarification."
3.1 Prioritize Questions
From the [NEEDS CLARIFICATION] markers:
- Rank by (impact x uncertainty), highest first
- Select up to 5 for the question queue
- Each question must materially affect implementation or testing
- Never reveal upcoming questions, one at a time only
3.2 Interactive Questioning Loop
For each question in the queue:
State context: Quote the relevant spec section
Recommend an answer: Based on codebase patterns, project
context, and best practices. Format:
**Recommended:** Option X -- <one sentence reasoning>
Present options as a markdown table:
| Option |
Description |
Implications |
| A |
... |
... |
| B |
... |
... |
| C |
... |
... |
Accept response: User replies with:
- Option letter (e.g., "A")
- "yes" or "recommended" to accept the recommendation
- A custom short answer
Update the spec immediately after each answer:
- Replace the
[NEEDS CLARIFICATION] marker with the answer
- Add to Clarifications section:
- Q: <question> -> A: <answer>
- Save the file (atomic update)
Handle scope changes: If the user's answer introduces new
scope (new scenarios, new capabilities, new actors), update
affected stories and criteria before proceeding. Treat the
answer as a mini re-spec of the affected section, don't just
record it and move on
Proceed to next question or stop
3.3 Stop Conditions
Stop asking questions when:
- All markers are resolved
- User signals completion ("done", "skip", "proceed", "no more")
- 5 questions have been asked
- Remaining ambiguities are low-impact
3.4 Full Abort
If the user says "wrong approach", "start over", or similar:
- Delete the spec file
- Report: "Spec discarded. Re-run /spec with a revised description."
- Stop the process
3.5 Deferred Markers
If questions remain after early termination, replace unresolved
markers with: [DEFERRED: not clarified -- <brief reason>]
Phase 4: Validate
4.1 Load Validation Checklist
Read validation-checklist.md
for the 8-point criteria.
4.2 Run 8-Point Check
For each point, verify with specific evidence from the spec:
- Testability, Every Given/When/Then maps to a test assertion
- Completeness, Every story has criteria; every P1 has error paths
- Clarity, No vague adjectives without measurable targets
- Scope, Out of Scope section exists and is non-empty
- Independence, P1 stories deliver standalone value
- Priority, P1/P2/P3 assigned; P1 set forms coherent MVP
- Edge Cases, Failure modes identified per P1 story
- Resolution, No unresolved
[NEEDS CLARIFICATION] markers
4.3 Project-Specific Validation
Using the domain config (already loaded in Phase 1), run the
project-specific checks per validation-checklist.md
§Project-Specific Validation.
4.4 Fix Issues
If points fail, fix the spec directly and re-run the checklist.
See validation-checklist.md §Handling Failures for the iteration
limit and fallback behavior.
4.5 Mark Spec Ready
Update frontmatter status:
- All points pass:
status: Ready
- Some warnings remain:
status: Ready-with-warnings
Phase 5: Handoff
5.1 Summary Report
Output to the user:
- Spec file path
- Number of user stories by priority (P1/P2/P3)
- Number of acceptance criteria total
- Number of clarifications resolved (if Phase 3 ran)
- Validation result (Ready or Ready-with-warnings)
- Any deferred ambiguities or validation warnings
5.2 Downstream Integration
Explain how the spec feeds /plan (which decomposes it into chunks) and
then /implement (which builds them):
| Spec Section |
Consumed by |
How to Use |
| User Stories |
/plan Phase 1 (Analysis) |
Scope of what to explore |
| Affected Components |
/plan Phases 1-2 |
Starting point for chunk decomposition |
| Assumptions |
/plan Phase 1 (Analysis) |
Context for architecture decisions |
| Acceptance Criteria |
/plan (chunk criteria), /implement (tests) |
Become per-chunk criteria, then failing tests |
| Edge Cases |
/implement Phase 2 (TDD Cycle) |
Additional test cases |
5.3 Suggest Next Step
Next: /plan <feature> (spec: docs/specs/<feature>.md)
If the spec has warnings, note them:
"The spec has N unresolved warnings, review the Notes section
before planning."
Non-code projects: If the spec covers content, configuration,
or documentation (no executable code), adapt the mapping:
- "Write these as failing tests" → "Write these as validation
criteria or review checks"
- "Starting point for chunks" → "Starting point for content chunks"
- Suggest a structured build order rather than
/plan + /implement
Post-Validation Pivot
If the user challenges a fundamental assumption after the spec is
marked Ready (e.g., changing the architecture, switching platforms,
redefining scope), handle it as a controlled re-spec:
- Acknowledge the pivot, don't defend the existing spec
- Assess impact, which stories survive the pivot vs need rewriting?
- Bump
spec-version and update the frontmatter
- Rewrite affected sections, stories, criteria, affected components
- Re-run Phase 4 validation on the updated spec
- Log the pivot in Clarifications:
- Pivot: <old> → <new> (<reason>)
This is cheaper than starting fresh because unaffected stories,
edge cases, and clarifications are preserved.
This is also the landing point when /plan or /implement discovers
mid-build that an acceptance criterion itself was wrong: they route the
user back here to fix the criterion rather than inventing the fix
downstream, then re-run /plan so §3.1 merges the revised spec into the
existing tracker and review-plan re-gates.
Lessons Learned (Apply Every Time)
- Acceptance Criteria That Can't Fail Aren't Criteria -
If a Given/When/Then always passes regardless of implementation,
it tests nothing. "System handles errors" is not testable.
"When API returns 500, user sees error banner with retry button" is
- Edge Cases Come from the Domain, Not the Feature -
The most dangerous edge cases aren't in the feature itself, they're
in how the feature interacts with existing domain rules. A "delete"
feature seems simple until you consider: shared items, items in
progress, items with dependencies, undo expectations, sync conflicts
- The Spec Is Not the Plan -
Specs define WHAT and WHY. Plans define HOW. If you catch yourself
writing framework names, file paths, or algorithm choices, stop,
those belong in TDD, not here
- Three Clarifications Beat Ten Assumptions -
A single well-chosen clarification question that resolves a P1 scope
ambiguity saves more rework than ten documented assumptions. The
max-5 limit forces prioritization, use it on what matters most
- "Simple" Features Hide Domain Complexity -
"Add search" sounds simple until you consider: fuzzy matching,
pagination, permissions filtering, empty states, indexing strategy.
The taxonomy exists to surface this complexity before implementation
- User Stories Should Survive a Pivot -
If changing the tech stack invalidates your user stories, they
contain implementation details. "User finds events by keyword"
survives a rewrite. "User calls GET /api/search" doesn't
- Don't Spec What You Can Grep -
If the codebase already implements a pattern, reference it instead
of re-specifying it. "Follow the same pattern as OrderService"
is more accurate than re-describing what OrderService does
- Scope Creep Starts in the Spec -
Every "while we're at it" in a spec doubles implementation time.
Be aggressive about P2/P3 classification. Ship P1, then spec P2
separately. The Out of Scope section is your best defense
- The Best Specs Are Boring -
A good spec reads like a checklist, not a narrative. If it's
exciting to read, it probably contains opinions instead of criteria.
Save the creativity for the code
- Check Quality Standards During Specification, Not Just Validation -
Phase 4 catches missing criteria categories (accessibility, offline
behavior) but fixing them there costs a validation iteration. Scan
the domain config's Quality Standards during Phase 2.3 while writing
criteria, it's cheaper to include them upfront than to discover them late
Session Scope
Specs complete in one session. There is no tracker or session
resumption mechanism. To revisit a feature's spec later, re-run
/spec, Phase 1.5 detects the existing file and offers update
or fresh start.
Commit Guidance
Do not commit proactively. Wait for the user to request it.
Refer to .devloop/config.md for project-specific commit conventions
(author, message format, trailers).
1---2name: spec3description: "Structured specification process: explores code, generates user stories with testable acceptance criteria, resolves ambiguities through interactive clarification, validates completeness, and outputs a lightweight spec. Use before /plan to clarify WHAT to build."4argument-hint: "[description of feature, fix, or change]"5effort: high6metadata:7 source: https://skillmd.com/skills/kashzod/spec8---910# Feature Specification Process1112Create a specification for the following: $ARGUMENTS1314Specifications clarify WHAT to build before implementation begins.15Instead of discovering ambiguity mid-implementation (expensive),16surface it upfront through structured exploration and clarification,17where resolving it costs a question instead of a rewrite.1819## Mapping to the Explore -> Plan -> Code Loop2021| Workflow Phase | Spec Phase | What Happens |22|---|---|---|23| **Explore** | Phase 1: Explore | Read files, understand context, check `.devloop/domain.md` |24| **Plan** | Phase 2: Specify | User stories, acceptance criteria, edge cases |25| **Plan** | Phase 3: Clarify | Interactive disambiguation (max 5 questions) |26| **Plan** | Phase 4: Validate | 8-point spec quality checklist |27| **Plan** | Phase 5: Handoff | Summary report, suggest /plan |2829## When to Use This Process3031| Scope | Approach |32|---|---|33| Trivial (typo, config, rename) | Don't use this skill -- just do it directly |34| Small (well-understood, single concern) | Quick spec shortcut (skip clarification) |35| Medium (multi-concern, some ambiguity) | Full process |36| Large (cross-cutting, unfamiliar domain) | Full process, thorough clarification |3738**Quick spec shortcut:** For small well-understood changes with39no domain ambiguity, collapse to: Explore -> Specify -> Validate40-> Handoff. Skip clarification entirely. Use when the feature can41be described in one sentence and has no competing interpretations.4243**Scope negotiation:** If the request contains 3+ distinct features,44recommend splitting into separate specs before proceeding. Each spec45should cover one coherent feature with independent user value.4647**Product vs feature:** If the request describes an entire product48or system (multiple independent capabilities, separate components,49its own installation story), treat it as a product-level spec:5051- One user story per major capability (not per implementation task)52- Acceptance criteria verify capability, not component details53- Implementation chunking goes in Notes or during TDD, not as54 separate specs55- Spec size will exceed the standard guideline, this is expected5657If a product spec exceeds 12 stories, consider splitting into a58product spec (overview) + separate feature specs (details).5960Product specs with interacting capabilities need explicit61interface contracts, file paths, data formats, handoff62expectations. Document these in Assumptions or a dedicated63section. Without them, components may diverge on implicit64conventions that break silently at integration time.6566## Supporting Files6768Load these on demand, not all upfront:6970| File | When to Load |71|---|---|72| [spec-template.md](references/spec-template.md) | Phase 2, when generating the spec |73| [clarification-taxonomy.md](references/clarification-taxonomy.md) | Phase 2 (scanning) and Phase 3 (questions) |74| [validation-checklist.md](references/validation-checklist.md) | Phase 4 (validation) |7576## Process Overview7778```text79Phase 1: Explore80Phase 2: Specify81Phase 3: Clarify (interactive, skippable)82Phase 4: Validate83Phase 5: Handoff84```8586Each phase must complete before the next begins.87Phase 3 is skipped if no ambiguities are found.8889---9091## Phase 1: Explore9293### 1.1 Understand the Request9495- Read the user's feature description carefully96- Identify: new feature, enhancement, bug fix, behavior change,97 integration, or workflow change98- Extract key concepts: actors, actions, data, constraints, triggers99- Note initial assumptions about scope and intent100101### 1.2 Explore Current Code102103- Read files in the affected area (focus on files mentioned in the104 request + 1 layer of direct dependencies)105- Trace the data flow through the application layers106- Identify existing patterns, utilities, and conventions to reference107- Note what already exists, don't spec what you can grep108109**Greenfield projects:** If the codebase doesn't exist yet, explore110the inputs that define WHAT to build: analysis docs, design docs,111reference materials, domain knowledge files, and similar projects.112The goal is the same, understand context before specifying, but113the context lives in documents rather than code.114115**Context tip:** Steps 1.2 and 1.3 are independent. If your harness116supports parallel tool calls or subagents, run them concurrently when117the codebase is large or unfamiliar; otherwise run them sequentially,118that is the default and is correct.119120### 1.3 Read Project Context121122- Load the domain config for domain context, architecture overview,123 existing patterns, and domain-specific concerns. Resolve it in this124 order: `.devloop/domain.md` in the project root, else proceed125 generically126- These inform edge case detection, affected component identification,127 and project-specific validation in Phase 4128- `domain.md` holds only domain knowledge. The one operational path `/spec`129 needs, the spec directory, lives in `.devloop/config.md` and is read where130 it's used (Phase 1.5 and 2.7)131- If neither file exists or the file contains only template132 placeholders (`YOUR_*_HERE`), proceed without it, the generic133 taxonomy categories still apply134- If the project clearly needs a domain config (complex domain,135 multiple conventions, domain-specific concerns), note this in136 the spec's Notes section as a recommendation. Don't block the137 spec process, create the spec first, suggest `.devloop/domain.md` after138139### 1.4 Identify Affected Components140141- List files and modules that will likely change142- Note their role in the architecture (data layer, domain, UI, etc.)143- This becomes the spec's "Affected Components" section and later144 feeds into TDD chunk decomposition145146### 1.5 Check for Existing Spec147148- Check the spec directory (the spec-directory setting in149 `.devloop/config.md`, default `docs/specs/`) for an existing spec150 file matching this feature151- If found, load it and show a summary to the user152- Ask: "A spec already exists for this feature. Update it, or153 start fresh?"154 - **Update:** Preserve Clarifications history, bump `spec-version`,155 revise stories and criteria based on new request156 - **Fresh:** Archive old spec with `.bak` suffix (overwrite any157 existing `.bak`), generate new one158159---160161## Phase 2: Specify162163### 2.1 Load Spec Template164165Read [spec-template.md](references/spec-template.md) for the166output format. Use its section structure and frontmatter schema.167168### 2.2 Generate User Stories169170For each distinct user-facing behavior:171172- Write a user story: **As a** <role>, **I want** <goal>,173 **so that** <benefit>174- Assign priority: P1 (must-have), P2 (should-have), P3 (nice-to-have)175- Include a "Why P_" line justifying the priority176- Ensure P1 stories form a coherent MVP that delivers value alone177- Each story should be independently implementable and testable178179### 2.3 Write Acceptance Criteria180181For each user story, write testable acceptance criteria:182183- Use Given/When/Then format for every criterion184- P1 stories need both happy-path and error-path criteria185- P2/P3 stories need at least one criterion each186- Scan the domain config's Quality Standards while writing, criteria187 categories like accessibility are cheaper to add now than to188 discover in Phase 4 validation189- See spec-template.md §Acceptance Criteria for complexity hints190 and specificity guidelines191- **Depth target:** Criteria should be specific enough to write a192 test from, but not so specific that they dictate implementation.193 "Then the output contains a section for each finding" is testable.194 "Then the template uses a Handlebars {{#each}} loop" is195 implementation. When in doubt, describe the observable outcome196197### 2.4 Identify Edge Cases198199Load [clarification-taxonomy.md](references/clarification-taxonomy.md).200Scan all 9 categories against the feature:201202- For each category, assess: Clear / Partial / Missing203- Document edge cases discovered in the spec's Edge Cases section204- Tag each edge case with its taxonomy category: `[Category N]`205- At minimum for P1 features: empty state, error state, boundary values206- Check the domain config's domain-specific concerns (Category 9)207208### 2.5 Document Assumptions209210Record reasonable defaults for unspecified details. See211spec-template.md §Assumptions for guidelines. Use the taxonomy's212"Reasonable defaults" as a guide.213214### 2.6 Mark Ambiguities215216For categories marked Partial or Missing where the ambiguity217materially impacts the spec:218219- Add `[NEEDS CLARIFICATION: <specific question>]` markers220- **Maximum 5 markers** across the entire spec221- Prioritize by impact, see222 [clarification-taxonomy.md §Prioritization](references/clarification-taxonomy.md)223 for the full ranking224- Make informed guesses for everything else (document in Assumptions)225- Write the "Out of Scope" section, at least one item for medium+226 features227228### 2.7 Write Spec File229230- Create the spec directory if it doesn't exist231- Write the spec to the configured location (the spec-directory232 setting in `.devloop/config.md`, default `docs/specs/<feature-name>.md`)233 using kebab-case for the filename234- Include all sections from the template235- Set frontmatter status to `Draft`236- **Size check:** Standard features should target ~80-150 lines237 before Clarifications. If well over, reconsider scope,238 it may be multiple features. Apply scope negotiation (see §When239 to Use). Product-level specs (see §Product vs feature)240 exceed this, up to ~300 lines is expected for products with241 6-12 user stories242243---244245## Phase 3: Clarify246247Skip this phase if no `[NEEDS CLARIFICATION]` markers exist.248Report: "No critical ambiguities detected. Skipping clarification."249250### 3.1 Prioritize Questions251252From the `[NEEDS CLARIFICATION]` markers:253254- Rank by (impact x uncertainty), highest first255- Select up to 5 for the question queue256- Each question must materially affect implementation or testing257- Never reveal upcoming questions, one at a time only258259### 3.2 Interactive Questioning Loop260261For each question in the queue:2622631. **State context:** Quote the relevant spec section2642. **Recommend an answer:** Based on codebase patterns, project265 context, and best practices. Format:266 `**Recommended:** Option X -- <one sentence reasoning>`2673. **Present options** as a markdown table:268269 | Option | Description | Implications |270 |---|---|---|271 | A | ... | ... |272 | B | ... | ... |273 | C | ... | ... |2742754. **Accept response:** User replies with:276 - Option letter (e.g., "A")277 - "yes" or "recommended" to accept the recommendation278 - A custom short answer2795. **Update the spec immediately** after each answer:280 - Replace the `[NEEDS CLARIFICATION]` marker with the answer281 - Add to Clarifications section: `- Q: <question> -> A: <answer>`282 - Save the file (atomic update)2836. **Handle scope changes:** If the user's answer introduces new284 scope (new scenarios, new capabilities, new actors), update285 affected stories and criteria before proceeding. Treat the286 answer as a mini re-spec of the affected section, don't just287 record it and move on2887. **Proceed to next question** or stop289290### 3.3 Stop Conditions291292Stop asking questions when:293294- All markers are resolved295- User signals completion ("done", "skip", "proceed", "no more")296- 5 questions have been asked297- Remaining ambiguities are low-impact298299### 3.4 Full Abort300301If the user says "wrong approach", "start over", or similar:302303- Delete the spec file304- Report: "Spec discarded. Re-run /spec with a revised description."305- Stop the process306307### 3.5 Deferred Markers308309If questions remain after early termination, replace unresolved310markers with: `[DEFERRED: not clarified -- <brief reason>]`311312---313314## Phase 4: Validate315316### 4.1 Load Validation Checklist317318Read [validation-checklist.md](references/validation-checklist.md)319for the 8-point criteria.320321### 4.2 Run 8-Point Check322323For each point, verify with specific evidence from the spec:3243251. **Testability**, Every Given/When/Then maps to a test assertion3262. **Completeness**, Every story has criteria; every P1 has error paths3273. **Clarity**, No vague adjectives without measurable targets3284. **Scope**, Out of Scope section exists and is non-empty3295. **Independence**, P1 stories deliver standalone value3306. **Priority**, P1/P2/P3 assigned; P1 set forms coherent MVP3317. **Edge Cases**, Failure modes identified per P1 story3328. **Resolution**, No unresolved `[NEEDS CLARIFICATION]` markers333334### 4.3 Project-Specific Validation335336Using the domain config (already loaded in Phase 1), run the337project-specific checks per validation-checklist.md338§Project-Specific Validation.339340### 4.4 Fix Issues341342If points fail, fix the spec directly and re-run the checklist.343See validation-checklist.md §Handling Failures for the iteration344limit and fallback behavior.345346### 4.5 Mark Spec Ready347348Update frontmatter status:349- All points pass: `status: Ready`350- Some warnings remain: `status: Ready-with-warnings`351352---353354## Phase 5: Handoff355356### 5.1 Summary Report357358Output to the user:359360- Spec file path361- Number of user stories by priority (P1/P2/P3)362- Number of acceptance criteria total363- Number of clarifications resolved (if Phase 3 ran)364- Validation result (Ready or Ready-with-warnings)365- Any deferred ambiguities or validation warnings366367### 5.2 Downstream Integration368369Explain how the spec feeds `/plan` (which decomposes it into chunks) and370then `/implement` (which builds them):371372| Spec Section | Consumed by | How to Use |373|---|---|---|374| User Stories | /plan Phase 1 (Analysis) | Scope of what to explore |375| Affected Components | /plan Phases 1-2 | Starting point for chunk decomposition |376| Assumptions | /plan Phase 1 (Analysis) | Context for architecture decisions |377| Acceptance Criteria | /plan (chunk criteria), /implement (tests) | Become per-chunk criteria, then failing tests |378| Edge Cases | /implement Phase 2 (TDD Cycle) | Additional test cases |379380### 5.3 Suggest Next Step381382```383Next: /plan <feature> (spec: docs/specs/<feature>.md)384```385386If the spec has warnings, note them:387"The spec has N unresolved warnings, review the Notes section388before planning."389390**Non-code projects:** If the spec covers content, configuration,391or documentation (no executable code), adapt the mapping:392- "Write these as failing tests" → "Write these as validation393 criteria or review checks"394- "Starting point for chunks" → "Starting point for content chunks"395- Suggest a structured build order rather than `/plan` + `/implement`396397---398399## Post-Validation Pivot400401If the user challenges a fundamental assumption after the spec is402marked Ready (e.g., changing the architecture, switching platforms,403redefining scope), handle it as a controlled re-spec:4044051. **Acknowledge the pivot**, don't defend the existing spec4062. **Assess impact**, which stories survive the pivot vs need rewriting?4073. **Bump `spec-version`** and update the frontmatter4084. **Rewrite affected sections**, stories, criteria, affected components4095. **Re-run Phase 4 validation** on the updated spec4106. **Log the pivot** in Clarifications: `- Pivot: <old> → <new> (<reason>)`411412This is cheaper than starting fresh because unaffected stories,413edge cases, and clarifications are preserved.414415This is also the landing point when `/plan` or `/implement` discovers416mid-build that an acceptance *criterion itself* was wrong: they route the417user back here to fix the criterion rather than inventing the fix418downstream, then re-run `/plan` so §3.1 merges the revised spec into the419existing tracker and `review-plan` re-gates.420421---422423## Lessons Learned (Apply Every Time)4244251. **Acceptance Criteria That Can't Fail Aren't Criteria** -426 If a Given/When/Then always passes regardless of implementation,427 it tests nothing. "System handles errors" is not testable.428 "When API returns 500, user sees error banner with retry button" is4292. **Edge Cases Come from the Domain, Not the Feature** -430 The most dangerous edge cases aren't in the feature itself, they're431 in how the feature interacts with existing domain rules. A "delete"432 feature seems simple until you consider: shared items, items in433 progress, items with dependencies, undo expectations, sync conflicts4343. **The Spec Is Not the Plan** -435 Specs define WHAT and WHY. Plans define HOW. If you catch yourself436 writing framework names, file paths, or algorithm choices, stop,437 those belong in TDD, not here4384. **Three Clarifications Beat Ten Assumptions** -439 A single well-chosen clarification question that resolves a P1 scope440 ambiguity saves more rework than ten documented assumptions. The441 max-5 limit forces prioritization, use it on what matters most4425. **"Simple" Features Hide Domain Complexity** -443 "Add search" sounds simple until you consider: fuzzy matching,444 pagination, permissions filtering, empty states, indexing strategy.445 The taxonomy exists to surface this complexity before implementation4466. **User Stories Should Survive a Pivot** -447 If changing the tech stack invalidates your user stories, they448 contain implementation details. "User finds events by keyword"449 survives a rewrite. "User calls GET /api/search" doesn't4507. **Don't Spec What You Can Grep** -451 If the codebase already implements a pattern, reference it instead452 of re-specifying it. "Follow the same pattern as OrderService"453 is more accurate than re-describing what OrderService does4548. **Scope Creep Starts in the Spec** -455 Every "while we're at it" in a spec doubles implementation time.456 Be aggressive about P2/P3 classification. Ship P1, then spec P2457 separately. The Out of Scope section is your best defense4589. **The Best Specs Are Boring** -459 A good spec reads like a checklist, not a narrative. If it's460 exciting to read, it probably contains opinions instead of criteria.461 Save the creativity for the code46210. **Check Quality Standards During Specification, Not Just Validation** -463 Phase 4 catches missing criteria categories (accessibility, offline464 behavior) but fixing them there costs a validation iteration. Scan465 the domain config's Quality Standards during Phase 2.3 while writing466 criteria, it's cheaper to include them upfront than to discover them late467468---469470## Session Scope471472Specs complete in one session. There is no tracker or session473resumption mechanism. To revisit a feature's spec later, re-run474`/spec`, Phase 1.5 detects the existing file and offers update475or fresh start.476477---478479## Commit Guidance480481Do not commit proactively. Wait for the user to request it.482Refer to `.devloop/config.md` for project-specific commit conventions483(author, message format, trailers).