# Domain modeling

Actively build and sharpen the project's domain model as you design: challenge
terms, invent edge-case scenarios, and record the glossary and decisions the
moment they crystallise. Merely reading the glossary for vocabulary is a
one-line habit any skill can do; this reference is for when you are changing
the model, not just consuming it.

## Where it lives

Both artifacts live in the maestro store, so they sit in the recall path every
session already reads:

```
maestro term add <name> "<definition>" [--work <id>]   # record or redefine a term
maestro term list | maestro term show <name>            # the glossary
maestro decision draft "<choice>" --rationale "<why + rejected alternative>" --work <id>
maestro decision lock <id>                              # the recorded decision
maestro search "<word>"                                 # terms, decisions, work, bundles
```

There is no glossary file to create; the first `term add` is the glossary.

## During the session

### Challenge against the glossary

When the user uses a term that conflicts with an existing definition, call it
out immediately. "The glossary defines 'cancellation' as X, but you seem to
mean Y. Which is it?"

### Sharpen fuzzy language

When the user uses vague or overloaded terms, propose a precise canonical
term. "You are saying 'account'. Do you mean the Customer or the User? Those
are different things."

### Discuss concrete scenarios

When domain relationships are being discussed, stress-test them with specific
scenarios. Invent scenarios that probe edge cases and force the user to be
precise about the boundaries between concepts.

### Cross-reference with code

When the user states how something works, check whether the code agrees. If
you find a contradiction, surface it: "The code cancels entire Orders, but you
just said partial cancellation is possible. Which is right?"

### Record terms inline

When a term is resolved, `maestro term add` right there. Do not batch these
up; capture them as they happen. A definition is domain language only: no
implementation details, no file paths, no decisions. Redefining a term is a
new `term add` with the same name; say why in the conversation.

### Lock decisions sparingly

