grill-master

# 🔥 grill-master An effort too big for one session fails a specific way: the outcome drifts from the intent, one unshared assumption at a time. grill-master prevents that drift by designing the workflow as it runs: a loose idea becomes a **working brief** — the operator's intent made checkable — and sessions work it one step at a time until the finish line holds. **The workflow unfolds.** A normal workflow is drawn before it runs; this one is discovered. The unfolding rule governs every session: take one step, then re-read the brief as a whole and record what the step changed. Each step is structure-preserving (Alexander) — there is no territory to discover, only a whole to strengthen, one step at a time. All file formats, claim rules, and the ready scan live in [CONVENTIONS.md](CONVENTIONS.md) — follow it exactly whenever you create or edit brief, step, or asset files. ## Decide, don't implement Each step defaults to resolving a decision; the brief is done when someone could build the thing without another decision — and maintain it without archaeology. The pull to just do the work is the signal you've reached the brief's edge — record the decision and hand off. Execution may be authorized in the brief's **Notes** or the current user request. Record live authorization while proceeding; a planning-only request remains decision work. ## Refer by name In everything the human reads, call briefs and steps by their titles with the file linked — a wall of slugs is illegible. ## The brief One directory per effort: `.brain/projects/<effort>/` — the brief file, one file per step, any assets. The brief is an **index**, not a store: each resolution lives in its step file. Its sections: - **Finish line** — the explicit, observable conditions that end the effort, including how the result stays maintained after it. Named first, at charter: it fixes scope, so it shapes every step. - **Vocabulary** — the terms this effort has settled, one line each: the effort's pattern language. A record of negotiations, not a glossary — words don't carry meaning by themselves, and drift is exactly that assumption failing — so each line is a settlement between operator and agent. A term used two ways silently forks the work; any session that catches drift re-negotiates the term on the spot and lands the settled meaning before closing. - **Notes** — domain, skills every session should consult, standing calls made mid-effort (attributed, dated), execution authorization if granted. - **Decision ledger** — one line per closed step: name-link plus gist. Closed is not solved forever: when reality reopens a settled decision, charter a new step naming what it supersedes — the old resolution never gets edited, and the reappearance is natural, not failure. - **Latent** — unknowns already in the whole but too soft to phrase as steps: the effort's latent structure. The test: can you state the step precisely now, even if you can't take it yet? Sharp → its own step file (blocked is fine). Soft → one line here, graduating when a result develops it. - **Out of scope** — work ruled past the finish line. It never graduates; it returns only if the finish line is redrawn, as a fresh effort. When an existing step turns out to sit past the finish line, close it and leave one line here saying why, linking it. Open steps are **not** listed in the brief; the scan finds what's ready (defined in CONVENTIONS.md). ## Steps A step is one session-sized unit of the workflow — a decision, an investigation, or authorized build work — in its own file. Four kinds: - **research** (AFK) — a fact outside the working tree that a decision waits on. Produces a linked asset. - **prototype** (HITL) — the strongest alignment instrument: a cheap, concrete artifact the operator can touch, via the `prototype` skill — prose agreement is cheap, and a touchable thing surfaces the misunderstandings prose hides. - **grilling** (HITL, the default) — a live decision conversation via `grill-me` (add `grill-with-docs` when the effort should accrete ADRs), one question at a time, recommendation first. The heat is on the decision, never the human: a grilling is two parties negotiating toward a shared vision, not an interrogation of the operator. Stress-test decisions with concrete scenarios, including who maintains the result and how it fails over time. - **task** (either) — execution the brief's Notes or current user request authorize, or groundwork a decision waits on: provisioning, access, moving data so its shape can be seen. States its done-condition up front ("Resolved when …") and records what was done plus the facts later steps depend on. HITL means the human speaks for themselves; the session that answers its own grilling has broken the step — reopen it. **Claim before any work**: stamp yourself as `assignee` per CONVENTIONS.md, which also governs staleness and takeover. After each step, update and re-read the brief. Continue ready authorized steps in this session; start another worker only for useful independent work. ## Charter a brief The user brings a loose idea — or a handoff, transcript, or artifact to plan from. 1. **Pin the finish line** with `grill-me`. Look up facts yourself; put only decisions to the human. Terms settle as the finish line does — seed the Vocabulary with them. Done when the human confirms finish-line conditions they could test an outcome against. 2. **Fan out breadth-first** — grill across the whole space, not deep on any thread, surfacing decisions, build phases, and soft unknowns. Charter the earliest touchable prototype the space allows — a reaction beats a discussion. If everything fits in this one session, skip the brief and say so. Done when the human has nothing more to add at this altitude. 3. **Create the effort** per CONVENTIONS.md: brief, one file per step you can state precisely, blockers wired in a second pass. Done when the scan returns exactly the ready set you expect. 4. **Fire workers at the ready research steps** — one worker per step, each claiming before work: herdr pi panes (per `herdr-orchestration`) when herdr is available, Agent subagents otherwise, task file per CONVENTIONS.md. Done when every ready research step is claimed and running. 5. **Commit, push, stop.** The charter session takes no steps itself; report the brief by name with its ready steps. ## Work a brief The user names a brief, or a brief plus a step. 1. **Read the brief** — the index only; open step files as needed. The Vocabulary binds this session: use its terms, challenge what's drifted. 2. **Choose the step**: the one the user named, else the first ready step from the scan. **Claim it** before any work. 3. **Resolve it by kind**, zooming into related closed steps on demand. 4. **Record it**: result section in the step file, status closed, one ledger line on the brief. 5. **Unfold**: re-read the whole brief against the result. Graduate sharpened unknowns into step files; close steps the result invalidated (out-of-scope line if they sit past the finish line); land settled terms in the Vocabulary; append mid-effort calls to Notes. Done when the brief reads true end to end — then commit and push. ## Register A metaphor highlights and hides (Lakoff): explorer talk hid that the workflow is made by deciding, and cook talk would bury the thinking under garnish. So the working words are literal workflow words — step, ready, blocked, claim, finish line — legible to any agent that has never read this skill, and the flavor budget is three words: sessions **grill**, briefs **unfold**, soft unknowns stay **latent** — the last two from one Alexander domain, an extension, not a new metaphor. Agents enact a metaphor's entailments mechanically — whatever this file's words imply, sessions will do — so the budget is a safety mechanism, not taste. One mark: 🔥 — the skill's title, and a herdr pane running a grill session. It never goes inside the files.