From 7bf54bf57d0f54c11c9d41c6032bae19dab59173 Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Mon, 6 Jul 2026 23:57:12 +0200 Subject: [PATCH 1/4] [#229] feat: add pair-capability-grill interview engine one-question-at-a-time capability, interview|sync modes, write-free. sync mode = systematic story coverage (goal/AC/edge/deps/design/risks) until explicit shared understanding. distributes to .claude/skills; catalog docs + skills-guide updated. --- .claude/skills/pair-capability-grill/SKILL.md | 211 ++++++++++++++++++ .pair/knowledge/skills-guide.md | 15 +- .../docs/contributing/writing-skills.mdx | 4 +- .../docs/reference/skill-management.mdx | 2 +- .../content/docs/reference/skills-catalog.mdx | 10 +- .../dataset/.pair/knowledge/skills-guide.md | 15 +- .../dataset/.skills/capability/grill/SKILL.md | 211 ++++++++++++++++++ 7 files changed, 455 insertions(+), 13 deletions(-) create mode 100644 .claude/skills/pair-capability-grill/SKILL.md create mode 100644 packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md diff --git a/.claude/skills/pair-capability-grill/SKILL.md b/.claude/skills/pair-capability-grill/SKILL.md new file mode 100644 index 00000000..d028b2f2 --- /dev/null +++ b/.claude/skills/pair-capability-grill/SKILL.md @@ -0,0 +1,211 @@ +--- +name: pair-capability-grill +description: "Reusable interview engine: one question at a time, always with a recommendation, exploring KB/codebase before asking. sync mode drives systematic AI-human alignment on every story aspect until explicit shared understanding is confirmed. Write-free by design — returns the synthesis to the caller, never writes adoption or issues. Invocable standalone or composed by /pair-process-brainstorm (phase 1) and /pair-process-refine-story (phase 0)." +version: 0.4.1 +author: Foomakers +--- + +# /pair-capability-grill — Interview Engine + +Ask one question at a time, always with a recommended answer, after exploring the KB/codebase for anything already answerable. `interview` mode explores a free topic; `sync` mode systematically aligns AI and human on every aspect of a story. Never writes — returns the synthesis to the caller. + +## Arguments + +| Argument | Required | Description | +| ---------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `$mode` | No | `interview` (default) or `sync`. | +| `$topic` | No | Freeform subject to explore in `interview` mode. If omitted, the opening question asks for it. | +| `$story` | Conditional| Target story identifier. Required for `sync` mode unless the composing skill already supplies a loaded story via `$context`. | +| `$context` | No | Caller-supplied context bundle (e.g. brainstorm's seed text, refine-story's current story body) so grill skips re-fetching it. | +| `$aspects` | No | Comma-separated subset of the [Sync Coverage Checklist](#sync-coverage-checklist) to focus on (e.g. `risks,dependencies`). `sync` only. If omitted, all six aspects are covered.| + +## Modes + +### Interview Mode (default) + +Freeform exploration of `$topic`. No fixed checklist — the question queue grows from what Step 1's exploration leaves open and from what answers reveal. Used standalone or composed by `/pair-process-brainstorm` phase 1 to produce a raw requirements blob. + +### Sync Mode + +Systematic AI↔human alignment on a specific story, covering all six aspects of the [Sync Coverage Checklist](#sync-coverage-checklist) (goal, AC, edge cases, dependencies, design, risks). Ends only at explicit shared-understanding confirmation. Used standalone (e.g. "sync me on #42") or composed by `/pair-process-refine-story` phase 0. + +## Algorithm + +### Step 0: Detect Mode and Target + +1. **Check**: Is `$mode` provided? +2. **Skip**: If provided, use it. +3. **Act**: Default to `interview` when omitted. +4. **Act**: If `$mode: sync`, resolve the target story: + - Use `$story` if provided. + - Else use a story already loaded by the composing skill via `$context`. + - Else **HALT**: "sync mode needs a target story — provide `$story` or invoke via `/pair-process-refine-story`." +5. **Verify**: Mode is `interview` or `sync`; for `sync`, a target story is resolved. + +### Step 1: Explore Before Asking + +1. **Act**: Before drafting any question, gather what is already knowable: + - `interview`: read the [PRD](../../../.pair/adoption/product/PRD.md), related epics/issues (per [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md)), and grep the codebase for the topic's terms. + - `sync`: read the target story's current body (sections already populated), [architecture.md](../../../.pair/adoption/tech/architecture.md), [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md), [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md), prior decisions in decision-log/adr, and the codebase for the touched components. +2. **Act**: For every fact resolvable this way, mark it **explored** with its source. It is never asked — anything answerable by exploring KB/codebase is explored instead of asked. +3. **Verify**: An explored/unresolved map exists before the first question is asked. + +### Step 2: Build the Question Queue + +1. **Check**: `interview` or `sync`? +2. **Act (interview)**: Decompose `$topic` into the open sub-questions left after Step 1. If `$topic` is omitted, the opening question of the queue is simply "what's the topic?". The queue has no fixed size — it grows as answers reveal new sub-questions. +3. **Act (sync)**: Take the [Sync Coverage Checklist](#sync-coverage-checklist), restricted to `$aspects` if given. Drop any aspect fully resolved in Step 1; queue the remaining aspects in checklist order (already risk-ordered). +4. **Verify**: Queue built — topic-driven (interview) or checklist-driven (sync). + +### Step 3: Ask One Question at a Time + +1. **Act**: Pop the next queue item. Ask exactly one question, always with a recommended answer derived from Step 1's findings, project precedent, or best judgment: + + > [Question]? + > **Recommendation**: [proposed answer] — [why]. + +2. **Act**: Read the human's reply: + - **Accepts the recommendation** → record it as the answer. + - **Gives a different answer** → record that instead. + - **"Don't know"** → the recommendation becomes the **provisional answer**, flagged as an assumption in the synthesis. + - **Raises a new sub-question** → insert it into the queue before continuing. +3. **Verify**: Exactly one answer recorded per question. Never batch multiple questions in a single turn. + +### Step 4: Repeat Until Explicit Shared Understanding + +1. **Check**: Is the queue empty? +2. **Skip**: If not empty, return to Step 3. +3. **Act**: When the queue empties, ask directly: + + > Do we have shared understanding here? (yes / no — anything to add?) + +4. **Verify**: Only an explicit **yes** ends the session. A **no**, or any new concern raised, adds items to the queue and returns to Step 3. The session never auto-exits on an empty queue alone. + +### Step 5: Assemble the Synthesis + +1. **Act**: Compile recorded answers, explored facts (with source), and flagged assumptions: + - `interview` → raw requirements blob (topic, findings per sub-question, open items, assumptions). + - `sync` → alignment synthesis mapped to the six [Sync Coverage Checklist](#sync-coverage-checklist) aspects, ready to drop into the matching [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md) sections. +2. **Verify**: Synthesis accounts for every answered/explored/assumed item — nothing silently dropped. + +### Step 6: Return — Never Write + +1. **Act**: Return the synthesis to the caller (composed invocation) or print it in conversation (standalone). **Never** write to adoption files or PM tool issues in either mode — that stays with the composer (`/pair-process-brainstorm`, `/pair-process-refine-story`) or the human. +2. **Act (standalone, or session interrupted before Step 4's explicit yes)**: Offer an optional handoff file: + + > Save this as a handoff file in `.pair/working/`? (y/n) + + If yes, create `.pair/working/` if it doesn't exist and write `grill---.md` with the synthesis-so-far plus per-aspect/per-topic coverage state (covered / explored / open). +3. **Verify**: No adoption or PM tool write occurred, regardless of mode or handoff. + +## Sync Coverage Checklist + +Ordered by risk of omission. Goal always comes first — it anchors every other aspect, so it precedes the risk ordering; the remaining five follow the same order the story template already uses functional-first, technical-last. + +| # | Aspect | Story Template Section(s) | Explore First | Sample Probe | +| - | ------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | --------------------------------------------------------- | +| 1 | Goal | Story Statement, User Value | PRD, parent epic body | "As a [persona], I want [outcome], so that [benefit] — confirm or adjust?" | +| 2 | AC | Acceptance Criteria → Functional Requirements (Given-When-Then), Business Rules | Story's existing AC draft, similar refined stories | One Given-When-Then scenario at a time | +| 3 | Edge Cases | Edge Cases and Error Handling | Codebase error-handling patterns, existing edge cases on the story | "What happens when [input/dependency] fails?" | +| 4 | Dependencies | Dependencies and Coordination | PM tool backlog graph, epic breakdown | "Does this depend on, or block, another story?" | +| 5 | Design | Technical Analysis → Implementation Approach, Key Components, Integration Points | architecture.md, tech-stack.md, codebase | "Which existing component/pattern implements this?" | +| 6 | Risks | Technical Risks and Mitigation | Story's existing risk table, decision-log/adr precedent | "What's most likely to break or slip here?" | + +Any aspect already covered by Step 1's exploration, or already answered elsewhere in the same conversation, is skipped and marked explored rather than asked — this is the session-length mitigation: the checklist stays fixed, but only genuinely open aspects consume a question. + +## Output Format + +```text +GRILL SESSION COMPLETE: +├── Mode: [interview | sync] +├── Topic/Story: [topic string | #ID: Title] +├── Coverage: [N/6 aspects covered (sync) | topics explored: list (interview)] +├── Assumptions: [list of "don't know" → recommendation-as-assumption items, or none] +├── Explored: [KB/codebase sources consulted instead of asked] +├── Confirmed: [explicit shared understanding: Yes] +└── Handoff: [None | .pair/working/] + +SYNTHESIS: +[the raw requirements blob (interview) or the six-aspect alignment synthesis (sync)] +``` + +## Composition Interface + +When composed by `/pair-process-brainstorm` (phase 1): + +- **Input**: `$mode` omitted (defaults `interview`); `$topic` from the free theme text or the `$root` issue's body; `$context` carries the issue if `$root` was given. +- **Output**: Returns the raw requirements blob (R3.7). `/pair-process-brainstorm` carries it into phase 2 (domain integration) — grill never touches the PM tool or adoption files itself. + +When composed by `/pair-process-refine-story` (phase 0, future extension): + +- **Input**: `$mode: sync`; `$story` is the story being refined; `$context` carries the current (possibly partial) story body so grill doesn't re-fetch it. +- **Output**: Returns the alignment synthesis, pre-mapped to Refined User Story Template sections. `/pair-process-refine-story` merges it into the body it writes via `/pair-capability-write-issue` — grill itself never calls `/pair-capability-write-issue`. + +When invoked **standalone**: + +- No composition context required (decision Q8). `$mode` defaults to `interview`; if `$topic` is also omitted, the opening question asks for it directly. `sync` still requires `$story`. +- Synthesis is printed in conversation. A handoff file in `.pair/working/` is offered, never written silently. + +## Example Transcripts + +### Interview Mode (standalone, free topic) + +```text +> /pair-capability-grill +AI: What's the topic? + Recommendation: none — this is genuinely open, your call. +You: caching strategy for the API layer +AI: [explores codebase: finds no cache layer; checks tech-stack.md: Redis already adopted] + Redis is already in tech-stack.md but unused for caching — reuse it or introduce another store? + Recommendation: reuse Redis — avoids a new dependency. +You: don't know +AI: [records "reuse Redis" as provisional answer, flagged as assumption] + What's the target cache TTL? + Recommendation: 5 minutes — matches the existing session-token TTL in auth config. +You: agreed +AI: Do we have shared understanding here? (yes / no) +You: yes +AI: GRILL SESSION COMPLETE — Mode: interview · Assumptions: 1 (store choice) · Handoff: none +``` + +### Sync Mode (composed by /pair-process-refine-story, phase 0) + +```text +$mode: sync, $story: #142, $context: +AI: [explores story body: Goal and AC present; Design, Risks missing] + Goal and AC already covered — skipping. + Who owns retry logic if the downstream call times out — caller or this story? + Recommendation: this story — the caller has no visibility into the downstream contract. +You: agreed +AI: [continues through Edge Cases, Dependencies, Design] + What's most likely to break or slip here? + Recommendation: the third-party rate limit — unconfirmed quota. +You: yes, flag that +AI: Do we have shared understanding here? (yes / no) +You: yes +AI: GRILL SESSION COMPLETE — Mode: sync · Coverage: 6/6 · returns alignment synthesis to /pair-process-refine-story +``` + +## Edge Cases and Error Handling + +- **User answers "don't know"**: the recommendation becomes the provisional answer, flagged as an assumption in the synthesis — never silently dropped, never blocking. +- **Session interrupted** (human stops, connection drops, or the composing skill's turn budget ends) before Step 4's explicit confirmation: offer the partial synthesis as a handoff file in `.pair/working/` rather than discarding it. +- **Aspect already answered earlier in the same conversation**: skip it, mark it explored with a reference to where it was answered — never re-ask. + +## HALT Conditions + +- `$mode: sync` with no `$story` resolvable from arguments or composer context (Step 0). + +## Graceful Degradation + +- If KB/codebase exploration is unavailable (no repo access), skip Step 1 silently in the sense that nothing is marked explored, ask every aspect/topic question directly, and note in the synthesis that explore-first was skipped. +- If `.pair/working/` cannot be created or written, present the handoff content inline in conversation and tell the human to save it manually. +- If the composing skill (`/pair-process-brainstorm`, `/pair-process-refine-story`) is not installed, grill still runs standalone — it has no required composed skills. + +## Notes + +- **Write-free by design**: single-writer responsibility stays with composers. Grill never writes adoption files or PM tool issues in any mode; the only file it ever writes is the optional `.pair/working/` handoff, and only on request or interruption. +- **Recommendation always present**: every question carries a recommended answer, adapted from mattpocock `grilling`. +- **Never auto-exit**: the exit condition is always an explicit shared-understanding confirmation — an empty question queue alone is not enough to end a session. +- Sync mode's coverage ordering is a checklist, not a script: aspects already resolved by exploration or earlier conversation are skipped, keeping sessions proportional to what's actually unknown. +- The `.pair/working/` handoff format here is a minimal, self-contained default — expect it to align with the checkpoint capability once that lands, without changing grill's write-free contract. diff --git a/.pair/knowledge/skills-guide.md b/.pair/knowledge/skills-guide.md index 759f939d..15ad5090 100644 --- a/.pair/knowledge/skills-guide.md +++ b/.pair/knowledge/skills-guide.md @@ -15,9 +15,9 @@ Run `/pair-next` at the start of every session. It reads project adoption files | Type | Count | Purpose | |------|-------|---------| | **Process** | 9 | Lifecycle phases — orchestrate capability skills | -| **Capability** | 23 | Atomic units — perform a single focused operation | +| **Capability** | 24 | Atomic units — perform a single focused operation | -Process skills compose capability skills. Capability skills are independently invocable. Total: 33 (9 process + 23 capability + 1 navigator). +Process skills compose capability skills. Capability skills are independently invocable. Total: 34 (9 process + 24 capability + 1 navigator). ## Full Catalog @@ -37,7 +37,7 @@ Process skills compose capability skills. Capability skills are independently in > How-to guides 04 and 05 (subdomain/bounded-context definition) no longer map to a process skill — see [Domain Modeling Skills](#domain-modeling-skills-2) below and [Migration Notes](#migration-notes). -### Capability Skills (23) +### Capability Skills (24) #### Domain Modeling Skills (2) @@ -94,6 +94,12 @@ Reclassified from process to capability (D24) — see [Callers Matrix](#callers- | `/pair-capability-assess-code-quality` | Code quality metrics assessment | | `/pair-capability-manage-flags` | Feature flag lifecycle management | +#### Discovery Skills (1) + +| Skill | Scope | +|-------|-------| +| `/pair-capability-grill` | Reusable interview engine (interview / sync modes), write-free | + ## Directory Structure ```text @@ -121,7 +127,8 @@ Reclassified from process to capability (D24) — see [Callers Matrix](#callers- │ ├── setup-gates/ │ ├── setup-pm/ │ ├── assess-code-quality/ -│ └── manage-flags/ +│ ├── manage-flags/ +│ └── grill/ └── next/ # Navigator skill └── SKILL.md ``` diff --git a/apps/website/content/docs/contributing/writing-skills.mdx b/apps/website/content/docs/contributing/writing-skills.mdx index 1bcfe677..097fbbe5 100644 --- a/apps/website/content/docs/contributing/writing-skills.mdx +++ b/apps/website/content/docs/contributing/writing-skills.mdx @@ -12,7 +12,7 @@ This guide walks you through creating a new skill for the pair Knowledge Base. | Type | Count | Purpose | |------|-------|---------| | **Process** | 11 | Lifecycle phases — orchestrate capability skills (e.g., `/implement`, `/review`) | -| **Capability** | 19 | Atomic units — perform a single focused operation (e.g., `/verify-quality`, `/record-decision`) | +| **Capability** | 20 | Atomic units — perform a single focused operation (e.g., `/verify-quality`, `/record-decision`) | Process skills **compose** capability skills. Capability skills are independently invocable. @@ -177,6 +177,6 @@ Add your skill to `packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.m ## Resources - [Agent Skills specification](https://agentskills.io) — The open standard. -- [Skills Catalog](/docs/reference/skills-catalog) — Full list of all 30 pair skills. +- [Skills Catalog](/docs/reference/skills-catalog) — Full list of all 31 pair skills. - [Skills concept](/docs/concepts/skills) — How skills fit into the pair ecosystem. diff --git a/apps/website/content/docs/reference/skill-management.mdx b/apps/website/content/docs/reference/skill-management.mdx index 9dcda3a3..1916a532 100644 --- a/apps/website/content/docs/reference/skill-management.mdx +++ b/apps/website/content/docs/reference/skill-management.mdx @@ -164,7 +164,7 @@ If two different source paths flatten to the same installed name (e.g. `a/b/` an | ------ | ----- | ------- | | `pair-` | 1 | Top-level skills (only `next`) | | `pair-process-` | 9 | Workflow orchestration skills | -| `pair-capability-` | 23 | Atomic operation skills | +| `pair-capability-` | 24 | Atomic operation skills | ### Transform Functions diff --git a/apps/website/content/docs/reference/skills-catalog.mdx b/apps/website/content/docs/reference/skills-catalog.mdx index c3b3c6d7..4c7d1b56 100644 --- a/apps/website/content/docs/reference/skills-catalog.mdx +++ b/apps/website/content/docs/reference/skills-catalog.mdx @@ -1,9 +1,9 @@ --- title: Skills Catalog -description: Complete catalog of all 33 pair skills organized by type — process, capability, and meta. +description: Complete catalog of all 34 pair skills organized by type — process, capability, and meta. --- -pair ships with 33 skills organized into three types: **process** (workflow orchestration), **capability** (atomic operations), and **meta** (navigation). Each skill is a `SKILL.md` file invoked as a slash command by your AI coding assistant. +pair ships with 34 skills organized into three types: **process** (workflow orchestration), **capability** (atomic operations), and **meta** (navigation). Each skill is a `SKILL.md` file invoked as a slash command by your AI coding assistant. > **Last updated:** 2026-07-07. Source: `packages/knowledge-hub/dataset/.skills/` @@ -88,6 +88,12 @@ Reclassified from process skills — see [Migration Notes](/docs/reference/skill | **write-issue** | `/pair-capability-write-issue` | Creates or updates issues in the adopted PM tool using template-driven formatting. | | **estimate** | `/pair-capability-estimate` | Estimates a refined user story using the adopted estimation methodology. | +### Discovery Capabilities + +| Skill | Command | Description | +| ----- | ------- | ----------- | +| **grill** | `/pair-capability-grill` | Reusable interview engine: one question at a time, always with a recommendation, exploring KB/codebase before asking. `sync` mode drives systematic AI-human alignment on a story until explicit shared understanding. Write-free — returns the synthesis to the caller. | + ## Skill Properties All skills share these properties: diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md b/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md index 7f356f44..1a7db100 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md @@ -15,9 +15,9 @@ Run `/next` at the start of every session. It reads project adoption files and P | Type | Count | Purpose | |------|-------|---------| | **Process** | 9 | Lifecycle phases — orchestrate capability skills | -| **Capability** | 23 | Atomic units — perform a single focused operation | +| **Capability** | 24 | Atomic units — perform a single focused operation | -Process skills compose capability skills. Capability skills are independently invocable. Total: 33 (9 process + 23 capability + 1 navigator). +Process skills compose capability skills. Capability skills are independently invocable. Total: 34 (9 process + 24 capability + 1 navigator). ## Full Catalog @@ -37,7 +37,7 @@ Process skills compose capability skills. Capability skills are independently in > How-to guides 04 and 05 (subdomain/bounded-context definition) were removed — domain modeling is referenced inline by each real caller's own how-to (02, 03, 06, 09; 08 planned — #242). See [Domain Modeling Skills](#domain-modeling-skills-2) below and [Migration Notes](#migration-notes). -### Capability Skills (23) +### Capability Skills (24) #### Domain Modeling Skills (2) @@ -94,6 +94,12 @@ Reclassified from process to capability (D24) — see [Callers Matrix](#callers- | `/assess-code-quality` | Code quality metrics assessment | | `/manage-flags` | Feature flag lifecycle management | +#### Discovery Skills (1) + +| Skill | Scope | +|-------|-------| +| `/grill` | Reusable interview engine (interview / sync modes), write-free | + ## Directory Structure ```text @@ -121,7 +127,8 @@ Reclassified from process to capability (D24) — see [Callers Matrix](#callers- │ ├── setup-gates/ │ ├── setup-pm/ │ ├── assess-code-quality/ -│ └── manage-flags/ +│ ├── manage-flags/ +│ └── grill/ └── next/ # Navigator skill └── SKILL.md ``` diff --git a/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md new file mode 100644 index 00000000..a90698a1 --- /dev/null +++ b/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md @@ -0,0 +1,211 @@ +--- +name: grill +description: "Reusable interview engine: one question at a time, always with a recommendation, exploring KB/codebase before asking. sync mode drives systematic AI-human alignment on every story aspect until explicit shared understanding is confirmed. Write-free by design — returns the synthesis to the caller, never writes adoption or issues. Invocable standalone or composed by /brainstorm (phase 1) and /refine-story (phase 0)." +version: 0.4.1 +author: Foomakers +--- + +# /grill — Interview Engine + +Ask one question at a time, always with a recommended answer, after exploring the KB/codebase for anything already answerable. `interview` mode explores a free topic; `sync` mode systematically aligns AI and human on every aspect of a story. Never writes — returns the synthesis to the caller. + +## Arguments + +| Argument | Required | Description | +| ---------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `$mode` | No | `interview` (default) or `sync`. | +| `$topic` | No | Freeform subject to explore in `interview` mode. If omitted, the opening question asks for it. | +| `$story` | Conditional| Target story identifier. Required for `sync` mode unless the composing skill already supplies a loaded story via `$context`. | +| `$context` | No | Caller-supplied context bundle (e.g. brainstorm's seed text, refine-story's current story body) so grill skips re-fetching it. | +| `$aspects` | No | Comma-separated subset of the [Sync Coverage Checklist](#sync-coverage-checklist) to focus on (e.g. `risks,dependencies`). `sync` only. If omitted, all six aspects are covered.| + +## Modes + +### Interview Mode (default) + +Freeform exploration of `$topic`. No fixed checklist — the question queue grows from what Step 1's exploration leaves open and from what answers reveal. Used standalone or composed by `/brainstorm` phase 1 to produce a raw requirements blob. + +### Sync Mode + +Systematic AI↔human alignment on a specific story, covering all six aspects of the [Sync Coverage Checklist](#sync-coverage-checklist) (goal, AC, edge cases, dependencies, design, risks). Ends only at explicit shared-understanding confirmation. Used standalone (e.g. "sync me on #42") or composed by `/refine-story` phase 0. + +## Algorithm + +### Step 0: Detect Mode and Target + +1. **Check**: Is `$mode` provided? +2. **Skip**: If provided, use it. +3. **Act**: Default to `interview` when omitted. +4. **Act**: If `$mode: sync`, resolve the target story: + - Use `$story` if provided. + - Else use a story already loaded by the composing skill via `$context`. + - Else **HALT**: "sync mode needs a target story — provide `$story` or invoke via `/refine-story`." +5. **Verify**: Mode is `interview` or `sync`; for `sync`, a target story is resolved. + +### Step 1: Explore Before Asking + +1. **Act**: Before drafting any question, gather what is already knowable: + - `interview`: read the [PRD](../../../.pair/adoption/product/PRD.md), related epics/issues (per [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md)), and grep the codebase for the topic's terms. + - `sync`: read the target story's current body (sections already populated), [architecture.md](../../../.pair/adoption/tech/architecture.md), [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md), [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md), prior decisions in decision-log/adr, and the codebase for the touched components. +2. **Act**: For every fact resolvable this way, mark it **explored** with its source. It is never asked — anything answerable by exploring KB/codebase is explored instead of asked. +3. **Verify**: An explored/unresolved map exists before the first question is asked. + +### Step 2: Build the Question Queue + +1. **Check**: `interview` or `sync`? +2. **Act (interview)**: Decompose `$topic` into the open sub-questions left after Step 1. If `$topic` is omitted, the opening question of the queue is simply "what's the topic?". The queue has no fixed size — it grows as answers reveal new sub-questions. +3. **Act (sync)**: Take the [Sync Coverage Checklist](#sync-coverage-checklist), restricted to `$aspects` if given. Drop any aspect fully resolved in Step 1; queue the remaining aspects in checklist order (already risk-ordered). +4. **Verify**: Queue built — topic-driven (interview) or checklist-driven (sync). + +### Step 3: Ask One Question at a Time + +1. **Act**: Pop the next queue item. Ask exactly one question, always with a recommended answer derived from Step 1's findings, project precedent, or best judgment: + + > [Question]? + > **Recommendation**: [proposed answer] — [why]. + +2. **Act**: Read the human's reply: + - **Accepts the recommendation** → record it as the answer. + - **Gives a different answer** → record that instead. + - **"Don't know"** → the recommendation becomes the **provisional answer**, flagged as an assumption in the synthesis. + - **Raises a new sub-question** → insert it into the queue before continuing. +3. **Verify**: Exactly one answer recorded per question. Never batch multiple questions in a single turn. + +### Step 4: Repeat Until Explicit Shared Understanding + +1. **Check**: Is the queue empty? +2. **Skip**: If not empty, return to Step 3. +3. **Act**: When the queue empties, ask directly: + + > Do we have shared understanding here? (yes / no — anything to add?) + +4. **Verify**: Only an explicit **yes** ends the session. A **no**, or any new concern raised, adds items to the queue and returns to Step 3. The session never auto-exits on an empty queue alone. + +### Step 5: Assemble the Synthesis + +1. **Act**: Compile recorded answers, explored facts (with source), and flagged assumptions: + - `interview` → raw requirements blob (topic, findings per sub-question, open items, assumptions). + - `sync` → alignment synthesis mapped to the six [Sync Coverage Checklist](#sync-coverage-checklist) aspects, ready to drop into the matching [user-story-template.md](../../../.pair/knowledge/guidelines/collaboration/templates/user-story-template.md) sections. +2. **Verify**: Synthesis accounts for every answered/explored/assumed item — nothing silently dropped. + +### Step 6: Return — Never Write + +1. **Act**: Return the synthesis to the caller (composed invocation) or print it in conversation (standalone). **Never** write to adoption files or PM tool issues in either mode — that stays with the composer (`/brainstorm`, `/refine-story`) or the human. +2. **Act (standalone, or session interrupted before Step 4's explicit yes)**: Offer an optional handoff file: + + > Save this as a handoff file in `.pair/working/`? (y/n) + + If yes, create `.pair/working/` if it doesn't exist and write `grill---.md` with the synthesis-so-far plus per-aspect/per-topic coverage state (covered / explored / open). +3. **Verify**: No adoption or PM tool write occurred, regardless of mode or handoff. + +## Sync Coverage Checklist + +Ordered by risk of omission. Goal always comes first — it anchors every other aspect, so it precedes the risk ordering; the remaining five follow the same order the story template already uses functional-first, technical-last. + +| # | Aspect | Story Template Section(s) | Explore First | Sample Probe | +| - | ------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | --------------------------------------------------------- | +| 1 | Goal | Story Statement, User Value | PRD, parent epic body | "As a [persona], I want [outcome], so that [benefit] — confirm or adjust?" | +| 2 | AC | Acceptance Criteria → Functional Requirements (Given-When-Then), Business Rules | Story's existing AC draft, similar refined stories | One Given-When-Then scenario at a time | +| 3 | Edge Cases | Edge Cases and Error Handling | Codebase error-handling patterns, existing edge cases on the story | "What happens when [input/dependency] fails?" | +| 4 | Dependencies | Dependencies and Coordination | PM tool backlog graph, epic breakdown | "Does this depend on, or block, another story?" | +| 5 | Design | Technical Analysis → Implementation Approach, Key Components, Integration Points | architecture.md, tech-stack.md, codebase | "Which existing component/pattern implements this?" | +| 6 | Risks | Technical Risks and Mitigation | Story's existing risk table, decision-log/adr precedent | "What's most likely to break or slip here?" | + +Any aspect already covered by Step 1's exploration, or already answered elsewhere in the same conversation, is skipped and marked explored rather than asked — this is the session-length mitigation: the checklist stays fixed, but only genuinely open aspects consume a question. + +## Output Format + +```text +GRILL SESSION COMPLETE: +├── Mode: [interview | sync] +├── Topic/Story: [topic string | #ID: Title] +├── Coverage: [N/6 aspects covered (sync) | topics explored: list (interview)] +├── Assumptions: [list of "don't know" → recommendation-as-assumption items, or none] +├── Explored: [KB/codebase sources consulted instead of asked] +├── Confirmed: [explicit shared understanding: Yes] +└── Handoff: [None | .pair/working/] + +SYNTHESIS: +[the raw requirements blob (interview) or the six-aspect alignment synthesis (sync)] +``` + +## Composition Interface + +When composed by `/brainstorm` (phase 1): + +- **Input**: `$mode` omitted (defaults `interview`); `$topic` from the free theme text or the `$root` issue's body; `$context` carries the issue if `$root` was given. +- **Output**: Returns the raw requirements blob (R3.7). `/brainstorm` carries it into phase 2 (domain integration) — grill never touches the PM tool or adoption files itself. + +When composed by `/refine-story` (phase 0, future extension): + +- **Input**: `$mode: sync`; `$story` is the story being refined; `$context` carries the current (possibly partial) story body so grill doesn't re-fetch it. +- **Output**: Returns the alignment synthesis, pre-mapped to Refined User Story Template sections. `/refine-story` merges it into the body it writes via `/write-issue` — grill itself never calls `/write-issue`. + +When invoked **standalone**: + +- No composition context required (decision Q8). `$mode` defaults to `interview`; if `$topic` is also omitted, the opening question asks for it directly. `sync` still requires `$story`. +- Synthesis is printed in conversation. A handoff file in `.pair/working/` is offered, never written silently. + +## Example Transcripts + +### Interview Mode (standalone, free topic) + +```text +> /grill +AI: What's the topic? + Recommendation: none — this is genuinely open, your call. +You: caching strategy for the API layer +AI: [explores codebase: finds no cache layer; checks tech-stack.md: Redis already adopted] + Redis is already in tech-stack.md but unused for caching — reuse it or introduce another store? + Recommendation: reuse Redis — avoids a new dependency. +You: don't know +AI: [records "reuse Redis" as provisional answer, flagged as assumption] + What's the target cache TTL? + Recommendation: 5 minutes — matches the existing session-token TTL in auth config. +You: agreed +AI: Do we have shared understanding here? (yes / no) +You: yes +AI: GRILL SESSION COMPLETE — Mode: interview · Assumptions: 1 (store choice) · Handoff: none +``` + +### Sync Mode (composed by /refine-story, phase 0) + +```text +$mode: sync, $story: #142, $context: +AI: [explores story body: Goal and AC present; Design, Risks missing] + Goal and AC already covered — skipping. + Who owns retry logic if the downstream call times out — caller or this story? + Recommendation: this story — the caller has no visibility into the downstream contract. +You: agreed +AI: [continues through Edge Cases, Dependencies, Design] + What's most likely to break or slip here? + Recommendation: the third-party rate limit — unconfirmed quota. +You: yes, flag that +AI: Do we have shared understanding here? (yes / no) +You: yes +AI: GRILL SESSION COMPLETE — Mode: sync · Coverage: 6/6 · returns alignment synthesis to /refine-story +``` + +## Edge Cases and Error Handling + +- **User answers "don't know"**: the recommendation becomes the provisional answer, flagged as an assumption in the synthesis — never silently dropped, never blocking. +- **Session interrupted** (human stops, connection drops, or the composing skill's turn budget ends) before Step 4's explicit confirmation: offer the partial synthesis as a handoff file in `.pair/working/` rather than discarding it. +- **Aspect already answered earlier in the same conversation**: skip it, mark it explored with a reference to where it was answered — never re-ask. + +## HALT Conditions + +- `$mode: sync` with no `$story` resolvable from arguments or composer context (Step 0). + +## Graceful Degradation + +- If KB/codebase exploration is unavailable (no repo access), skip Step 1 silently in the sense that nothing is marked explored, ask every aspect/topic question directly, and note in the synthesis that explore-first was skipped. +- If `.pair/working/` cannot be created or written, present the handoff content inline in conversation and tell the human to save it manually. +- If the composing skill (`/brainstorm`, `/refine-story`) is not installed, grill still runs standalone — it has no required composed skills. + +## Notes + +- **Write-free by design**: single-writer responsibility stays with composers. Grill never writes adoption files or PM tool issues in any mode; the only file it ever writes is the optional `.pair/working/` handoff, and only on request or interruption. +- **Recommendation always present**: every question carries a recommended answer, adapted from mattpocock `grilling`. +- **Never auto-exit**: the exit condition is always an explicit shared-understanding confirmation — an empty question queue alone is not enough to end a session. +- Sync mode's coverage ordering is a checklist, not a script: aspects already resolved by exploration or earlier conversation are skipped, keeping sessions proportional to what's actually unknown. +- The `.pair/working/` handoff format here is a minimal, self-contained default — expect it to align with the checkpoint capability once that lands, without changing grill's write-free contract. From fb35454b4949a36198b330a2d17be36d7a424656 Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Tue, 7 Jul 2026 09:45:37 +0200 Subject: [PATCH 2/4] [#229] fix: correct grill goal-aspect mapping + stale skill counts Goal aspect mapped to Refined template's only matching section (Story Statement; User Value is Initial-Breakdown-only). Reconciled capability count to 22 (verified dir count) across skills-guide and website docs; skills-catalog.mdx was already correct. --- .claude/skills/pair-capability-grill/SKILL.md | 2 +- apps/website/content/docs/contributing/writing-skills.mdx | 4 ++-- apps/website/content/docs/reference/skill-management.mdx | 2 +- .../knowledge-hub/dataset/.skills/capability/grill/SKILL.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.claude/skills/pair-capability-grill/SKILL.md b/.claude/skills/pair-capability-grill/SKILL.md index d028b2f2..5c67277f 100644 --- a/.claude/skills/pair-capability-grill/SKILL.md +++ b/.claude/skills/pair-capability-grill/SKILL.md @@ -104,7 +104,7 @@ Ordered by risk of omission. Goal always comes first — it anchors every other | # | Aspect | Story Template Section(s) | Explore First | Sample Probe | | - | ------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | --------------------------------------------------------- | -| 1 | Goal | Story Statement, User Value | PRD, parent epic body | "As a [persona], I want [outcome], so that [benefit] — confirm or adjust?" | +| 1 | Goal | Story Statement | PRD, parent epic body | "As a [persona], I want [outcome], so that [benefit] — confirm or adjust?" | | 2 | AC | Acceptance Criteria → Functional Requirements (Given-When-Then), Business Rules | Story's existing AC draft, similar refined stories | One Given-When-Then scenario at a time | | 3 | Edge Cases | Edge Cases and Error Handling | Codebase error-handling patterns, existing edge cases on the story | "What happens when [input/dependency] fails?" | | 4 | Dependencies | Dependencies and Coordination | PM tool backlog graph, epic breakdown | "Does this depend on, or block, another story?" | diff --git a/apps/website/content/docs/contributing/writing-skills.mdx b/apps/website/content/docs/contributing/writing-skills.mdx index 097fbbe5..3a0dde2d 100644 --- a/apps/website/content/docs/contributing/writing-skills.mdx +++ b/apps/website/content/docs/contributing/writing-skills.mdx @@ -12,7 +12,7 @@ This guide walks you through creating a new skill for the pair Knowledge Base. | Type | Count | Purpose | |------|-------|---------| | **Process** | 11 | Lifecycle phases — orchestrate capability skills (e.g., `/implement`, `/review`) | -| **Capability** | 20 | Atomic units — perform a single focused operation (e.g., `/verify-quality`, `/record-decision`) | +| **Capability** | 22 | Atomic units — perform a single focused operation (e.g., `/verify-quality`, `/record-decision`) | Process skills **compose** capability skills. Capability skills are independently invocable. @@ -177,6 +177,6 @@ Add your skill to `packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.m ## Resources - [Agent Skills specification](https://agentskills.io) — The open standard. -- [Skills Catalog](/docs/reference/skills-catalog) — Full list of all 31 pair skills. +- [Skills Catalog](/docs/reference/skills-catalog) — Full list of all 34 pair skills. - [Skills concept](/docs/concepts/skills) — How skills fit into the pair ecosystem. diff --git a/apps/website/content/docs/reference/skill-management.mdx b/apps/website/content/docs/reference/skill-management.mdx index 1916a532..03385621 100644 --- a/apps/website/content/docs/reference/skill-management.mdx +++ b/apps/website/content/docs/reference/skill-management.mdx @@ -267,6 +267,6 @@ No code change is required in `apps/pair-cli` — the `skills` registry (`config ## Related -- [Skills Catalog](/docs/reference/skills-catalog) — All 33 pair skills +- [Skills Catalog](/docs/reference/skills-catalog) — All 34 pair skills - [Configuration Reference](/docs/reference/configuration) — config.json registry settings - [KB Structure Reference](/docs/reference/kb-structure) — Directory layout diff --git a/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md index a90698a1..1d959e52 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md @@ -104,7 +104,7 @@ Ordered by risk of omission. Goal always comes first — it anchors every other | # | Aspect | Story Template Section(s) | Explore First | Sample Probe | | - | ------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | --------------------------------------------------------- | -| 1 | Goal | Story Statement, User Value | PRD, parent epic body | "As a [persona], I want [outcome], so that [benefit] — confirm or adjust?" | +| 1 | Goal | Story Statement | PRD, parent epic body | "As a [persona], I want [outcome], so that [benefit] — confirm or adjust?" | | 2 | AC | Acceptance Criteria → Functional Requirements (Given-When-Then), Business Rules | Story's existing AC draft, similar refined stories | One Given-When-Then scenario at a time | | 3 | Edge Cases | Edge Cases and Error Handling | Codebase error-handling patterns, existing edge cases on the story | "What happens when [input/dependency] fails?" | | 4 | Dependencies | Dependencies and Coordination | PM tool backlog graph, epic breakdown | "Does this depend on, or block, another story?" | From 70605aa1bb3ea6030dd8d300859dd6def6d45d65 Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Tue, 7 Jul 2026 20:46:17 +0200 Subject: [PATCH 3/4] [#229] fix: correct stale skill counts in writing-skills.mdx after rebase MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Found while rebasing this branch onto the updated main: this file's own "Process 11 / Capability 22" counts predate #246's process→capability reclassification and weren't part of the rebase conflict (git auto-merged it verbatim since main never touched this specific file). Corrected to Process 9 / Capability 24, consistent with skills-guide.md and skills-catalog.mdx. Also fixed a pre-existing MD012 (multiple blank lines) markdownlint violation at EOF. Refs: #229 --- apps/website/content/docs/contributing/writing-skills.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/apps/website/content/docs/contributing/writing-skills.mdx b/apps/website/content/docs/contributing/writing-skills.mdx index 3a0dde2d..9460499b 100644 --- a/apps/website/content/docs/contributing/writing-skills.mdx +++ b/apps/website/content/docs/contributing/writing-skills.mdx @@ -11,8 +11,8 @@ This guide walks you through creating a new skill for the pair Knowledge Base. | Type | Count | Purpose | |------|-------|---------| -| **Process** | 11 | Lifecycle phases — orchestrate capability skills (e.g., `/implement`, `/review`) | -| **Capability** | 22 | Atomic units — perform a single focused operation (e.g., `/verify-quality`, `/record-decision`) | +| **Process** | 9 | Lifecycle phases — orchestrate capability skills (e.g., `/implement`, `/review`) | +| **Capability** | 24 | Atomic units — perform a single focused operation (e.g., `/verify-quality`, `/record-decision`) | Process skills **compose** capability skills. Capability skills are independently invocable. @@ -179,4 +179,3 @@ Add your skill to `packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.m - [Agent Skills specification](https://agentskills.io) — The open standard. - [Skills Catalog](/docs/reference/skills-catalog) — Full list of all 34 pair skills. - [Skills concept](/docs/concepts/skills) — How skills fit into the pair ecosystem. - From fad949cacf046bc1f2a83d2561b3df0d699cc460 Mon Sep 17 00:00:00 2001 From: Gianluca Carucci Date: Wed, 8 Jul 2026 19:36:30 +0200 Subject: [PATCH 4/4] [#229] fix: HITL self-answering guard + record Q8 decision (grill review remediation) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add a HITL self-answering guard to Step 3 (both SKILL.md copies): the agent must never answer a question on the human's behalf or treat a missing reply as acceptance. Inspired by an equivalent fix landed in mattpocock/skills' wayfinder/grilling (v1.1, 2026-07-06): "a grilling agent that answers its own questions has broken this." - Record decision-log/2026-07-08-grill-standalone-no-composition-context.md (Q8): the story's own AC/Composition Interface cite "decision Q8" with no backing record — same gap pattern closed for D21/Q11 in #232. Refs: #229 --- .claude/skills/pair-capability-grill/SKILL.md | 3 +- ...grill-standalone-no-composition-context.md | 40 +++++++++++++++++++ .../dataset/.skills/capability/grill/SKILL.md | 3 +- 3 files changed, 44 insertions(+), 2 deletions(-) create mode 100644 .pair/adoption/decision-log/2026-07-08-grill-standalone-no-composition-context.md diff --git a/.claude/skills/pair-capability-grill/SKILL.md b/.claude/skills/pair-capability-grill/SKILL.md index 5c67277f..12d3d2af 100644 --- a/.claude/skills/pair-capability-grill/SKILL.md +++ b/.claude/skills/pair-capability-grill/SKILL.md @@ -69,7 +69,8 @@ Systematic AI↔human alignment on a specific story, covering all six aspects of - **Gives a different answer** → record that instead. - **"Don't know"** → the recommendation becomes the **provisional answer**, flagged as an assumption in the synthesis. - **Raises a new sub-question** → insert it into the queue before continuing. -3. **Verify**: Exactly one answer recorded per question. Never batch multiple questions in a single turn. +3. **Never answer on the human's behalf.** The recommendation is a proposal, not a stand-in for consent — if no reply has been given yet, the turn ends there and the session waits for real input. Treating a missing reply as acceptance, or drafting what the human "would probably say," breaks the interview — grill is HITL by design, and the agent never speaks for the human's side of it. +4. **Verify**: Exactly one answer recorded per question. Never batch multiple questions in a single turn. ### Step 4: Repeat Until Explicit Shared Understanding diff --git a/.pair/adoption/decision-log/2026-07-08-grill-standalone-no-composition-context.md b/.pair/adoption/decision-log/2026-07-08-grill-standalone-no-composition-context.md new file mode 100644 index 00000000..af6e8110 --- /dev/null +++ b/.pair/adoption/decision-log/2026-07-08-grill-standalone-no-composition-context.md @@ -0,0 +1,40 @@ +# Decision: `pair-capability-grill` Runs Standalone Without Composition Context + +## Date + +2026-07-08 + +## Status + +Active + +## Category + +Process Decision + +## Context + +Story #229 (`pair-capability-grill` — reusable interview engine) needed to decide whether the skill requires a composing caller (`/pair-process-brainstorm`, `/pair-process-refine-story`) to function, or whether it can run directly when a human invokes it standalone (e.g. "grill me on X"). + +During #229's refinement session this was resolved as an open question (**Q8**) and recorded only in the story body's "Refinement Session Insights" ("Q8 decided — standalone yes, write-free with optional working/ handoff") — never formalized as a decision record, even though the shipped `SKILL.md` cites "decision Q8" inline as if a durable record existed (`.claude/skills/pair-capability-grill/SKILL.md`, Composition Interface § standalone case). This follows the same pattern closed for D21/Q11 in #232 (`2026-07-08-husky-default-hook-manager.md`) — this ADL closes the equivalent gap for Q8. + +## Decision + +**`pair-capability-grill` runs standalone with no composition context required.** When invoked directly (not composed by another skill), `$mode` defaults to `interview`; if `$topic` is also omitted, the opening question of the interview simply asks for it. `sync` mode is the one exception — it always requires a target story (`$story`), whether composed or standalone, since sync has no meaning without a story to align on. + +Standalone sessions remain write-free like composed ones: the synthesis is printed in conversation rather than returned to a caller, and a `.pair/working/` handoff file is offered (not auto-written) on interruption or explicit request. + +## Alternatives Considered + +- **Require a composing caller always**: rejected — would make grill unusable for a human who just wants an ad-hoc interview (e.g. "grill me on this design before I build it"), which is the skill's most direct, lowest-friction use case and the one explicitly named in the story's own Business Rules. +- **Standalone mode auto-writes a handoff file**: rejected — contradicts the write-free-by-design contract; a human running an ad-hoc interview may not want a file left behind for a quick, disposable exploration. Handoff stays opt-in. + +## Consequences + +- `pair-capability-grill`'s Step 0 (Detect Mode and Target) does not HALT when no composing skill and no `$context` are present — this is expected, not an error path, for `interview` mode. +- Documentation, examples, and the Composition Interface section must keep the standalone case as a first-class path, not an edge case bolted onto composed usage. + +## Adoption Impact + +- No adoption file changes required — this is a skill-internal behavioral decision, not a project-level configuration choice. +- `pair-capability-grill` `SKILL.md` (dataset + installed mirror) already documents this decision inline (Composition Interface § standalone: "decision Q8"). diff --git a/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md b/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md index 1d959e52..ae3aaf79 100644 --- a/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md @@ -69,7 +69,8 @@ Systematic AI↔human alignment on a specific story, covering all six aspects of - **Gives a different answer** → record that instead. - **"Don't know"** → the recommendation becomes the **provisional answer**, flagged as an assumption in the synthesis. - **Raises a new sub-question** → insert it into the queue before continuing. -3. **Verify**: Exactly one answer recorded per question. Never batch multiple questions in a single turn. +3. **Never answer on the human's behalf.** The recommendation is a proposal, not a stand-in for consent — if no reply has been given yet, the turn ends there and the session waits for real input. Treating a missing reply as acceptance, or drafting what the human "would probably say," breaks the interview — grill is HITL by design, and the agent never speaks for the human's side of it. +4. **Verify**: Exactly one answer recorded per question. Never batch multiple questions in a single turn. ### Step 4: Repeat Until Explicit Shared Understanding