From 14b92236ddccf7d683232eceac6e9063ebc55ae2 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 29 Jul 2026 12:37:09 +0100 Subject: [PATCH] docs: describe grilling as round-by-round everywhere The round-by-round rework left the wrappers and callers still promising a one-question-at-a-time interview. Sync grill-me, grill-with-docs and triage (docs + skill step), plus grilling's Codex short_description and the loop-me draft. Co-Authored-By: Claude Opus 5 --- .changeset/grilling-rounds-docs-sync.md | 5 +++++ docs/engineering/grill-with-docs.md | 6 +++--- docs/engineering/triage.md | 2 +- docs/productivity/grill-me.md | 4 ++-- skills/engineering/triage/SKILL.md | 2 +- skills/in-progress/loop-me/SKILL.md | 2 +- skills/productivity/grilling/agents/openai.yaml | 2 +- 7 files changed, 14 insertions(+), 9 deletions(-) create mode 100644 .changeset/grilling-rounds-docs-sync.md diff --git a/.changeset/grilling-rounds-docs-sync.md b/.changeset/grilling-rounds-docs-sync.md new file mode 100644 index 0000000..c914fa5 --- /dev/null +++ b/.changeset/grilling-rounds-docs-sync.md @@ -0,0 +1,5 @@ +--- +"mattpocock-skills": patch +--- + +Sync the skills and docs that still described grilling as a **one-question-at-a-time** interview. Since the round-by-round rework, `grill-me`, `grill-with-docs` and `triage` all run the frontier a round at a time — their pages, `triage`'s grill step and `grilling`'s Codex `short_description` now say so. The opt-out for the old rhythm (a line in your global `CLAUDE.md`) is unchanged. diff --git a/docs/engineering/grill-with-docs.md b/docs/engineering/grill-with-docs.md index 7338f1f..b7cfd75 100644 --- a/docs/engineering/grill-with-docs.md +++ b/docs/engineering/grill-with-docs.md @@ -12,7 +12,7 @@ npx skills update grill-with-docs ## What it does -`grill-with-docs` interviews you relentlessly about a plan or design, one question at a time, until you and the agent reach a shared understanding — and it writes the vocabulary and decisions down as you go. +`grill-with-docs` interviews you relentlessly about a plan or design, a round of questions at a time, until you and the agent reach a shared understanding — and it writes the vocabulary and decisions down as you go. The grilling **leaves a paper trail**. A plain interview sharpens your thinking and then evaporates when the session ends; this one captures each term the moment it's resolved into a `CONTEXT.md` glossary, and records the hard, one-way decisions as ADRs. The alignment survives the conversation instead of living only in your head. @@ -28,13 +28,13 @@ This skill is stateful — it writes into your repo as it grills. Resolved terms ## The grill -The engine is a **grill**: a relentless, one-question-at-a-time walk down the decision tree, resolving dependencies between decisions before moving on, with a recommended answer offered for every question. Questions the codebase can answer are answered by reading the codebase, not by asking you. +The engine is a **grill**: a relentless, round-by-round walk down the decision tree. Each round asks the whole **frontier** — every decision whose prerequisites are already settled — and waits, so dependencies between decisions are resolved before the questions that hang off them are asked, with a recommended answer offered for every question. Questions the codebase can answer are answered by reading the codebase, not by asking you. What makes this variant its own skill is where the answers go. As the grill runs, fuzzy language gets sharpened into canonical terms and written to the glossary inline — not batched at the end. The glossary stays a glossary: pure vocabulary, no implementation details, no spec. ADRs are offered sparingly, only when a decision is hard to reverse, surprising without context, and the result of a real trade-off. Most sessions produce a sharper glossary and few or no ADRs, and that's the intended shape. ## It's working if -- It asks one question at a time and waits, rather than dumping a questionnaire. +- It asks a round of independent questions and waits, rather than dumping the whole questionnaire at you. - Terms get written to `CONTEXT.md` the moment they resolve, in your project's own words. - It reaches into the codebase to answer its own questions where it can. - ADRs stay rare — you're not asked to rubber-stamp reversible choices. diff --git a/docs/engineering/triage.md b/docs/engineering/triage.md index 00673b5..5ef6dfa 100644 --- a/docs/engineering/triage.md +++ b/docs/engineering/triage.md @@ -43,4 +43,4 @@ The step that separates `triage` from ad-hoc labelling is verification. It repro ## Where it fits -`triage` is the **periodic maintenance** pass over your issue tracker — run it whenever reports pile up, to keep the queue sorted and the `ready-for-agent` column trustworthy. It sits at the front of the tracker, upstream of the build chain: the briefs it writes are what [tdd](https://aihero.dev/skills-tdd) later picks up to implement. When a request needs sharpening it leans on [grilling](https://aihero.dev/skills-grilling) and [domain-modeling](https://aihero.dev/skills-domain-modeling) to grill it into shape one question at a time. Its close neighbour is [to-spec](https://aihero.dev/skills-to-spec), which populates the tracker from a fresh conversation where `triage` processes what's already there. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. +`triage` is the **periodic maintenance** pass over your issue tracker — run it whenever reports pile up, to keep the queue sorted and the `ready-for-agent` column trustworthy. It sits at the front of the tracker, upstream of the build chain: the briefs it writes are what [tdd](https://aihero.dev/skills-tdd) later picks up to implement. When a request needs sharpening it leans on [grilling](https://aihero.dev/skills-grilling) and [domain-modeling](https://aihero.dev/skills-domain-modeling) to grill it into shape a round of questions at a time. Its close neighbour is [to-spec](https://aihero.dev/skills-to-spec), which populates the tracker from a fresh conversation where `triage` processes what's already there. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/productivity/grill-me.md b/docs/productivity/grill-me.md index 4a64cfa..abe214c 100644 --- a/docs/productivity/grill-me.md +++ b/docs/productivity/grill-me.md @@ -14,7 +14,7 @@ npx skills update grill-me `grill-me` runs a relentless interview about a plan or design, walking every branch of the decision tree until you and the agent reach a **shared understanding**. -It asks **one question at a time** and waits. It never dumps a batch of questions at you — that is bewildering — and where a question can be answered by reading the codebase, it goes and reads rather than asking. Each question comes with the agent's own recommended answer, so you are reacting to a proposal, not staring at a blank prompt. +It asks in **rounds** and waits. A round is the whole **frontier** — every decision whose prerequisites are already settled — put to you as one numbered list, so you're never asked something that hinges on an answer the agent hasn't heard yet. Where a question can be answered by reading the codebase, it goes and reads rather than asking. Each question comes with the agent's own recommended answer, so you are reacting to a proposal, not staring at a blank prompt. ## When to reach for it @@ -24,7 +24,7 @@ Reach for it before you build, when a plan feels roughly right but you can sense ## The decision tree -The session walks the plan as a tree of decisions, resolving dependencies between them one by one — a parent decision settled before the choices that hang off it. The point is not to reach agreement quickly; it is to make every implicit call explicit, so nothing important is left silently assumed. You come out the other side with a plan whose branches have all been visited. +The session walks the plan as a tree of decisions, settling a parent decision before the choices that hang off it. Your answers reshape the tree and push the frontier outward, so the next round asks whatever they unblocked. The point is not to reach agreement quickly; it is to make every implicit call explicit, so nothing important is left silently assumed. You come out the other side with a plan whose branches have all been visited. `grill-me` is **stateless**: it writes nothing and leaves no workspace behind. It runs anywhere, and the only artifact is the sharpened understanding in the conversation itself. That is the deliberate contrast with [grill-with-docs](https://aihero.dev/skills-grill-with-docs), which captures the same interview as durable ADRs and a glossary. diff --git a/skills/engineering/triage/SKILL.md b/skills/engineering/triage/SKILL.md index be47b78..e67b7bb 100644 --- a/skills/engineering/triage/SKILL.md +++ b/skills/engineering/triage/SKILL.md @@ -73,7 +73,7 @@ Show counts and a one-line summary per item. Let the maintainer pick. 3. **Verify the claim.** Before any grilling, check that the claim holds up. For a bug, reproduce it from the reporter's steps. For a PR, confirm the diff does what it claims — check it out, run the relevant tests or commands. Report what happened: confirmed (with code path), failed, or insufficient detail (a strong `needs-info` signal). A confirmed verification makes a much stronger agent brief. -4. **Grill (if needed).** If the request needs fleshing out, run the `/grilling` and `/domain-modeling` skills together — grill it into shape one question at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land. +4. **Grill (if needed).** If the request needs fleshing out, run the `/grilling` and `/domain-modeling` skills together — grill it into shape a round of questions at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land. 5. **Apply the outcome:** - `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)). diff --git a/skills/in-progress/loop-me/SKILL.md b/skills/in-progress/loop-me/SKILL.md index 3a8c52c..c408efa 100644 --- a/skills/in-progress/loop-me/SKILL.md +++ b/skills/in-progress/loop-me/SKILL.md @@ -5,7 +5,7 @@ disable-model-invocation: true argument-hint: "A workflow to design, or nothing to go find one" --- -Run a stateful `/grilling` session whose only output is **workflow** specs. Use the grilling discipline — relentless, one question at a time, a recommended answer attached to each — aimed at the vocabulary and goal below. Create, edit, and delete specs as the grilling resolves things. +Run a stateful `/grilling` session whose only output is **workflow** specs. Use the grilling discipline — relentless, a round of questions at a time, a recommended answer attached to each — aimed at the vocabulary and goal below. Create, edit, and delete specs as the grilling resolves things. ## The loop lens diff --git a/skills/productivity/grilling/agents/openai.yaml b/skills/productivity/grilling/agents/openai.yaml index 85b1260..ddbdb96 100644 --- a/skills/productivity/grilling/agents/openai.yaml +++ b/skills/productivity/grilling/agents/openai.yaml @@ -1,3 +1,3 @@ interface: display_name: "Grilling" - short_description: "Stress-test thinking one question at a time" + short_description: "Stress-test thinking a round of questions at a time"