pair-capability-grill

name	pair-capability-grill
description	Interviews one question at a time, always with a recommendation, after exploring the KB/codebase first; sync mode drives systematic AI-human alignment on a story until shared understanding is confirmed. Invoke directly to interview on any topic ('grill me on the requirements'). Composed by /pair-process-refine-story and a future /brainstorm (planned — #230). Write-free — returns the synthesis, never writes adoption or issues.
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.

Core Rules

• Never answer for the human. The recommendation attached to each question is a proposal, not a stand-in for consent. If no reply has been given, the turn ends 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.
• One question per turn. Ask exactly one question at a time; never batch multiple questions.
• Write-free. Never write adoption files or PM tool issues in any mode; the only file grill ever writes is the optional .pair/working/ handoff, on request or interruption.

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 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, planned — #230) 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 (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, related epics/issues (per 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, tech-stack.md, 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, 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. 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 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.

4. 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 aspects, ready to drop into the matching 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, /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-<mode>-<slug>-<YYYYMMDD-HHMM>.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, except Goal always first — it anchors every other aspect; the remaining five follow the story template's functional-first, technical-last order.

#	Aspect	Story Template Section(s)	Explore First	Sample Probe
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?"
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?"

Aspects already covered by Step 1's exploration, or answered earlier in the same conversation, are skipped and marked explored rather than asked — the checklist stays fixed, but only genuinely open aspects consume a question.

Output Format

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/<file>]

SYNTHESIS:
[the raw requirements blob (interview) or the six-aspect alignment synthesis (sync)]

Composition Interface

When composed by /brainstorm (phase 1, planned — #230):

• 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 /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)

> /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)

$mode: sync, $story: #142, $context: <current draft body>
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

See graceful degradation (composing skill not installed → this skill still runs standalone) for the standard scenarios. Additional cases:

• If KB/codebase exploration is unavailable (no repo access), skip Step 1 (nothing 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.

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, 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.
• 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.