`design`

Take a ratified requirement to a recorded architectural decision — constraints, structure, diagrams, threats, then a panel that must agree before the decision is written down.

Use it when: Use when the user is designing a system, choosing an architecture, or asking how something should be built.
Comes with: The solution-architect pack
Where you decide: Ratify (G1): a review panel decides
Size: 5 stages · 1 gate · up to 3 revision rounds

npx skilldrop-cli install --loop design

Installs the loop as an invokable skill, plus every skill its stages run.

Other ways to install

Every loop in its pack, with their skills:

npx skilldrop-cli install --loop --pack solution-architect

The loop alone, without its stage skills (each stage falls back to an inline version):

npx skilldrop-cli install --loop design --no-skills

In Claude Code, the solution-architect plugin includes it:

/plugin install solution-architect@skilldrop

The loop

%%{init: {'theme':'base','themeVariables':{'fontFamily':'Segoe UI, Helvetica, Arial','fontSize':'15px','lineColor':'#9AA5B1'},'flowchart':{'curve':'basis','rankSpacing':70,'nodeSpacing':50,'padding':16}}}%%
flowchart LR
    classDef gen    fill:#E8F0FE,stroke:#4C7DF0,stroke-width:1.5px,color:#1A3A8F;
    classDef review fill:#FDEAEA,stroke:#E05B5B,stroke-width:1.5px,color:#8A1F1F;
    classDef gate   fill:#FBE3A2,stroke:#D9971E,stroke-width:2px,color:#6B4500,font-weight:bold;
    classDef ship   fill:#E6F7EC,stroke:#34A853,stroke-width:2px,color:#0F6B33,font-weight:bold;

    constrain["constrain<br/><small>context-graph·nfr-spec</small>"]:::gen
    shape["shape<br/><small>design-doc·architecture-diagrams</small>"]:::gen
    threat["threat<br/><small>threat-model</small>"]:::review
    ratify["ratify<br/><small>council-review</small>"]:::gate
    record["record<br/><small>adr-generator·context-graph</small>"]:::gen
    G1{"G1 · review"}:::gate
    DONE(["complete"]):::ship

    constrain --> shape
    shape --> threat
    threat --> ratify
    ratify --> G1
    G1 == "PROCEED" ==> record
    record --> DONE

    G1 -- "REVISE (max 3)" --> shape

Stages

#	Stage	What it does	Skills	Gate
1	constrain generate	Read the decisions already in force where the design will land, then name the quality targets before the structure, so the design is judged against numbers and the existing decisions rather than taste.	`context-graph`, `nfr-spec`	—
2	shape generate	Write the design and render it. The prose and the picture are one artifact and must not disagree.	`design-doc`, `architecture-diagrams`	—
3	threat verify	Attack the design that now exists, before it is ratified rather than after it is built.	`threat-model`	—
4	ratify gate	A standing panel takes independent positions before cross-talk, surfaces the cruxes, and records dissent.	`council-review`	G1 — a review panel decides PROCEED · PROCEED WITH CONDITIONS · REVISE · RECONSIDER · SPLIT · BLOCKED
5	record generate	Write the decision down with its rejected alternatives, so the next team inherits the reasoning and not just the outcome, then check the records still agree with each other.	`adr-generator`, `context-graph`	—

The loop with the worst reversibility profile in the repo. A discovery mistake costs a re-brief; a design mistake surfaces months later, in code nobody wants to unwind. That is why its gate is a panel — independent positions, surfaced cruxes, recorded dissent — and not a script, and why the decision is recorded only after the panel agrees.

How to run this loop

Constrain before shaping. First run context-graph where the design will land. List the decisions already in force there, each by id, and any the code has drifted from. A new design either keeps each one or says which it supersedes; when the repo has no records, say so. Then run nfr-spec, always. A design produced before its quality targets exist gets judged on taste, and taste does not survive a review panel.
Shape prose and picture together. design-doc and architecture-diagrams are one artifact in two renderings. A diagram that disagrees with the doc is a defect in both.
Attack it before ratifying. threat-model consumes the design directly. Running it after G1 means the panel ratified something nobody had attacked.
Ratify at G1. council-review seats the standing panel, takes positions before cross-talk, names the cruxes, and records dissent with "what would change our mind". REVISE returns to shape. SPLIT and RECONSIDER leave the loop.
Record last. adr-generator writes the decision after it is a decision, with the rejected options and the reasoning that killed them. An ADR written before G1 is a proposal wearing an ADR's clothes. Then run context-graph again. Every record the new ADR supersedes must now say "Superseded by" it, and the new ADR must name the code it governs. A supersession recorded on one side only is the most common way a decision log starts to lie.

Verdicts

Defined in contracts/terminals.json. PROCEED WITH CONDITIONS is the common outcome and the most abused: the conditions are part of the decision, and record must carry them into the ADR.

Non-interactive runs

council-review can be run by an agent seating the panel itself, so G1 is satisfiable without a human. SPLIT is not — a genuine unresolved split needs a person. Emit BLOCKED: need a decision-maker for <the crux> and name the positions.

When a stage's skill is not installed

Name the missing skill and skilldrop as its source, do the minimal inline version, and record the stage as degraded. If council-review is missing, do not skip G1 — run the panel inline from the design's own quality attributes and say the seating was improvised.

Run log (opt-in)

Only when the environment variable SKILLDROP_LOOP_LOG is set to a file path: after each gate's verdict, append one JSON line to that file. Nothing else is recorded, and nothing is sent anywhere. When the variable isn't set, or you can't read it, skip this section.

printf '%s\n' '{"ts":"2026-10-01T14:03:00Z","loop":"design","stage":"ratify","gate":"G1","verdict":"PROCEED","round":1}' >> "$SKILLDROP_LOOP_LOG"

Fields: ts (UTC), loop, stage, gate (null for a stage without one), verdict (the gate's exact word), and round (1 for the first attempt, counting returns under the cap). skilldrop loop-stats summarises the file: which gates pass first time, which loop back, and which end in BLOCKED.

Quality bar

Quality targets exist before structure does. nfr-spec is stage 1 because a design without numbers can only be argued about.
The ADR names what was rejected and why. A decision record with one option is a description of what happened, not a decision.
Dissent is recorded, not resolved away. A panel that always reaches consensus is not seating real positions.
The diagram and the doc say the same thing. They are checked against each other before G1, not after someone builds from the wrong one.
The design names the decisions already in force where it lands, and which of them it keeps or supersedes.
After record, the records agree with each other: each record the new ADR supersedes says so too.

Anti-patterns to avoid

❌ Writing the ADR before G1. It pre-commits the panel to a decision it has not made, and every reviewer can feel it.
❌ Running threat-model after ratification. The panel then ratified an unattacked design, which is the failure this ordering exists to prevent.
❌ Treating PROCEED WITH CONDITIONS as PROCEED. The conditions must reach the ADR; dropping them is how a conditional approval silently becomes unconditional.
❌ Designing over a decision nobody read. A new design that quietly contradicts a current ADR leaves two decisions in force on one system, and the next reader can't tell which one wins.
❌ Skipping constrain because the NFRs are "obvious". Obvious targets are the ones nobody writes down and everybody remembers differently.

Source

LOOP.md · loop.json on GitHub · Why loops