tzurot-design-boulder

name	tzurot-design-boulder
description	The design-boulder process: grounded, council-reviewed architecture design sessions producing an ACCEPTED artifact. Invoke with /tzurot-design-boulder when starting a design session for a feature or subsystem too large to plan inline.
lastUpdated	2026-07-05

Design Boulder Procedures

Invoke with /tzurot-design-boulder when starting a design session. A "boulder" is a design-heavy work item where the approach is the deliverable: multi-system features, architecture rewrites, new subsystems. The output is an ACCEPTED design artifact in docs/proposals/backlog/, not code.

Proven across the full accepted-artifact set in docs/proposals/backlog/.

When to boulder vs. plan inline

Boulder	Plan mode / inline
The design decides architecture for quarters (tiers, schemas, protocols)	The design is one PR's shape
Multiple viable approaches with real tradeoffs	One obvious approach
Grounding requires research (external prior art, provider docs, multi-file code archaeology)	The codebase context fits in one read
The owner has directives/opinions to incorporate	Purely technical call

The cadence

1. Ground (parallel agents + own archaeology)

• 2–4 read-only agents, each with a distinct lens: (a) the system as actually implemented (exact orders, types, call sites — design-grade, not vibes), (b) entity/data landscape, (c) external prior art / provider APIs (web), (d) our own prior designs and backlog archaeology.
• Check for prior design work FIRST (docs/proposals/backlog/, themes, git log) — prior proposals have nearly been re-derived. Their resolved decisions carry forward; their stale claims get flagged, not trusted.
• Verify provider/library facts against first-party docs, not memory — stale provider knowledge has forced whole design sections to be deleted. Mark findings [V] verified / [I] inferred; anything load-bearing gets a citation or a named runtime probe.
• Agents return structured reports; the grounding output that matters most is the table nobody can argue with (exact orders, scoping matrices, traced wires).

2. Draft (decision table + open calls)

• One artifact in docs/proposals/backlog/<slug>.md. Header: Status (Draft), what it supersedes/extends, owner directives verbatim, grounding provenance.
• Body: the system-as-is (verified facts only) → numbered decisions (D1..Dn), each with rationale AND the rejected alternative → what this deliberately does NOT do → schema/phasing sketches → § Open calls: the genuinely contestable choices, each with a recommendation.
• Confirm the owner's actual concern is the artifact's center — an artifact centered on the wrong concern costs a full second artifact. If the directive is dictated/informal, restate what you think the center is before drafting deep.
• Plans touching schema or user-visible behavior: restate user-visible semantics in plain terms (per 00-critical.md § Before Code Changes).

3. Council (full trio, adversarial)

• Load /tzurot-council-mcp first and use its CURRENT roster + model IDs — a from-memory roster runs short and wastes the pass.
• One adversarial brief per model (identical text): compressed verified context + the decisions + numbered open calls + "attack: wrong X, missed Y; verdict per call; top 3 misses." Send all trio calls in ONE message (parallel).
• Fold verdicts honestly: unanimous-accept → confirm; split → the split IS the owner question (present all positions); council catches a real flaw → rebuild that section and SAY SO in the doc ("council-rebuilt", "the draft was self-contradictory — all three caught it"). Add a § Council record: what was adopted, what was declined and why, per-model attribution.
• Councils earn their tokens on implementation truth (wire contracts, fan-out math, phase ordering) — feed them implementation-grade context, not vision statements.

4. Owner pass (batched)

• One AskUserQuestion batch: the genuinely-owner calls as separate questions (council splits, taste calls), everything council-unanimous as a single "Confirm all (Recommended)" with a Hold option that names the doc path.
• Owner answers that are new design input (not just confirm/deny) get folded as "owner-refined" decisions with the reasoning captured.
• Owner directives are immutable session state — a decided call never gets re-proposed in a later phase.

5. Land (acceptance + absorption wiring)

All in one commit (docs-only → direct develop commit is sanctioned):

• Artifact Status → ACCEPTED <date> + council/owner sign-off line; open calls table → per-row CONFIRMED/decided status.
• Absorption map: superseded proposals get a superseded-by note (keep the still-useful tables); themes whose items the artifact discharges get an annotation (strike what's absorbed, keep what remains); follow-ups rows promoted into the design get updated; backlog/now.md + CURRENT.md updated. pnpm ops guard:proposal-links + pnpm backlog:lint must pass.
• Declined ideas get NO tombstone — the decline rationale lives in the artifact's council record.

Variants

• Sibling boulders, shared grounding: two related designs can share one grounding wave; draft both, run ONE trio pass covering both (verdicts per open call of each), land together.
• Owner-input mid-flight: owners drop links/notes/voice-dictated scoping models during grounding — treat as grounding input, cite as "owner directive" in the artifact, and use local curl/wget with a browser UA for bot-walled links the owner has personally vetted.
• Prod bugs surfaced by grounding: file on the board immediately (now.md § Production Issues) and let the owner sequence them vs. the design work — grounding agents reading real code find real bugs.

Anti-patterns

Don't	Do
Draft from memory of how the system works	Ground first; the draft cites the sweep
Present the council a vision statement	Feed it call sites, orders, types
Merge council riders silently	§ Council record with attribution
Re-derive a prior proposal	Mine it; carry its resolved decisions forward
Land the artifact without absorption wiring	The landing commit IS the wiring
Treat "design done" as "work done"	Phasing table names the build slices; board carries the next step