spec-dd

What this skill does

# Specification-Driven Development

Orchestrate a spec-first development workflow: behavioral specification, test
scenario derivation, test implementation planning, test implementation, feature
implementation, and cross-artifact alignment review. The skill guides writing
behavioral specifications, derives test scenarios, plans test implementation
approaches, and verifies alignment across all artifacts and code. Quality gates
between phases are advisory — the skill flags issues and recommends addressing
them, but the user can override and proceed.

## Commands

| Command | Phase | Reference |
|---------|-------|-----------|
| `/spec-dd` | Auto-detect phase, assess state, recommend next step | All references |
| `/spec-dd:spec` | Behavioral Specification | `references/specification.md` |
| `/spec-dd:test` | Test Specification | `references/test-specification.md` |
| `/spec-dd:test-impl` | Test Implementation Specification | `references/test-implementation-specification.md` |
| `/spec-dd:verify` | Implementation Verification | `references/verify.md` |
| `/spec-dd:review` | Alignment Review | `references/review.md` |

All commands accept an optional feature name argument (e.g., `/spec-dd:spec user-auth`).
`/spec-dd:verify` also accepts a spec file path as its first argument
(e.g., `/spec-dd:verify specifications.md chat-ui`). This allows verification against
any spec file, including informal ones not created through the spec-dd workflow.
If no feature name is provided and multiple features exist, list available features and
ask the user to choose.

## Artifacts

All artifacts live in `docs/specs/` with one set of files per feature:

| Artifact | Filename |
|----------|----------|
| Behavioral Specification | `docs/specs/<feature>-specification.md` |
| Test Specification | `docs/specs/<feature>-test-specification.md` |
| Test Implementation Specification | `docs/specs/<feature>-test-implementation-specification.md` |
| Implementation Verification | `docs/specs/<feature>-verification.md` |
| Implementation Review | `docs/specs/<feature>-implementation-review.md` |

## First Steps

When any command is invoked:

1. **Read the relevant reference file** from `references/` BEFORE doing anything else.
   - `/spec-dd:spec` -> read `references/specification.md`
   - `/spec-dd:test` -> read `references/test-specification.md`
   - `/spec-dd:test-impl` -> read `references/test-implementation-specification.md`
   - `/spec-dd:verify` -> read `references/verify.md`
   - `/spec-dd:review` -> read `references/review.md`
   - `/spec-dd` -> read whichever reference applies to the recommended phase

2. **Auto-detect project language** by scanning for manifest files:
   - `package.json` (JavaScript/TypeScript)
   - `requirements.txt`, `pyproject.toml` (Python)
   - `go.mod` (Go)
   - `Cargo.toml` (Rust)
   - `pom.xml`, `build.gradle` (Java/Kotlin)
   - Use the detected language/ecosystem to inform testing frameworks, patterns,
     idioms, and handoff prompts throughout the workflow.

3. **For `/spec-dd` (router):** Follow the auto-detect router logic below.

4. **For `/spec-dd:<phase>`:** Check whether prior-phase artifacts exist. If gaps
   are found, advise the user which earlier phase to complete first, but do not
   block — proceed if the user chooses to continue.

## Phase 1: Behavioral Specification (`/spec-dd:spec`)

**Reference:** Read `references/specification.md` before starting.

**Purpose:** Define what the system does — behavioral contracts, not implementation
details.

**Workflow:**

1. Guide the user through creating or reviewing the behavioral specification for
   the selected feature.
2. Use selectable options plus a free-text escape for every question. Ask 1-3
   questions per turn, grouped thematically. Summarize captured answers before
   moving on.
3. Review for ambiguity:
   - Vague language ("fast", "secure", "easy", "simple", "efficient")
   - Missing edge cases and boundary conditions
   - Undefined terms and implicit assumptions
   - Unmeasurable acceptance criteria
4. Mark any unresolved items with `[NEEDS CLARIFICATION]`.
5. Produce or update `docs/specs/<feature>-specification.md`.

**Advisory gate:** No unresolved `[NEEDS CLARIFICATION]` markers before proceeding
to Phase 2.

**Artifact template:**

```markdown
# <Feature> - Behavioral Specification

## Objective
What this feature does and why it exists.

## User Stories & Acceptance Criteria
Numbered user stories, each with measurable acceptance criteria.

## Constraints
Technical, business, or regulatory constraints.

## Edge Cases
Boundary conditions, error states, unusual inputs.

## Non-Goals
What this feature explicitly does NOT do.

## Open Questions
Items marked [NEEDS CLARIFICATION] that must be resolved.
```

## Phase 2: Test Specification (`/spec-dd:test`)

**Reference:** Read `references/test-specification.md` before starting.

**Purpose:** Derive test scenarios from the behavioral spec only — no implementation
knowledge.

**Pre-check:** Verify that `<feature>-specification.md` exists. If it does not,
advise the user to complete Phase 1 first. If the user chooses to proceed anyway,
note the risk and continue.

**Workflow:**

1. Derive Given/When/Then scenarios from each acceptance criterion in the
   behavioral specification.
2. Enforce one behavior per scenario, one action per step.
3. Build a coverage matrix mapping every spec requirement to test scenarios.
4. Language-aware review: ensure scenarios are realistic and testable for the
   project's detected testing ecosystem.
5. Check traceability: every acceptance criterion must have at least one test
   scenario.
6. Produce or update `docs/specs/<feature>-test-specification.md`.

**Advisory gate:** Full traceability between spec requirements and test scenarios
before proceeding to Phase 3.

**Artifact template:**

```markdown
# <Feature> - Test Specification

## Coverage Matrix
Table mapping each acceptance criterion to its test scenarios.

## Test Scenarios
Given/When/Then format. Grouped by user story or functional area.

## Edge Case Scenarios
Boundary conditions derived from the specification's edge cases section.

## Traceability
Summary confirming every acceptance criterion is covered.
```

## Phase 3: Test Implementation Specification (`/spec-dd:test-impl`)

**Reference:** Read `references/test-implementation-specification.md` before starting.

**Purpose:** Map every test scenario to a technical approach for implementing it
as actual test code.

**Pre-check:** Verify that `<feature>-test-specification.md` exists. If it does
not, advise the user to complete Phase 2 first. Proceed if the user overrides.

**Workflow:**

1. Guide the user through describing the technical approach for implementing
   each test scenario as actual test code.
2. Use language-aware patterns: test framework selection, fixture strategies,
   mock/stub approaches, test file organization.
3. Map every test scenario from the test specification to specific test
   functions, test classes, or test modules.
4. Describe shared fixtures, test data factories, and setup/teardown strategies.
5. Verify completeness: every Given/When/Then scenario has a corresponding
   test implementation approach.
6. Produce or update `docs/specs/<feature>-test-implementation-specification.md`.

**Advisory gate:** Every test scenario mapped to a test implementation approach
before proceeding to Phase 4.

**Artifact template:**

```markdown
# <Feature> - Test Implementation Specification

## Test Framework & Conventions
Detected stack, test framework, test runner, conventions.

## Test Structure
How tests are organized: files, classes/modules, naming conventions.

## Test Scenario Mapping
Map each test scenario to a test function/method with setup and assertion strategy.

## Fixtures & Test Data
Shared fixtures, factories, test data approach, setup/teardown.

## Alignment Check
Confirmation that every test scenario has a test implementation approach.
```

## Phase 4: Test Imple