From 3fa0242f564b30faae1a653f15d26a4ebfb34af2 Mon Sep 17 00:00:00 2001 From: Frank Date: Sun, 18 Oct 2026 19:15:14 -0700 Subject: [PATCH] style(grilling): rewrite in the mattpocock corpus voice (Refs #20) Read all 36 upstream skills, then rewrote to their house style per writing-for-agents' own levers: leading words as tokens (frontier, brief, ledger, artefact, scout), vocabulary-first and used exactly, positive phrasing with prohibitions kept only as hard guardrails, completion criteria sharpened to checkable+exhaustive ('counted before sending', 'frontier empty and nothing sits blocked'), zero history, gotchas the environment cannot confess kept inline. All settled behaviour from the grilling-on-grilling session survives intact. --- agent/skills/grilling/SKILL.md | 48 ++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 20 deletions(-) diff --git a/agent/skills/grilling/SKILL.md b/agent/skills/grilling/SKILL.md index e901c22..ce7d4cd 100644 --- a/agent/skills/grilling/SKILL.md +++ b/agent/skills/grilling/SKILL.md @@ -3,36 +3,44 @@ name: grilling description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases. --- -Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it. +# Grilling -Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled. A question whose answer depends on an unsettled fact or another open question belongs to a _later_ round, not this one. Ask the whole frontier in one round, then wait. +Interview the user relentlessly until nothing is silently assumed. The subject is a **design tree**: every decision branches into the decisions that hang off it. -## The round: `ask` is the default vehicle +A decision is **frontier** when it can be asked now, without an answer you haven't heard yet. The interview is done when the frontier is empty: every branch of the tree visited. -Per-question discipline: +## Rounds -- One question decides exactly **one artefact**. Name it before sending; two names → split. A round may carry many single-artefact questions; a question may not. -- Shared plumbing is not grounds for merging: two products sharing an endpoint, service, or build step are still two questions. -- Ideas are **heavily encouraged** - the interviewer's own idea gets its own atomic question like any other. What is banned is smuggling an unasked-for artefact into another question's option text ("...and also X" in a label or preview). -- Option wording derives from the user's stated goal, never from your scaffolding (todo text, table rows, runbook headings). -- `multi: true` for pick-many; `preview` for code/config evidence (renders as markdown); `header` for the branch chip. +Work the tree in **rounds**: ask the whole frontier at once, then wait. A decision whose answer hangs on an open question or an unfetched fact joins a later round. -Fallback: a harness without `ask` degrades to the classic text round - `❓ **Q1** - **title**: body` / `➡️ recommendation`, worded so a bare "yes" accepts every recommendation. +Ask each closed decision - anything expressible as 2–5 options - through the `ask` tool: -Dialog mechanics you must respect: `ask` is exclusive - spawn scouts **before** the `ask` call in the same message or they stall behind the dialog. The dialog cannot be interrupted by arriving facts; results land between rounds. Esc **aborts the whole run** with no post-cancel turn - the durable ledger is the safety net. Questions are spoken aloud when speech is enabled. +- **One artefact per question**, counted before sending. Name the artefact each question decides; two names means two questions. Shared plumbing (an endpoint, a service, a build step) still leaves two artefacts. +- Recommended answer first, marked `recommended: 0`: the user's single Enter accepts it. +- Options quote the user's goal. Their words, their stated goal, ground the wording; your todo text and table rows stay out of it. +- Your own idea is welcome: it gets its own recommended question. Attach it to its own question, so it rides there on its merits. +- `multi: true` for pick-many, `header` for the branch chip, `preview` when the decision needs code or config in front of the user. -## The ledger: `todo` is the tree, `local://` is the save-file +Open narrative - "walk me through the deploy flow" - has no options to offer; ask it as prose in chat. Without an `ask` tool the whole round degrades to text: `❓ **Q1 — title**: body`, then `➡️ recommendation`, phrased so one bare "yes" accepts every recommendation. -- `todo`: **phase = design-tree branch**, task text = the decision (`" - via: "` carries the edge; todo has no edges). `pending` = frontier, `block` with a one-line reason = waiting on a fact or an open decision (the HUD stays visible while anything is blocked), `done` = settled. `unblock` the moment its prerequisite settles. -- `write local://grilling-state.md` at the end of **every round**: the tree with each decision's verdict + one-line rationale. This is the only thing that survives an Esc-abort - keep it current. +Dialog mechanics, the gotchas no doc confesses: the dialog is exclusive, so dispatch scouts before the `ask` call in the same message and expect their results between rounds. Esc cancels the whole run with no closing turn; the ledger below is what survives it. -## Facts are yours; decisions are the user's +## The ledger -- Environment facts (filesystem, repo, live config): `task` + `scout`, one batch, one scout per fact-cluster; concurrency is capped, so cluster rather than spray. -- Outside-world facts: call `web_search` directly - no spawn hop. +The tree lives in the `todo` list while the interview runs, so the user watches it fall: + +- One task per decision, filed under the phase for its branch; `via: ` in the task text carries the edge. +- `pending` is the frontier; `block` with a one-line reason waits on a fact or an open decision; `done` is settled. Unblock the moment the dependency settles. + +Write `local://grilling-state.md` at the end of every round: the tree, each decision's verdict and one-line rationale. It is the durable copy of the interview; keep it current so an Esc costs one round. + +## Facts are yours, decisions are theirs + +- Environment facts (filesystem, repo, live config): dispatch a **scout** per fact-cluster, batched into one `task` call, before the round's `ask`. Cluster tightly; spawns are the expensive route. +- Outside-world facts: call `web_search` directly. - Cheap lookups: `read`/`grep` inline. -- Only the main session may ask; every spawn carries the exact facts to return. +- The main session is where questions happen: every spawn carries the exact facts to return, and comes back into the next round. -## Completion +## Done -Frontier empty and nothing blocked → write the settled-decisions summary from the ledger, then **one closing `ask`**: "Shared understanding reached - proceed?" Nothing executes before that yes. After it: distill the settled decisions into the project's knowledge base, or a log markdown file, and refresh the ledger file to final form. +The frontier is empty and nothing sits blocked. Distil the ledger into a **brief**: one line per decision, verdict plus rationale, grouped by branch. Put it in chat, then one closing `ask`: "Proceed on this brief?" Nothing executes before that yes. After it, fold the brief into the project's knowledge base, or a log markdown file, wherever the project keeps its decisions.