/design

name: design
model: inherit
effort: high
agents: [explorer, critic]
description: >
  Use to produce a Software Architecture Document for a feature — Arc42 12 sections + C4 L1/L2
  inline + ADRs spawned on a blast-radius gate — once spec.md exists. Triggers on
  "design {slug}", "architecture for {slug}", "SAD for {slug}", "arc42 for {slug}",
  "C4 context+container for {slug}", "/sdd:design {slug}", "спроектуй архітектуру {slug}",
  "SAD для {slug}", "архітектурний документ {slug}". Drafts §1–§12, batch-validates each
  section Socratically (4-state machine), spawns an ADR only when a decision crosses the
  blast-radius threshold (irreversible / multi-module / has legitimate alternatives), writes each
  resolved section + its ADRs to disk immediately, then runs a clean-context critic and commits
  sad.md + each ADR separately.
  Brownfield: dispatches an Explore subagent to map the repo first. Hard-refuse if spec.md
  is missing; CONTEXT.md is optional (when present its Glossary is canonical).

Skill: design

Generator of the **Software Architecture Document** (`docs/features/<slug>/sad.md` — Arc42 12 sections, C4 Context inline in §3 and C4 Container inline in §5) plus supporting ADRs (`docs/features/<slug>/adr/NNNN-*.md`). It drafts all 12 sections in memory, walks them Socratically one section at a time, spawns an ADR only when a decision's *blast radius* (масштаб удару — how painful it is to reverse the decision later) crosses the gate, writes each resolved section and its ADRs to disk as soon as it resolves, runs a clean-context critic over the finished SAD, and then commits once per document — `sad.md` plus each ADR on its own — per [`../_shared/write-and-commit.md`](../_shared/write-and-commit.md). The document itself is the state — resuming after an interrupt is free. L3 Component / L4 Code are out of scope. This file is the spine; detail lives in `references/`.

The Socratic machine, the critic, and the size matrix are **shared** — this skill keeps only its deltas: → [`../_shared/socratic-loop.md`](../_shared/socratic-loop.md) · [`../_shared/critic.md`](../_shared/critic.md) · [`../_shared/size-matrix.md`](../_shared/size-matrix.md) · [`../_shared/ask-style.md`](../_shared/ask-style.md)

`sad.md` + ADR prose follow `artifact_language` — the Arc42 section headings, frontmatter, C4/Mermaid keywords and ADR `Status` values stay English → [`../_shared/artifact-language.md`](../_shared/artifact-language.md).

Depth governs the per-section question volume + autonomy → [`../_shared/interview-depth.md`](../_shared/interview-depth.md). C4 diagrams are confirmed in prose, never as raw source → [`../_shared/diagram-presentation.md`](../_shared/diagram-presentation.md). design is also where the feature's **target surface(s)** are chosen — the first §4 decision, written to `sad.md` frontmatter `target_surfaces` and read (never re-derived) by every downstream stage → [`../_shared/surfaces.md`](../_shared/surfaces.md).

Owner

Architect / Tech Lead (drives everything). PM is consulted only on §10 Quality goals and §11 Risk severities.

Inputs

• `<slug>` — same feature slug used by every earlier stage.
• **Gate (hard-refuse if missing):** `docs/features/<slug>/spec.md`. If absent → STOP and point: «run `specify <slug>` first — design reads the spec's goals/NFRs as canonical».
• (Optional) `CONTEXT.md` — repo-root and/or `docs/features/<slug>/` → [`../glossary/SKILL.md`](../glossary/SKILL.md). When present, its `## Glossary` is canonical for roles + domain terms (per-feature wins over root on conflict); when absent, the spec's §4 roles are canonical and the handoff recommends `/sdd:glossary <slug>` before terms drift.
• (Optional) `docs/features/<slug>/ux-flows.md` — the user flows + SCR screen inventory from `ux-flows`. When present it is **evidence** for the §4 Target-surface + UI-architecture decisions and for the §5 containers — read it in step 2; its absence on a UI-touching feature is legal (the stage may have been skipped) but worth naming in the handoff.
• (Optional) `docs/features/<slug>/.size` — depth hint (MVP vs Full + expected ADR count per the size matrix). Absent → default to M (full set) **and say so loudly in the handoff** — «size M (default — no `.size`; run `/sdd:classify-size <slug>`)».
• A git repo — so the Step-3 Explore subagent can read code on a brownfield.
• Skip if `sad.md` already has all 12 sections filled AND `adr/` has ≥1 file — suggest review instead.

Protocol

1. **Gate + size + set interview depth.** `test -f docs/features/<slug>/spec.md` → missing = refuse with the pointer above. Read `.size` if present (shapes ADR count + §6 flow count — see the size matrix) and `.route` if present. **Then set the interview depth (the opening question):** read `interview_depth` from `.claude/sdd.local.md` if present (else default medium), and — unless a `--depth=easy|medium|hard` arg was passed — ask ONE depth-selection `AskUserQuestion` phrased per [`../_shared/ask-style.md`](../_shared/ask-style.md), with the saved/medium value as the «(Recommended)» first option — **except on route `quick`, where `easy` becomes the «(Recommended)» first option** (the quick-route softening per the Routes table in [`../_shared/size-matrix.md`](../_shared/size-matrix.md)). The level governs the step-6 per-section question volume (easy: decide convention-defaults itself + ledger, ask only blast-radius decisions; medium: walk every real decision; hard: walk every decision, foreground each trade-off) and the C4 diagram confirmation → [`../_shared/interview-depth.md`](../_shared/interview-depth.md). (The blast-radius → ADR gate and the §11 owner+due rule are floors — enforced at every depth.) 2. **Read upstream.** `spec.md` (§2 Goals, §3 Non-goals, §6 NFR with numeric targets + measurement, §6.1 Security/privacy + abuse cases, §7 KPIs, §8 Open questions, any §1 ¶4 «Decision override» bullets); `docs/features/<slug>/ux-flows.md` when present (platform decisions, flows, the SCR