SDD (Spec-Driven Development) Skill

Spec-Driven Development workflow that enforces the sdd/ folder hierarchy. All development work proceeds through planning-first gates and produces current-state artifacts as completion evidence.

Trigger Keywords

Invoke this skill when user requests:

• 개발해, 작업해, 구현해, 수정해, 고쳐, 리팩토링해, 테스트해, 배포해
• 화면명세서, 화면설계서, UI, 디자인, screen spec, screen design
• develop, implement, fix, refactor, build, deploy

sdd/ Folder Hierarchy

sdd/
├── 01_planning/     # Requirements, constraints, stakeholder input
├── 02_plan/         # Execution plan, acceptance criteria, approach
├── 03_build/        # Current build state, implementation notes
├── 04_verify/       # Verification evidence, test results, residual risks
├── 05_operate/      # Deployment notes, runbooks (conditional)
├── 99_toolchain/    # Tool configs, scripts, environment setup
└── decisions/       # Decision records for major design choices

Key Principle: These folders are current-state artifacts, not history archives. Each file reflects the current state of the work — update in place rather than appending new versions.

Workflow

Step 0: Activation Check

Verify sdd/ folder exists in the project root:

ls sdd/ 2>/dev/null || echo "sdd/ folder not found"

If sdd/ does not exist:

1. Inform the user that SDD workflow requires a sdd/ folder
2. Offer to create the folder structure: mkdir -p sdd/{01_planning,02_plan,03_build,04_verify,05_operate,99_toolchain,decisions}
3. Ask user to confirm before proceeding

If sdd/ exists, continue to Step 1.

Step 1: Planning Review (Gate)

MUST complete before any coding begins.

Read all relevant planning documents:

[SDD] Reading planning documents...
├── sdd/01_planning/ — requirements, constraints
└── sdd/99_toolchain/ — tool configs, environment

Actions:

1. Read sdd/01_planning/ contents (all .md files)
2. Read sdd/99_toolchain/ if present
3. Identify: What is the task? What constraints exist? What is in scope?
4. If planning docs are empty or missing, prompt user to fill them before proceeding

Gate: If planning docs are absent or insufficient, pause and ask user to provide requirements. Do NOT proceed to plan phase without understanding the context.

Step 2: Plan Phase

Create or update sdd/02_plan/ with the execution plan.

Artifact to produce: sdd/02_plan/current.md

# Execution Plan

## Task
{task description}

## Approach
{implementation strategy}

## Acceptance Criteria
- [ ] {criterion 1}
- [ ] {criterion 2}
- [ ] {criterion N}

## Out of Scope
- {what will NOT be done}

## Dependencies
- {prerequisite or dependency}

Display:

[SDD Plan] Created sdd/02_plan/current.md
├── Approach: {one-line summary}
├── Criteria: {N} acceptance criteria defined
└── Gate: Plan ready — proceeding to build

Step 3: Build Phase

Implement the changes. Update sdd/03_build/ with current build state.

Artifact to produce or update: sdd/03_build/current.md

# Build State

## Status
{In Progress | Complete}

## Implemented
- {file or component}: {what was done}

## Decisions Made
- {decision}: {rationale}
- Write DR for major decisions: sdd/decisions/{YYYY-MM-DD}-{topic}.md (template: templates/decision-record.md)

## Known Issues
- {issue}: {planned resolution}

During implementation:

• Follow the plan from Step 2
• Update sdd/03_build/current.md as work progresses
• Keep the artifact current (not a log — overwrite stale entries)

Display:

[SDD Build] Implementing changes...
[SDD Build] Updated sdd/03_build/current.md
└── Status: {In Progress | Complete}

Step 4: Verify Phase

Run verification and update sdd/04_verify/ with evidence.

Artifact to produce or update: sdd/04_verify/current.md

# Verification Evidence

## Acceptance Criteria Results
- [x] {criterion 1}: {evidence}
- [x] {criterion 2}: {evidence}
- [ ] {criterion N}: {reason if not passing}

## Tests Run
- {test command or suite}: {result}

## Residual Risks
- {risk}: {severity} — {mitigation plan}

## Verdict
{Pass | Fail | Conditional Pass}

Actions:

1. Check each acceptance criterion from sdd/02_plan/current.md
2. Run applicable tests or verification commands
3. Document evidence (do NOT just say "tests pass" — include actual output or reference)
4. List residual risks honestly

Gate: If verdict is Fail, return to Step 3 (Build). Do NOT declare done with a Fail verdict.

Display:

[SDD Verify] Running verification...
[SDD Verify] Updated sdd/04_verify/current.md
├── Criteria: {N}/{total} passing
├── Residual risks: {count}
└── Verdict: {Pass | Fail | Conditional Pass}

Step 5: Operate Phase (Conditional)

Only execute if deployment is in scope for this task.

Artifact to produce or update: sdd/05_operate/current.md

# Operate State

## Deployment
- Environment: {target}
- Method: {how deployed}
- Timestamp: {when}

## Runbook
{steps to operate, restart, rollback}

## Monitoring
{what to watch, alerts, logs}

Skip this step if:

• Task is code-only (no deployment)
• User did not request deployment
• Deployment is handled by CI/CD automatically

Step 6: Completion Gate

Before declaring [Done], verify:

[SDD Done?] Checking completion gates...
├── sdd/02_plan/current.md — exists? {Y/N}
├── sdd/03_build/current.md — exists and current? {Y/N}
├── sdd/04_verify/current.md — exists and verdict Pass? {Y/N}
└── sdd/05_operate/current.md — exists (if deploy in scope)? {Y/N}

If any gate fails, complete the missing artifact before declaring done.

Final display:

[SDD Done] Task complete
├── Plan: sdd/02_plan/current.md
├── Build: sdd/03_build/current.md
├── Verify: sdd/04_verify/current.md (Verdict: Pass)
└── Artifacts are current-state — ready for next iteration

Artifact Maintenance Rules

1. Overwrite, don't append: Update files in place. These are current-state docs, not logs.
2. One file per folder: current.md is the canonical artifact. Supplementary files are allowed but the main doc is always current.md.
3. Checkboxes reflect reality: Do NOT pre-check criteria. Update checkboxes as work is verified.
4. Residual risks are honest: List known risks even after passing. Hiding risks defeats the purpose.

Decision Record Template

Major design decisions during Step 3 are recorded in sdd/decisions/{YYYY-MM-DD}-{topic}.md using the template at templates/decision-record.md (relative to this skill directory).

When to create a Decision Record:

• Architectural choice between 2+ viable options
• Trade-off accepted (e.g., complexity for performance)
• Deferred decision (waiting for data/approval)
• Superseding a previous decision

See guides/harness-engineering/ for harness-level decision context that DRs may reference.

Integration with Other Skills

Skill	When to Use Together
/deep-plan	Before /sdd-dev when requirements are ambiguous — use deep-plan to research, then sdd-dev to execute
/structured-dev-cycle	Alternative workflow without sdd/ folder — use sdd-dev when project uses sdd/ hierarchy
/dev-review	After Step 4 — use dev-review for additional code quality check
/adversarial-review	After Step 4 — use adversarial-review for security-sensitive changes

Example Usage

/sdd-dev add user authentication to the API
/sdd-dev implement pagination for the product list screen
/sdd-dev 화면명세서 기반으로 대시보드 UI 구현
/sdd-dev refactor the payment module
/sdd-dev  # (no argument — guided workflow)

When no argument is provided, ask: "어떤 작업을 진행할까요? sdd/01_planning/ 의 요구사항을 기반으로 계획을 수립합니다."