/swarm-design-deep

name: swarm-design-deep
description: The developer-driven design lane — the user commits to each approach before anything is written, then the design goes to pseudocode, algorithms, invariants, sequence diagrams and test vectors in their chosen design language. Use when the user wants to own the system rather than receive it: "developer mode", deep/detailed design, designing algorithms or data structures, writing pseudocode or sequence diagrams during design, or human-driven planning after the SRS.

swarm-design-deep — the developer-driven design lane

**Gate:** requires a validated SRS. This lane **replaces** swarm-design for the phase — do not run both; one skill owns the design artifacts.

The standard lane (swarm-design) is agent-driven: it proposes an architecture and the user validates it. That is the right trade for most projects. This lane exists for the other case — a developer who must hold the system in their head afterwards. It is slower and costs more tokens on purpose, and it pays for itself only if implementation comes out mechanical.

The contract

Treat the design session as the agent, and apply six of the 12 factors to it:

| | applied here | |---|---| | **8** own your control flow | The user decides what is designed next. Never advance the unit list yourself. | | **7** contact humans with tool calls | Every unresolved choice is an explicit question. No assumption reaches the doc silently. | | **3** own your context window | Design lives in per-unit files, not the transcript. This is what makes the depth affordable. | | **6** launch/pause/resume | One unit per session, closed and dropped. A cold session resumes from the unit table. | | **12** stateless reducer | Each session = (files so far + one decision) → updated files. | | **10** small, focused agents | One unit designed to the bottom beats the whole system designed halfway. |

**Awareness is caused by producing, not by reading.** Forty pages of excellent design gets a rubber stamp. The commit step below is the whole point of the lane; without it this is just swarm-design with more words.

Setup — the design profile (ask once)

Write `docs/design/profile.md`, then never ask again:

• **design language** — what algorithms and signatures are written in. *Independent of the

implementation language*: designing in Java and building in Python is normal. Language-neutral pseudocode is a valid answer. Say this out loud when asking, because users assume it's the build language.

• **granularity** — what one unit is here (module / service / endpoint / algorithm).
• **diagram formats** — see `references/diagrams.md`.
• **standing depth override**, if any.

Units and depth triage

Decompose into units and give each a class. Propose the triage, get it confirmed. **Depth is allocated, not applied** — this is the primary token control.

| class | signals | owes | |---|---|---| | **algorithmic** | novel logic, ordering/state/concurrency, performance-sensitive, non-obvious data structure | pseudocode, data structures, invariants, complexity, edge-case table, **test-vector table** | | **integration** | crosses a boundary — network, process, third party, filesystem, user | sequence diagram, contract (types in/out), failure modes with timeout/retry/idempotency stance | | **mechanical** | CRUD, config, glue, framework-shaped, fully determined by its contract | signature + one line of intent. **No pseudocode.** |

Level-0 units are the standard lane's deliverables — stack, decomposition, data model, milestone boundaries — run through the same loop. Level-1 units are the modules themselves.

If the user asks for algorithmic depth on something mechanical: **say what it costs and what it buys, once**, then do as they decide. Pseudocode for a CRUD handler is waterfall with extra steps, and saying so is part of the job — arguing twice is not.

The unit loop

Per unit, in order. Steps 1–2 are the lane; skip step 2 and you are running swarm-design.

1. **Frame.** What must this unit do (FR refs), what constrains it (NFR refs), what goes in and out, and 2–3 candidate approaches with real trade-offs. **Write no implementation detail yet.** Read the relevant FR spec, not the whole SRS. 2. **Commit.** The user states the approach in their own words, or picks one and says why. Wait for it. If they delegate — "you pick" — decide, and record `decided-by: agent (delegated)`. Do not treat silence, a "sounds good", or a question as a commitment. 3. **Draft.** Write the unit file against *their* approach, not your preferred one. Include whatever the depth class owes. 4. **Check.** Ask 2–3 questions about **consequences**, not content: "what happens if the queue is empty when the timer fires?" Aim them at the parts most likely to be wrong. A wrong answer means the design or the explanation is wrong — fix it, don't re-explain harder. This is not a quiz and must not read as one. 5. **Close.** Record status and attribution in the unit table, drop the unit from context, and **report units remaining**.

The user may write any part themselves — a signature, the control flow, the whole unit. Complete and critique it rather than replacing it, and record that they wrote it.

**When a committed approach proves wrong while drafting:** stop, show the conflict with evidence, and return to step 1 for that unit. Never quietly design something else.

Ownership accounting

Each unit carries `decided-by: user | agent (delegated)`. At the exit summary, report the ratio. If more than half were delegated, say it in one plain line — the lane was chosen for ownership, and that is how much of it they hold. State it and move on; it does not block.

Files

docs/design/
  profile.md              design language, granularity, diagram formats, depth policy
  overview.md             system map · unit table (class · status · decided-by) · FR traceability
  units/NN-<slug>.md      one file per unit  (template: references/uni