Design

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 as one atomic commit (on route quick + depth easy, sections still hit the disk immediately but commits batch — step 6), and runs a clean-context critic over the finished SAD. 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/critic.md · ../_shared/size-matrix.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.

Depth governs the per-section question volume + autonomy → ../_shared/interview-depth.md. C4 diagrams are confirmed in prose, never as raw source → ../_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.

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. 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, 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). 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. (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 inventory — evidence for the §4 Target-surface + UI-architecture decisions and the §5 containers); CONTEXT.md ## Glossary when present — read both repo-root (project-wide) and docs/features/<slug>/CONTEXT.md (feature-scoped); per-feature wins on conflict; canonical roles + domain terms win over anything that contradicts. Neither file exists → the spec's §4 roles are canonical; recommend /sdd:glossary <slug> in the handoff.
3. Current architecture — read the map, don't re-scan. Prefer docs/architecture-map.md (produced by survey): if it exists and is fresh (its reflects_commit ≈ current HEAD), read it — that IS the brownfield context (module layout, layering, datastores, conventions, the C4 of what exists). Re-scan only if the map is absent or stale: dispatch the explorer agent — subagent_type: "sdd:explorer" (model: haiku + effort: low, clean-isolated per ../_shared/agent-roster.md) — for «module layout, layering/ports conventions, datastores, inter-module comms, anything that constrains <slug>», and suggest the user run survey to persist it. Greenfield (no source + no map) → note <!-- brownfield: N/A — greenfield repo --> in §3. (Fallback to a subagent_type: "Explore" Agent if explorer unavailable.)
4. Bootstrap + read template. Copy ./templates/sad.md → docs/features/<slug>/sad.md; patch frontmatter (updated_at, feature_size from .size; leave target_surfaces: [] empty — it's filled when §4's Target-surface decision resolves in step 6). Commit design: <slug> bootstrap sad.md. Read the template's <!-- … --> comments (the per-section contract) + ./templates/adr.md (MADR shape). This is the only file write between Step 4 and Step 6 — Step 5 drafts in-memory.
5. Per-section draft (in-memory). For each §1 → §12, draft proposed content + the decisions it contains, bundling trivial convention defaults into one question. Per-section sourcing, item-banks, the question budget, and pre-Socratic hygiene → ./references/draft-generation.md. Do NOT write sad.md here.
6. Socratic walk + blast-radius gate, per-section write. For each §1 → §12: render the full section + its numbered decisions (big picture), walk one AskUserQuestion per decision with the shared 4-state machine (per-section question volume scales with the depth dial — at easy, decide convention-defaults yourself and ladder them into the assumptions ledger, asking only blast-radius decisions), apply transitions in-memory, run the blast-radius gate on each Approved decision (spawn an ADR on 2-of-3), then write the resolved section + its spawned ADRs + commit design: <slug> sad §N — <summary>. Never return to a written section. Commit cadence: the per-section commit is the default (medium/hard, any route). On route quick + depth easy the section is still written to disk immediately after it resolves (write-after-resolve and never-return hold — an interrupt loses nothing), but commits batch — at most 3 for the pass (e.g. §1–§5, §6–§12, finalization), or a single design: <slug> sad (quick) when the pass ran uninterrupted; 14 doc-commits on an S-feature is noise, not safety. §4's first decision is the Target-surface selection — what's being built (backend-service / web-frontend / mobile-app / desktop-app / cli / worker / library-sdk, derived from spec §1 «for whom» + §4 roles, with ux-flows.md as evidence when it exists — a real screen inventory is a strong signal for a UI surface; the spec itself names no surface), gated by the blast-radius gate (multi-surface is multi-module + irreversible ⇒ usually an ADR). On resolution, write target_surfaces: [...] to the sad.md frontmatter — it draws one §5 C4 container per surface and is read (never re-derived) by api / sequences / tasks / plan-tests / review. For each declared UI surface, walk the follow-on UI-architecture decision (web → SSR/SPA/hybrid; mobile → native/cross-platform; + state/routing if warranted), gated to an ADR like any §4 strategic choice → ../_shared/surfaces.md. For the §3 C4Context and §5 C4Container sections, confirm the diagram per ../_shared/diagram-presentation.md — write the block into sad.md, validate it, then describe the context / containers in prose (who talks to what, which systems it depends on) and confirm by prose; never paste the raw C4 source as the question. At easy, write + a one-line summary and proceed (no per-diagram question). design delta → ./references/socratic.md (section list, decision-types, the gate); gate scoring → ./references/blast-radius.md; C4 syntax for §3/§5 → ./references/c4-mermaid-syntax.md; design-specific question shapes → ./references/ask-examples.md. Maintain the edits-log + an adjacent ADR-spawns log.
7. Critic + finalize. Dispatch the critic agent — subagent_type: "sdd:critic" (clean-isolated per ../_shared/agent-roster.md; model per judgment_model; effort xhigh on L/XL via CLAUDE_CODE_EFFORT_LEVEL; fallback general-purpose if unavailable) — with the design delta in ./references/critic.md (over ../_shared/critic.md) on the final sad.md + edits-log + ADR-spawns log; resolve each finding via AskUserQuestion (Accept revert / Accept amendment / Override-with-rationale → §1 ¶4 bullet). Run the pre-write backstop scans: validate every Mermaid block in sad.md per ../_shared/mermaid-check.md (render-parse with mmdc if available, else the structural lint — fix any that don't parse, never commit a broken diagram); ADR title in decision-form kebab-case + Status Accepted; §9 closed against adr/; no <placeholder> stubs. On pass, write any amendments + commit design: <slug> finalization (critic pass). Then emit the stage-handoff block per ../_shared/handoff.md — What I did + Review (sad.md, adr/) + Run next — resolve the next stage per .route (the Routes table in ../_shared/size-matrix.md): forward /sdd:sequences <slug> (which writes flows into §6); sequences' N/A condition = one actor and no multi-step runtime flow, skip target /sdd:data-model <slug> (on quick — auto-skip with the reason + inverted ↳ or; on standard — offer the ↳ or; on full — no skip line); when skipping, carry the next conditions forward in order: no schema change either → /sdd:api <slug> directly; no contract change either → evaluate screens' N/A condition (no UI surface in target_surfaces) → /sdd:screens <slug>, or /sdd:tasks <slug> when that holds too.