--- name: spec description: "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." argument-hint: "[description of feature, fix, or change]" effort: high --- # 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](references/spec-template.md) | Phase 2, when generating the spec | | [clarification-taxonomy.md](references/clarification-taxonomy.md) | Phase 2 (scanning) and Phase 3 (questions) | | [validation-checklist.md](references/validation-checklist.md) | Phase 4 (validation) | ## Process Overview ```text 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](references/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](references/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: ]` markers - **Maximum 5 markers** across the entire spec - Prioritize by impact, see [clarification-taxonomy.md §Prioritization](references/clarification-taxonomy.md) 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/.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: 1. **State context:** Quote the relevant spec section 2. **Recommend an answer:** Based on codebase patterns, project context, and best practices. Format: `**Recommended:** Option X -- ` 3. **Present options** as a markdown table: | Option | Description | Implications | |---|---|---| | A | ... | ... | | B | ... | ... | | C | ... | ... | 4. **Accept response:** User replies with: - Option letter (e.g., "A") - "yes" or "recommended" to accept the recommendation - A custom short answer 5. **Update the spec immediately** after each answer: - Replace the `[NEEDS CLARIFICATION]` marker with the answer - Add to Clarifications section: `- Q: -> A: ` - Save the file (atomic update) 6. **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 7. **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 -- ]` --- ## Phase 4: Validate ### 4.1 Load Validation Checklist Read [validation-checklist.md](references/validation-checklist.md) for the 8-point criteria. ### 4.2 Run 8-Point Check For each point, verify with specific evidence from the spec: 1. **Testability**, Every Given/When/Then maps to a test assertion 2. **Completeness**, Every story has criteria; every P1 has error paths 3. **Clarity**, No vague adjectives without measurable targets 4. **Scope**, Out of Scope section exists and is non-empty 5. **Independence**, P1 stories deliver standalone value 6. **Priority**, P1/P2/P3 assigned; P1 set forms coherent MVP 7. **Edge Cases**, Failure modes identified per P1 story 8. **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 (spec: docs/specs/.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: 1. **Acknowledge the pivot**, don't defend the existing spec 2. **Assess impact**, which stories survive the pivot vs need rewriting? 3. **Bump `spec-version`** and update the frontmatter 4. **Rewrite affected sections**, stories, criteria, affected components 5. **Re-run Phase 4 validation** on the updated spec 6. **Log the pivot** in Clarifications: `- Pivot: → ()` 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) 1. **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 2. **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 3. **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 4. **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 5. **"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 6. **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 7. **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 8. **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 9. **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 10. **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).