# Sdd Conventions

> This skill should be used when working on specification documents, when creating feature specs, when writing acceptance criteria, when following SDD methodology, or when asked about the project's specification process. Provides conventions and standards for specification-driven development.

- Skill: `haruhikomotokawa/sdd-conventions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add haruhikomotokawa/sdd-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/haruhikomotokawa/sdd-conventions/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: HaruhikoMotokawa (https://skillmd.com/u/haruhikomotokawa)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/haruhikomotokawa/sdd-conventions

---


# SDD Conventions

## Spec File Location

All specification documents live in `docs/specs/`. Naming convention: `{feature-slug}.md` (kebab-case).

Status prefix in the filename or frontmatter:

```markdown
---
status: draft | review-requested | approved | in-implementation | implemented
---
```

## Required Sections

Every spec must include all of the following:

1. **Overview** — 1-2 sentences, no jargon, answers "what and why"
2. **Goals** — bullet list of measurable outcomes
3. **Non-Goals** — explicit scope boundaries (not just "everything else")
4. **User Stories** — "As a [role], I want [action] so that [benefit]"
5. **Acceptance Criteria** — testable, Given/When/Then format
6. **Technical Design** — data model changes, API/interface changes, affected components
7. **Open Questions** — unresolved items that could block implementation
8. **Implementation Checklist** — actionable tasks by area (backend, frontend, tests, docs)

## Acceptance Criteria Format

Use Given/When/Then exclusively:

```
- Given [initial state or precondition],
  When [user action or system event],
  Then [observable, verifiable outcome]
```

**Invalid** — "The system should handle errors gracefully"
**Valid** — "Given a network timeout occurs during payment processing, When the user submits the payment form, Then an error message 'Payment failed. Please try again.' is shown and no charge is made"

Each criterion must be verifiable by an automated test or an explicit manual test step.

## Spec Lifecycle

```
draft → review-requested → approved → in-implementation → implemented
```

- **draft**: being written, not ready for review
- **review-requested**: ready for technical and product review
- **approved**: all issues resolved, implementation may begin
- **in-implementation**: actively being built
- **implemented**: feature shipped, spec archived

## Rules

1. Implementation must NOT begin before a spec reaches `approved`
2. All open questions must be resolved before moving to `approved`
3. Acceptance criteria must be testable — if it cannot be verified, rewrite it
4. Breaking an approved spec requires re-approval

## Useful Commands

- `/sdd-spec <feature-name>` — create a new spec
- `/sdd-review [spec-file]` — review a spec for approval readiness
- `/sdd-init` — set up SDD structure in a new project