sequences
Use to add Mermaid sequenceDiagram blocks to the SAD's runtime view (sad.md §6) — one per critical flow, showing how a request moves between participants with happy + error paths. Triggers on "sequences for {slug}", "sequence diagram for {slug}", "draw the runtime flow", "add a sequence to the SAD", "/sdd:sequences {slug}", "діаграми послідовності {slug}", "sequence для {slug}", "намалюй потік {slug}". Reads sad.md §5 for participants, drafts each flow from templates/sequence.md with generic participants, walks them Socratically one flow at a time, and writes confirmed blocks into sad.md §6 — they inform data-model indexes downstream. Hard-refuse if sad.md is missing → run `design {slug}` first.
genkovich · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add genkovich/sdd --skill sequencesAbout this skill
name: sequences
model: inherit
effort: medium
agents: []
description: >
Use to add Mermaid sequenceDiagram blocks to the SAD's runtime view (sad.md §6) — one per
critical flow, showing how a request moves between participants with happy + error paths.
Triggers on "sequences for {slug}", "sequence diagram for {slug}", "draw the runtime flow",
"add a sequence to the SAD", "/sdd:sequences {slug}", "діаграми послідовності {slug}",
"sequence для {slug}", "намалюй потік {slug}". Reads sad.md §5 for participants, drafts each
flow from templates/sequence.md with generic participants, walks them Socratically one flow at
a time, and writes confirmed blocks into sad.md §6 — they inform data-model indexes downstream.
Hard-refuse if sad.md is missing → run design {slug} first.
Skill: sequences
Draws the runtime view of an already-designed feature: for each critical flow it produces a Mermaid sequenceDiagram block — generic participants, happy path plus the error branches the spec demands — and writes them into docs/features/<slug>/sad.md §6. One flow at a time, user confirms each. The diagrams are the bridge between the static design (§5 building blocks) and the data layer: every persist/read step you draw becomes a hint for the indexes data-model will need.
Diagram labels + §6 prose follow artifact_language — but the existing sad.md's language wins over the setting; Mermaid keywords (sequenceDiagram, participant, alt/else/end) and participant names that name real modules stay English → ../_shared/artifact-language.md.
This skill keeps only its own machinery. Question phrasing is shared → ../_shared/ask-style.md. Flow count is driven by the spec, not a cap — every §4 user story / §5 acceptance criterion is covered (size may collapse detail, never coverage) → ../_shared/size-matrix.md. Each diagram is confirmed in prose, never as raw Mermaid → ../_shared/diagram-presentation.md; whether each flow is confirmed per-diagram or written-and-summarized follows the interview-depth setting → ../_shared/interview-depth.md.
Owner
Tech Lead (drives the runtime decomposition). The PM confirms that each drawn flow matches a real user story; a backend engineer flags persist steps that imply a new index.
Inputs
<slug>— same feature slug used by every earlier stage.- Gate (hard-refuse if missing):
docs/features/<slug>/sad.md. The §5 building-block view names the participants; §6 is where flows are written. Ifsad.mdis absent → STOP and point: «rundesign <slug>first — sequences are written into its §6». - (Expected)
sad.mdfrontmattertarget_surfaces— picks the participant vocabulary (UI-driven flows for a UI surface). Absent or empty → warn («surfaces undeclared — re-rundesign, or proceeding asbackend-service») and treat as[backend-service](→../_shared/surfaces.md); never silently guess a UI surface. - (Optional)
docs/features/<slug>/ux-flows.md— when it exists, the UI-driven flows drawn here agree with it: the<ui>steps follow the same screen path, and a flow may reference theSCR-NNid in a note; a divergence between a §6 flow and a ux-flow is surfaced, never silently drawn over. - Strongly expected:
docs/features/<slug>/spec.md— §4 user stories tell you which flows exist; §5 acceptance criteria are the coverage floor — every AC must be shown by a flow, a branch, or an explicit non-runtime N/A (the step-7 coverage check). Present by this stage in the normal pipeline; if genuinely absent, fall back to §6/§5 ofsad.mdfor the flow list and note that AC-coverage can't be verified. - (Optional)
docs/features/<slug>/.size— depth hint for detail (XS/S may collapse a flow's internal steps), never for coverage. Absent → default to M and say so loudly in the handoff — «size M (default — no.size; run/sdd:classify-size <slug>)». - (Optional)
.claude/sdd.local.mdinterview_depth(else medium) — governs only the diagram-confirmation UX (per-diagram prose+ask vs. write+summarize-and-proceed);sequencesdoes not open its own depth question (it honors the setting, or a--depth=arg if passed).
Protocol
- Gate.
test -f docs/features/<slug>/sad.md→ fail = refuse with the pointer above. Then read §5 (participants) and §6 (any flows already drawn — this skill is additive, never rewrite an existing block). - Pick the flows — spec-driven, no cap. List the flows from
spec.md§4 user stories + §5 acceptance criteria (absent the spec, from §6 itself): one flow per critical user story / distinct runtime path. There is no fixed cap — draw as many flows as the user stories and ACs need (the old "3–5" cap silently under-covered). Then plan AC coverage: map every §5 AC to where it will be shown — a dedicated flow, analt/elsebranch inside the relevant flow, or explicitly non-runtime (e.g. a middleware-enforced 401, a build-time check) with a one-line reason. Size only collapses detail (XS/S may show fewer internal steps per flow), never coverage. Confirm the flow list and the AC→flow map with oneAskUserQuestionbefore drawing — phrasing per../_shared/ask-style.md. - Map participants — generic only. For each flow, draw participants from a fixed generic vocabulary:
<client>,<ui>,<service>,<data-store>,<external-system>,<message-bus>. Do not invent concrete service or technology names — those aredesign/data-modeldecisions, not runtime-view ones. Whensad.mdfrontmattertarget_surfacesdeclares a UI surface (web-frontend/mobile-app/desktop-app), draw the flows it touches as UI-driven —<user>(actor) →<ui>→ `