ReinaMacCredy maestro-design
Use when the request, acceptance, authority, or implementation boundary is unsettled. Design is human-guided whenever a choice changes what will be built. Do not begin implementation until the relevant decisions are locked and the user has approved the resulting scope. Design is read-only toward production code and authorizes nothing.
Mode per unknown
Identify what kind of unknown blocks progress, then load only the reference that resolves it:
| The unknown | Mode | Reference |
|---|---|---|
| Decisions only the user can make, several and interdependent | grill | references/grilling.md |
| A decision owned by someone not in the conversation | route to maestro-questionnaire |
|
| A fact in docs, APIs, or source outside this repo | research | maestro-explore (research mode) |
| "Does this state model feel right?" or "What should it look like?" | prototype | maestro-explore (prototype mode) |
| Fuzzy terminology, or a hard-to-reverse choice worth recording | model | references/domain-modeling.md |
| The effort exceeds one session and is wrapped in fog, or the user does not know what to do next | wayfind | references/wayfinder.md |
Facts are yours to find; decisions are the user's. Never ask the user for anything you could look up. Modes compose: grill runs with the glossary in hand; wayfind dispatches grill, research, and prototype per child work item. Each design pass must close at least one fork; a pass that closes none surfaces the blocker to the user instead of looping.
Intake
Pin the problem before choosing a method:
For [who], reach [observable outcome] within [boundary], because [impact], without [excluded effect].
Route uncertainty to a lane:
| Current uncertainty | Lane |
|---|---|
| state unknown | scout, no-write |
| several architectures | two or three decision lanes |
| contract clear | delivery |
| candidate needs breaking | challenge |
| hard-to-reverse fork | council |
Weigh the ROI of independent judgment on five questions:
- Would wrong framing be costly?
- Is the decision hard to reverse?
- Is the domain new to the owner?
- Can independent judgment produce a materially different option?
- Is human attention fragmented?
Mostly no: the direct session. Mixed: a Lead plus one peer. Mostly yes: several lanes. Yes on every question including hard to reverse: a council. Before launching any lane, pin the branch and commit, active writers, and dirty paths.
Recall pass first
Before proposing anything, search the store for precedent:
maestro search "<topic keyword>" # hits labeled work/decision/note/bundle
maestro bundle show <id> # deep-read a bundle hit
maestro decision list # locked choices that bind this scope
A past bundle that settled the same fork is evidence; cite it instead of re-deriving the argument.
Working method
- Read the current
maestro work show, linked decisions, notes, and source. - Present ONE unresolved fork at a time with a concrete recommendation.
- Record each settled fork immediately:
maestro decision draft "<choice>" --rationale "<why, with the rejected alternative>" --work <id>thenmaestro decision lock <id>. Supersede an old decision with--supersedes; never rewrite its history. - Keep acceptance, non-goals, and authority visible on the work item.
- Do not edit code during a design-only engagement.
Council
A hard-to-reverse fork with wide blast radius runs the maestro-council
protocol: neutral brief, sealed seats, one premise verifier on unanimity,
bounded verifiers, one cross-examination round, an audit by tier, and one
binding verdict recorded with maestro decision draft --rationale carrying
the dissent. The candidate under review stays frozen; a new finding creates
a new candidate.
Readiness gate and exit
Count the material forks still open before writing anything down. More than two open forks: keep grilling (or route the unknown by the mode table); too foggy to state even the problem: wayfind. Forks the conversation already settled are synthesized, never re-asked. An external claim entering a decision (API behavior, library semantics, versions) comes from research against primary sources, never from memory.
Then exit by tier (maestro-bundle tier rule):
- Light: design ends with a work item whose acceptance fits in one sentence,
maestro work add "<title>" --acceptance "<observable result>", plus the locked decisions. No SPEC, no red-test list; the work is verified inline bymaestro-work. A quickfix never reaches design. - Full:
maestro bundle open <id> --work <workId>, opened in the store whose checkout will change (a walk run in the Hub room still opens its bundle where the code lives; note the bundle on the Hub map and the map on the bundle's work item), then fill SPEC.md as a pure contract: Problem, Solution, Scope, Anti-goals (each traces to a real risk in this repo and gets a matching VERIFY.md check; an anti-goal that cannot be checked is a wish, not a constraint), Decisions (ids only, Hub decisions ashub:<id>;maestro bundle show <id>renders them), and Red tests: one failing test at an accepted seam per risk the SPEC names, nothing beyond that list. Work with no executable seam (docs, config) or behavior-preserving work (upgrades, refactors) lists VERIFY.md scenarios, a readback, diff, or captured baseline, not tests. Draft the VERIFY.md rows from the red list and anti-goals; seed NOTES.md with Current State, Next Action, andBase:.
If the contract would need guessing to write a red test or an acceptance sentence, the fork is not settled: return to the walk. Finish with the next fork, an explicit implementation gate, or a named blocker. A SPEC authorizes nothing; implementation starts only on the user's explicit request.
For unattended/away-mode design constraints, read references/unattended.md.