git:20260310.4ae0218 to git:20260310.7925aae

---

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:

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

- Maximum 3 `[NEEDS CLARIFICATION]` markers in any spec

## Task Format

```

```

- `[P]` = parallelizable (different files, no dependencies)

- Mark completed: `- [ ]` → `- [X]`