---
name: sdd-methodology
description: "Guides agents through the Spec-Driven Development (SDD) lifecycle: specification authoring, technical planning, task decomposition, and implementation execution. Use when working on features that follow a structured development process, when creating specs, plans, or tasks, when the user mentions SDD, spec-driven, specification workflow, or when gating rules between phases need enforcement."
---

# Spec-Driven Development Methodology

## Project Bootstrap

Before feature delivery begins, a project can establish shared product context, technical context, and governance:

1. **Product Strategist** *(optional)* — Create or refine `specs/prd.md` and register it as the canonical Product Document. Output: `specs/prd.md`, `.github/sddp-config.md` update
2. **Solution Architect** *(optional)* — Create or refine `specs/sad.md` and register it as the canonical Technical Context Document. Output: `specs/sad.md`, `.github/sddp-config.md` update
3. **Init** — Establish or amend `project-instructions.md` and preserve or adopt project-level context in `.github/sddp-config.md`. Output: `project-instructions.md`, `.github/sddp-config.md` updates

Project bootstrap does **not** change the strict feature delivery order below.

## Feature Delivery Lifecycle

SDD enforces a strict phase order. Each phase produces artifacts that gate the next:

1. **Specify** — Capture WHAT users, systems, or operators need and WHY. Output: `spec.md`
2. **Clarify** — Reduce ambiguity via targeted questions. Output: updated `spec.md`
3. **Plan** — Design HOW to build it. Output: `plan.md`, `research.md`, `data-model.md`, `contracts/`
4. **Tasks** — Decompose into actionable work items. Output: `tasks.md`
5. **Implement** — Execute tasks phase-by-phase. Output: source code + marked tasks + `.completed` marker
6. **Quality Control** — Verify implementation against spec, run tests, static analysis, and security audit. Output: `qc-report.md`, `.qc-passed` marker

### Phase Gating Rules

- **Specify → Clarify**: `spec.md` must exist
- **Clarify → Plan**: `spec.md` must exist (clarify is optional but recommended)
- **Plan → Tasks**: `spec.md` + `plan.md` must exist
- **Tasks → Implement**: `spec.md` + `plan.md` + `tasks.md` must exist
- **Implement**: All checklists in `checklists/` must pass (or user explicitly overrides)
- **Implement → QC**: `.completed` marker must exist in `FEATURE_DIR`
- **Checklist**: After generation, the `TestEvaluator` auto-evaluates items against artifacts, resolves gaps, and asks the user about ambiguous items

If a required artifact is missing, stop and direct the user to the correct prior phase.

### Gate Failure Error Template

When reporting a gate failure to the user, always include all three elements:
1. **What is missing and where**: Name the missing artifact and its expected full path — e.g., "Missing `spec.md` at `specs/00001-user-auth/spec.md`"
2. **Most likely cause**: Brief explanation — e.g., "This file is created by `/sddp-specify`. It does not exist yet in your feature directory."
3. **Copy-pasteable fix command**: Include context from the branch/feature name — e.g., "`/sddp-specify Users can register and log in with email and password`"

Never output a bare "Cannot proceed without [artifact]" without these three elements.

## Feature Directory Convention

Every feature's artifacts live at `specs/<feature-folder>/`.

- If the current branch matches `#####-feature-name`, agents use the branch name.
- If a git repo is active but the branch does not match, full-mode agents prompt for a folder name and validate new names in `00001-feature-name` format.
- If no git repo is active, full-mode agents derive a suggested folder name from the feature description and validate new names in `00001-feature-name` format.
- If git is in detached HEAD or branch resolution fails for another reason, full-mode agents halt and tell the user to fix the repository state and re-run the workflow.
- Existing non-prefixed feature folders are grandfathered and remain usable when already present.

Detect the branch via: `git rev-parse --abbrev-ref HEAD`

Standard layout:
```
specs/prd.md                   # Project-level Product Requirements Document (optional but preferred)
specs/sad.md                   # Project-level Software Architecture Document (optional but preferred)
project-instructions.md        # Project governance managed by /sddp-init
.github/sddp-config.md         # Shared project context and document registration

specs/<feature-folder>/
├── spec.md, plan.md, tasks.md
├── research.md, data-model.md
├── contracts/
├── checklists/
├── qc-report.md          # Generated by /sddp-qc
├── manual-test.md         # Generated by /sddp-qc when manual verification needed
├── .completed             # Set by /sddp-implement
└── .qc-passed             # Set by /sddp-qc on success
```

## Project Instructions

The file `project-instructions.md` contains non-negotiable project principles.

- **During Planning**: Run an Instructions Check — verify the plan aligns with every principle
- **During Analysis**: Project instructions violations are always CRITICAL severity
- **Project instructions changes**: Must go through `/sddp-init` with semantic versioning
- Project instructions supersede all other practices

## Quality Philosophy: "Unit Tests for English"

Checklists validate the QUALITY of requirements, not implementation behavior:
- ✅ "Are error handling requirements defined for all API failure modes?"
- ❌ "Verify the API returns proper error codes"

The full quality framework is in [references/quality-dimensions.md](references/quality-dimensions.md) — read it only when performing quality analysis, checklist generation, or evaluating requirements quality. Not needed for general phase gating or directory convention lookups.

## Priority System

Product specs use user stories; technical and operational specs use objectives. All use priorities P1 (most critical) through P3+:
- Each story or objective must be **independently testable/verifiable** — implementing just P1 yields a viable MVP
- Prioritize clarifications by impact: scope > security/privacy > UX or operator flow > technical details
- Maximum 3 `[NEEDS CLARIFICATION]` markers in any spec

## Task Format

```
- [ ] T### [P?] [US#|OBJ#?] {(FR|TR|OR|RR)-###?} Description with file path
```

- `[P]` = parallelizable (different files, no dependencies)
- `[US#]` = product user story reference
- `[OBJ#]` = technical or operational objective reference
- `{(FR|TR|OR|RR)-###}` = links task to requirement(s) from spec
- Phases: optional Setup → optional Foundational (cross-work-item blockers) → Delivery Work Items (by priority) → optional Polish
- Mark completed: `- [ ]` → `- [X]`