Apply [Decisions and readiness](~/maestro/WORKFLOW.md#decisions-and-readiness)
to distinguish a durable domain choice from a reversible implementation detail.
Do not create a decision record for every answer or fact found during modeling.

The rationale carries the rejected alternative and the why; a later reversal
is a new decision with `--supersedes <id>`, never an edit.

# Grilling

Apply [Decisions and readiness](~/maestro/WORKFLOW.md#decisions-and-readiness).
Interview on material user-owned choices blocking the next slice, not routine
implementation details. Map their dependencies as a **design tree**.

Work the tree in **rounds**. The **frontier** is every decision whose
prerequisites are already settled — the questions you can ask _now_ without
guessing at answers you haven't heard yet. Ask the frontier in plain prose,
one decision at a time when the forks are heavy, or as a short numbered list
when they are independent and light. Then wait for the user's answers before
the next round.

For each question:

- Lead with **what this does** — the consequence of the decision in this
  repo, before any option list.
- Present the options as prose, each with its concrete trade-off. When a
  layout or structure is easier to see than to describe, include a small
  ASCII sketch per option.
- End with a `my rec:` line — your recommended answer and the one-line why.
- No emoji, no batching questions that depend on each other's answers. When
  the harness offers a question card, use it: one decision per card, "what
  this does" first, the sketch per option, the `my rec:` line on every fork.
- Record durable decisions under the shared workflow's threshold:
  `maestro decision draft "<choice>" --rationale "<why + rejected alternative>" --work <id>`
  then `maestro decision lock <id>`. An answer to a fork is
  never an implementation order, even when the chosen option is
  itself an artifact (a script, a schema, a prototype); building starts only
  on an explicit request.

Each round the user answers reshapes the tree — settled decisions push the
frontier outward and unblock questions that depended on them. Recompute the
frontier and ask the next round. A question whose answer depends on another
question still open in this round belongs to a _later_ round, not this one.

Finding _facts_ is your job, never the user's. Investigate directly; delegate
only when independent work or context isolation warrants it. Do not ask the
user for anything you could look up yourself.
Don't block on it: a running exploration is an unsettled prerequisite, so
only the questions downstream of it wait for the sub-agent to report — ask
the rest of the frontier now. The _decisions_ are the user's — put each to
them and wait.

Finish when the next slice meets the shared readiness rule. Record deferred
questions; they need not all be settled now. Continue only within verified
implementation authority. A design-only request stops at the design result.

# Unattended

Use this recipe when an external driver is authorized to keep advancing local
accepted work while the user is away. Maestro records state; it does not own a
hidden scheduler or a second lifecycle.

## Loop anatomy

### Perceive

Reconstruct state from `maestro status`, `maestro ready`, `maestro work show`, decisions, and handbacks.
Do not rely on conversational memory.

### Choose

Select exactly one ready item whose authority and acceptance are already
settled. If none is safe, return dry or blocked instead of inventing work.

### Act

Use `maestro recipe show work` to drive that one item. Stay within local reversible
actions unless the unattended grant explicitly covers a named external action.

### Observe

Verify the item through its real consumer path and record completion evidence.
Stop on approval prompts, secrets, destructive git, or exhausted failure
budget.

### Learn

Record only sourced corrections that will help a later session resume safely.

### Continue

The external driver may select the next ready item after the current unit is
verified. Return one of: next item, dry, blocked, or hard stop.

# Wayfinding

A loose idea has arrived: too big for one agent session, and wrapped in fog.
The way from here to the **destination** is not visible yet. Wayfinding finds
that way instead of charging at the destination. It charts the way as a
**map** in the maestro store, then works its **decision tickets** (questions
whose resolution is a decision, not slices of a build to execute) one at a
time until the route is clear.

The destination varies per effort, and naming it is the first act of
charting. It might be a SPEC to hand off, a decision to lock before planning
starts, or a change made in place like a data-structure migration.

## Plan, don't do

Wayfinding is **planning** by default: each ticket resolves a decision, and
the map is done when nothing is left to decide before someone goes and does
the thing. The pull to just do the work is usually the signal you have reached
the edge of the map and it is time to hand off. Absent an explicit override
in the map's notes, produce decisions, not deliverables.

## The map in maestro terms

| Wayfinding | maestro |
|---|---|
| the map | a parent work item, `maestro work add "<destination>" --kind idea --acceptance "<what reaching the end looks like>"` |
| a ticket | a child, `maestro work add "<question>" --parent <mapId> --kind research\|idea\|task` |
| blocking | `--blocked-by <ticketId>` on the child (repeatable), or `maestro work block <ticketId> --by <ticketId>` once both exist |
| the frontier | `maestro ready`: open, unblocked children |
| claim | `maestro work start <ticketId>`; the lease is the claim |
| resolve | `maestro decision draft ... --work <ticketId>`, `decision lock`, then `maestro work done <ticketId> --claim "<answer>" --proof "<evidence>"` |
| decisions so far | `maestro work show <mapId>` lists the closed children; `maestro bundle show` renders their decisions |
| not yet specified | `maestro work note <mapId> "fog: <suspected question>"` |
| out of scope | `maestro work cancel <ticketId> --reason "beyond the destination: <why>"` |

Refer to tickets by their title in everything the human reads; ids ride
inside, they never stand in for a name.

## Ticket types

Every ticket is either **HITL** (worked with a human who speaks for
themselves) or **AFK** (driven by the agent alone). A HITL ticket only
resolves through that live exchange; the agent never stands in for the
human's side of it.

- **research** (AFK): a fact outside the working directory that a decision
  waits on. Resolved by `maestro-explore` in research mode.
- **prototype** (HITL): raise the fidelity of the discussion with a cheap,
  concrete artifact to react to, via `maestro-explore` prototype mode; link
  the artifact from the ticket's note.
- **grilling** (HITL): conversation. The default case; always with
  [grilling.md](grilling.md) and [domain-modeling.md](domain-modeling.md).
- **task** (HITL or AFK): manual work that must happen before a decision can
  be made (signing up for a service, provisioning access, moving data so its
  shape can be seen). The one type that does rather than decides; it earns
  its place by unblocking a decision. The answer records what was done and
  the facts later tickets depend on.

## Fog of war

The map is deliberately incomplete: do not chart what you cannot yet see. The
test between fog and ticket is whether you can state the question precisely
now, not whether you can answer it now. Ticket when the question is sharp,
even if blocked; fog note when you cannot phrase it that sharply. A fog note
names the tool result or store id it rests on, or carries the word
`unverified`; a note written from summarized memory has survived whole maps
after the fact it described had already changed. Before a fog note graduates
into a ticket or is restated in a later note, re-check it against the store or
the repository. Resolving a ticket clears the fog ahead of it; graduate
whatever is now specifiable into fresh tickets and append a note
`fog cleared by <id>: <what replaced it>`. Work notes are append-only, so the
latest note wins; nothing is removed.

Work beyond the destination is out of scope, not fog: cancel it with the
reason and leave it out of the decisions list. It returns only if the
destination is redrawn, and then as a fresh effort.

## Invocation

Unattended, resolve at most one ticket per session (research tickets
excepted): the rule keeps an AFK agent from deciding a whole map alone.
With the owner present, continue on the owner's word and stop only at fog,
a research ticket, or the end of the frontier.

### Chart the map

1. **Name the destination.** Grill with the domain model in hand until the
   destination is one or two sentences; it becomes the parent's acceptance.
   When the owner brings an example, ask whether the example is the
   destination or one instance of it; when the owner names a reference tool,
   read how that tool answers the question before presenting options.
2. **Map the frontier.** Grill again, breadth-first: fan out across the whole
   space, surfacing the open decisions and the first steps takeable now. If
   this surfaces no fog and the whole journey fits one session, you do not
   need a map: stop and ask the user how they would like to proceed.
3. **Create the parent**, then the tickets you can specify now as children;
   wire the edges with `maestro work block` once the ids exist. Fog goes into
   parent notes.
4. **Fire the research agents** for each research ticket, in parallel.
5. Stop. Charting is one session's work; it resolves nothing by hand.

### Work through the map

1. `maestro work show <mapId>` for the low-resolution view, then
   `maestro ready` for the frontier.
2. Choose the ticket: the one the user named, else the first frontier ticket.
   `maestro work start` it before any work.
3. Resolve it, zooming into related or closed tickets on demand.
4. Record the resolution as a locked decision and close the ticket with the
   answer as its claim.
5. Add newly surfaced tickets, graduate fog, cancel anything the answer shows
   sits beyond the destination, and update tickets the decision invalidates.

Other sessions may be working unblocked tickets in parallel; the lease on a
ticket is what keeps two sessions off the same question.