/using-sdd

name: using-sdd
type: workflow
description: "Routes every software-development request through the right SDD workflow before action. Use at session start, before clarifying questions, before edits, and whenever deciding which SDD skill should govern a task."
argument-hint: "[user-request-or-current-task]"
user-invocable: true
allowed-tools: Read, Glob, Grep
context: main
effort: 2
agent: technical-director
when_to_use: "Use at the start of every SDD session and before any non-trivial response, clarification, code edit, review, bug fix, plan, commit, or completion claim."

Using SDD

`using-sdd` is the router and discipline layer for the Software Development Department. It does not replace specialist skills. It decides which SDD workflow must govern the current request before the agent acts.

For phase orientation, use `docs/technical/SDD_LIFECYCLE_MAP.md` (`DEFINE -> PLAN -> BUILD -> VERIFY -> REVIEW -> SHIP`). For detailed runtime stage rules, use `docs/technical/CONTROL_PLANE_MAP.md`.

Core Rule

Before answering, asking clarifying questions, editing files, spawning agents, or claiming completion, check whether an SDD skill applies.

If a skill applies, use it. Do not rely on memory of the skill. Read the current skill and follow its gates.

Skill Routing

| User intent or situation | Required SDD workflow | | --- | --- | | Codex environment, Codex setup, AGENTS.md, .codex, Claude-to-Codex tool mapping, or SDD outside Claude Code | `codex-sdd` then route through `using-sdd` | | First session, unclear project state | `start` | | Vague product idea, ideation, product direction | `brainstorm` | | User wants structured requirements or says "ask me", "don't assume", "interview" | `deep-interview` | | New feature, behavior change, architectural change | `spec-driven-development` | | Existing spec needs readiness review before planning or implementation | `review-spec` | | Approved spec conflicts with code, tests, review findings, user feedback, or platform reality | `spec-evolution` | | Framework, library, external API, platform behavior, deprecation, migration, or "latest/official/best practice" correctness matters | `source-driven-development` | | Epic, multi-step work, large prompt, many files | `planning-and-task-breakdown` | | Implementation of one approved task | `test-driven-development` | | Execution of approved multi-task sequential plan with review gates | `subagent-driven-development` | | Bug, failing test, build failure, CI failure, performance regression, or unexpected behavior | `systematic-debugging` | | Complex, intermittent, unfamiliar, or repeatedly failed bug investigation | `diagnose` | | Simple obvious bug with clear cause | `test-driven-development` with a regression test | | Coordinated multi-agent work across domains | `orchestrate` | | Independent parallel workstreams | `fork-join` | | UI/frontend architecture or component design | `frontend-design` or `ui-spec` | | API contract or endpoint design | `api-design` | | Architecture decision with durable consequences | `architecture-decision-records` | | Code quality, PR review, merge readiness | `code-review` or `code-review-checklist` | | Prose quality for specs, ADRs, PR bodies, release notes, or technical docs | `style-review` | | Behavior-preserving cleanup, simplification, readability refactor, or complexity reduction after tests pass | `code-simplification` | | Review comments, PR feedback, CHANGES_REQUIRED verdict, or reviewer questions need response | `receiving-code-review` | | Phase transition or readiness review | `gate-check` | | Release or launch preparation | `release-checklist` or `launch-checklist` | | Completion claim, success claim, task done, fixed, passing, ready, clean, merge-ready | `verification-before-completion` | | Commit requested | `commit` | | Create, update, refine, or evaluate an SDD skill; repeated prompt should become a skill; agent failure suggests missing/broken skill | `learner` | | Save reusable lesson or preference | `learner` or `annotate` | | Context is too large or stale | `context-engineering` or `save-state` |

When multiple skills apply, use process skills before implementation skills:

1. Requirements and design: `brainstorm`, `deep-interview`, `spec-driven-development`, `review-spec`, `source-driven-development`, `spec-evolution` 2. Planning and coordination: `planning-and-task-breakdown`, `subagent-driven-development`, `orchestrate`, `fork-join` 3. Investigation and execution: `systematic-debugging`, `test-driven-development`, domain implementation skills 4. Review and release: `verification-before-completion`, `code-review`, `style-review`, `code-simplification`, `receiving-code-review`, `gate-check`, `release-checklist` 5. Skill evolution: `learner` after evidence exists, or before edits when the task is explicitly to improve skills.

Mandatory Gates

Before Implementation

Implementation code means any production behavior change in files such as `src/`, `app/`, `lib/`, `services/`, `components/`, migrations, infrastructure, runtime config, hooks, build scripts, or generated assets that ship with the product. Tests are only allowed before production code when they are part of a TDD RED phase.

Do not write implementation code until one of these gate paths is satisfied:

| Gate path | Allowed when | Required before code | | --- | --- | --- | | Fast Gate | Small, explicit, low-risk edit; one obvious file; no behavior ambiguity | State the exact file, exact change, risk check, and verification command/check | | Spec Gate | New feature, behavior change, UI flow, API change, data change, or unclear side effects | Use `spec-driven-development`; present spec and task sequence; get explicit user approval | | Spec Review Gate | Existing spec is the source of truth for a plan, review, or implementation | Use `review-spec`; proceed only if verdict is `APPROVED` or the plan carries non-blocking notes | | Spec Evolution Gate | Approved spec