/sequences

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`](../_shared/artifact-language.md).

This skill keeps only its own machinery. Question phrasing is **shared** → [`../_shared/ask-style.md`](../_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`](../_shared/size-matrix.md). Each diagram is **confirmed in prose, never as raw Mermaid** → [`../_shared/diagram-presentation.md`](../_shared/diagram-presentation.md); whether each flow is confirmed per-diagram or written-and-summarized follows the interview-depth setting → [`../_shared/interview-depth.md`](../_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. If `sad.md` is absent → STOP and point: «run `design <slug>` first — sequences are written into its §6».
• (Expected) `sad.md` frontmatter `target_surfaces` — picks the participant vocabulary (UI-driven flows for a UI surface). **Absent or empty → warn** («surfaces undeclared — re-run `design`, or proceeding as `backend-service`») **and treat as `[backend-service]`** (→ [`../_shared/surfaces.md`](../_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 the `SCR-NN` id 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 of `sad.md` for 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.md` `interview_depth` (else medium) — governs only the diagram-confirmation UX (per-diagram prose+ask vs. write+summarize-and-proceed); `sequences` does **not** open its own depth question (it honors the setting, or a `--depth=` arg if passed).

Protocol

1. **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). 2. **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**, an **`alt`/`else` branch** 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 one `AskUserQuestion` before drawing — phrasing per [`../_shared/ask-style.md`](../_shared/ask-style.md). 3. **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 are `design`/`data-model` decisions, not runtime-view ones. **When `sad.md` frontmatter `target_surfaces` declares a UI surface** (`web-frontend` / `mobile-app` / `desktop-app`), draw the flows it touches as **UI-driven** — `<user>` (actor) → `<ui>` → `<service>