grilling

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

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.

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 whole frontier in one round, then wait for the user's answers before the next round.

## Ask through the harness question UI

Put the round's questions to the user through the harness's structured question interface, so they answer by picking options instead of typing a prose reply. When the harness exposes a question tool, do not post the frontier as a numbered list in the chat and wait for text.

The control has a different name in each harness:

| Harness | Tool | Shape |
| --- | --- | --- |
| Claude Code | `AskUserQuestion` | up to 4 questions per call, 2 to 4 options each, header ≤ 12 chars, optional multi-select; an "Other" free-text choice is always added |
| OpenCode | `question` | a list of questions, each with a header, the question text, and options; the user moves between them and can type a custom answer |
| Codex CLI | `request_user_input` | option-based question prompt (Plan mode) |
| Gemini CLI | `ask_user` | one or more questions, from yes/no to multiple choice to open-ended |
| Cursor CLI | `AskQuestion` | question with selectable options |

Use whichever one the current harness exposes. Check your tool list for the right name before giving up on it.

Build each question like this:

| Field | What goes in it |
| --- | --- |
| `header` | One to four words naming the decision, short enough for the harness limit (12 characters on Claude Code). |
| `question` | The decision and the trade-offs that make the options meaningful. Put longer context in the message that carries the call. |
| `options` | The real branches, two to four of them, each with a one-line description of what choosing it commits to. List your recommended answer first and mark it `(Recommended)`. |
| `multi-select` | Only when more than one branch can hold at the same time. |

If the harness limits how many questions one call takes (Claude Code allows four), split the round across several calls. Collect the answers to the whole round before asking the next.

If the harness has no question tool, or the user turned it off, fall back to prose: number each question and state your recommended answer under it.

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. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't 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.

The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.

## Capture domain docs at the close (repo sessions only)

Run this only after the frontier is empty, and only after the user confirms shared understanding. Skip it when there is no project working directory, or when the session was only a thought exercise with nothing to persist. Do not write domain files before that confirmation.

Follow `docs/agents/domain.md` for glossary vocabulary and ADR criteria.

1. Read `docs/agents/domain.md` when present. If the repo already keeps a teach-style glossary (for example `## Terms` from the teach skill), leave that file alone and use a product `GLOSSARY.md` path from `docs/agents/domain.md` instead of overwriting teach vocabulary.
2. Write settled project-specific terms into the glossary path domain.md names. Create the file lazily. If `GLOSSARY-MAP.md` exists and does not resolve a path, fall back to root `GLOSSARY.md` and say so.
3. For each decision that qualifies as an ADR under domain.md, ask through the harness question UI whether to write it, with options such as Write ADR (Recommended), Skip, and Edit (Other). Draft the short form from domain.md in the question context. Create `docs/adr/` lazily when the first Write is chosen. Most sessions produce zero ADRs; that is fine. Do not open a free-form chat interview for this step when the question UI is available.
4. Report what you wrote or that nothing qualified. Then you may act on the plan. Hand the same conversation to `to-spec` when the next step is a spec. When you also persist grilling notes under `.scratch/`, write them on the repository's **primary worktree** (same rule as the issue tracker in `docs/agents/issue-tracker.md`), not only inside a disposable agent checkout.

From pedrosatin/skills, MIT.

More from pedrosatin/skills