design

Design

Turn ideas into specs with rigor scaled to scope. Stage 1 of the pipeline; can also run standalone.

Tier (do first if not already set)

If the orchestrator has not set a tier, classify now.

Tier	Criteria
micro	≤30 LOC, single file, no API change, no new dep
small	≤300 LOC, ≤3 files, internal only
full	New API / schema / multi-module / external surface

State the chosen tier explicitly.

Do NOT begin implementation, scaffold code, or invoke any build-phase skill until the design has been presented and approved at the chosen tier.

Anti-pattern: "this is too simple"

Even micro requires the 1-line design and approval. The artifact is small, the gate is not. "Simple" is where unexamined assumptions cause the most wasted work.

Common steps (all tiers)

Run before any tier-specific flow.

1. Prior-spec scan — list filenames in docs/specs/ whose topic relates. Surface up to 3. Ask: "Found prior work in X, Y. Reuse, diverge, or fresh? Reason?"
2. Project context — current files, recent commits, repo conventions
3. Constraints scan — load constraints-scan.md, walk the 7 checks (deploy env, perf, auth, data volume, failure tolerance, ops, platform)
4. Clarifying questions — one at a time, multiple choice preferred. The user may batch ("give me all questions at once"); honor that. If the feature touches paths, files, line endings, encodings, locales, or shell commands, ALWAYS ask explicitly which OSes are supported and capture in the spec's Platform constraint.

Per-tier flow

micro

1. State a 1-line design and the smallest test that proves it
2. Ask: "Approve?"
3. Return: tier=micro, design=<line>, spec_path=null

No spec doc.

small

1. Propose 2 approaches with tradeoffs (skip the 4-slot since scope is bounded)
2. Present a condensed design (≤200 words): problem, approach, files, risks
3. 3-check approval gate — ask:
   • Success criteria measurable?
   • Failure modes named?
   • Scope bounded?
4. Write spec to docs/specs/YYYY-MM-DD-<topic>.md using spec-template.md (sections marked [full only] may be omitted)
5. Commit
6. Return: tier=small, spec_path=<path>

full

1. 4-slot forcing function — consider all four:

   • (a) don't build / wait — what happens if we do nothing? When does it stop being viable?
   • (b) buy / use existing — library, service, or internal system that solves this?
   • (c) build minimal — smallest viable version
   • (d) build full — addresses all known requirements

   Eliminate 2 with reason. Recommend from the remaining 2.

2. Pre-mortem — list top 3 risks. For each:

   • Assumption that, if wrong, kills the design
   • Cheapest test that falsifies the assumption

   No-falsification risks → mark as accepted risk.

3. Section walk — present each, get "looks right" before continuing:

   • Problem
   • Goals & non-goals
   • Constraints
   • Approach (chosen + why)
   • Architecture
   • Data model
   • Failure modes
   • Rollout / migration
   • Success metrics

4. Write spec — use spec-template.md. Save to docs/specs/YYYY-MM-DD-<topic>.md. Commit.

5. Self-review (10 checks) — fix inline:

   1. Placeholders / TBD / TODO removed
   2. Internal consistency
   3. Scope bounded to one plan
   4. Ambiguity removed
   5. Testability — every requirement maps to a test
   6. Failure modes named with handling
   7. Observability — what to log/metric
   8. Security — auth, data exposure, input validation
   9. Rollback / migration plan
   10. Success metrics measurable with thresholds

6. Independent reviewer (subagent) — dispatch using reviewer-prompt.md. On return:

   • Approved → continue
   • Issues Found → present to user, fix, re-dispatch

7. 3-check approval gate — ask:

   • Success criteria measurable? (yes/no)
   • Failure modes named? (yes/no)
   • Scope bounded? (yes/no)

8. Return: tier=full, spec_path=<path>, risks=<list>

Visual decisions

Default to terminal-native:

• Mermaid for flow / sequence / architecture / state
• ASCII for rough layout
• Tables for tradeoffs

Load visual-companion.md only when the question is pixel mockups, polish, color, or true side-by-side designs.

Output

{
  "tier": "micro" | "small" | "full",
  "design": "<line>" | null,
  "spec_path": "<path>" | null,
  "risks": [...] | [],
  "approved_at": "<iso>",
  "spike_required": false | { "question": "<>", "budget": "<>" }
}