Design First

Design First — Progressive Design Facilitation

The failure mode this prevents is not "no design". It is the agent producing a confident, complete, plausible design in one shot — which the user skims, approves, and discovers is wrong after the code exists. A design nobody was forced to think about is worse than no design, because it carries authority it did not earn.

Progressive facilitation fixes this by climbing one level at a time, asking rather than asserting, and refusing to descend to the next level until the current one is agreed.

Config Resolution

1. Read .msskills/config.yaml in the repo root; look up paths.design.
2. A custom document exists at that path → read its frontmatter mode:
   • override → use it alone as the design process; ignore the defaults below.
   • overlay (default, or no mode key) → read defaults first, then apply the custom document's sections on top, matched by exact heading; new sections append.
3. A path is configured but no file exists there → say which path is missing, then use the embedded defaults.
4. No config file or no paths.design key → use defaults.
5. .msskills/stack.md exists → phrase every question in that stack's vocabulary. Do not ask a Go team about Spring profiles.

The four levels

Each level answers one question and produces one artefact. See defaults for the question banks and the blueprint template.

Climb in order. L3 cannot be answered before the components exist; L4 cannot be answered before the interactions do. Jumping to L4 because the user asked for "the API" produces a schema for a service whose boundary nobody agreed on.

Self-Validation Checklist

STOP at the end of each level. Verify every check before proposing to descend.

1. ONE LEVEL: Does this message address exactly one level? Content from the next level → remove it and hold it for that level.
2. QUESTIONS OVER ASSERTIONS: Are the open points asked, or asserted? Anything you inferred about the domain, the users, or the constraints → turn it into a question or flag it as an explicit assumption.
3. UNKNOWNS NAMED: Have you listed what you still do not know at this level? Silence about a gap reads as certainty.
4. GROUNDED: Does every statement reference something real — an existing service, table, endpoint, or a constraint the user gave? Unsourced detail is invention → go read the code or ask.
5. DECISIONS SURFACED: Has every genuine trade-off at this level been routed through collaborative-judgment rather than settled inside the prose?
6. RECORDED: Is the level's outcome written into the blueprint document, including the rejected options and why?
7. GATE STATED: Have you explicitly asked to proceed, and named what the next level will decide? "Shall I continue?" is not a gate; "Shall I move to L3, where we settle sync versus async for the payment hop?" is.
8. NO CODE: Have you written implementation code? Interfaces, schemas, and signatures are L4 artefacts; bodies are not. Delete them.

All checks pass → present the level, then stop and wait.

Active Anti-Pattern Scan

Any box you can check is a defect. Fix it before presenting.

• Big-Bang Blueprint: all four levels delivered in one message → split; present L1 and stop.
• Confident Invention: entities, rules, or volumes stated as fact that came from nowhere → mark as assumption or ask.
• Rhetorical Questions: questions asked and then answered in the same breath → ask, then stop.
• Design as Menu: a list of every possible approach with no position → recommend one and say why, per collaborative-judgment.
• Premature Contracts: field-level schemas at L1 or L2 → defer to L4.
• Skipped Failure Story: L3 flows with only the happy path → every hop needs its timeout, retry, and failure behaviour, per resilience-patterns.
• Boundary Assumed: a new service proposed without asking whether it belongs in an existing one → route through service-boundaries first.
• Ceremony Mismatch: four full levels for a one-endpoint change → calibrate depth (see below).
• Orphan Design: the blueprint is never written to disk, so implementation cannot reference it → write it as you go, not at the end.
• Approval Assumed: descending because the user said "ok" to something else → each gate is explicit.

Ambiguity Signals

Route these through collaborative-judgment rather than deciding alone.

• How deep to climb. A new bounded context earns all four levels. A field added to an existing endpoint earns L4 alone. Most work sits between; propose a depth at the start and let the user cut it. Depth is the user's call, not yours.
• When the design contradicts existing code. The blueprint says one thing, the repository does another. Both "the code is stale" and "the design is wrong" are plausible — present the conflict rather than quietly following either.
• Unknowable answers. Some questions ("what will peak load be?") cannot be answered before launch. The choice between designing for the guess and designing to defer is a real trade-off.
• Requirements that change mid-climb. Restarting from L1 is expensive; patching L3 around a changed L1 produces incoherence. Say which levels the change invalidates and let the user choose.