pair-capability-grill — interview engine (interview|sync modes)

[rucka]

Story Statement

As a pair user in discovery or refinement
I want pair-capability-grill: a reusable, write-free interview engine — one question at a time, always with a recommendation, exploring KB/codebase before asking — with a sync mode for AI↔human story alignment
So that interviews are consistent across brainstorm and refine, and shared understanding gates the Ready transition (R3.11)

Where: composed by brainstorm (phase 1) and refine-story (phase 0); standalone in conversation

Epic Context

Parent Epic: Structured & parametrized brainstorming #205
Status: Refined
Priority: P0 (Must-Have)

Status Workflow

• Refined: Story is detailed, estimated, and ready for development
• In Progress: Story is actively being developed
• Done: Story delivered and accepted

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

1. Given any grill session
   When questions are asked
   Then one at a time, each with the recommended answer, and anything answerable by exploring KB/codebase is explored instead of asked

2. Given $mode: sync on a story
   When the session runs
   Then all story aspects are covered systematically (goal, AC, edge cases, dependencies, design, risks) and it ends only at explicit shared understanding, returning the alignment synthesis to the caller

3. Given any mode
   When the session produces output
   Then grill WRITES NOTHING to adoption or issues — it returns the synthesis to the caller (brainstorm/refine write); standalone: synthesis in conversation + optional handoff file in .pair/working/ on request

4. Given a standalone invocation
   When the user starts it on a free topic
   Then it works with no composition context (decision Q8: standalone allowed)

Business Rules

• Write-free by design: single-writer responsibility stays with composers
• Exit condition: explicit shared-understanding confirmation (never auto-exit)
• Recommendation always present (adapted from mattpocock grilling)

Edge Cases and Error Handling

• User answers "don't know": recommendation becomes the provisional answer, flagged as assumption in the synthesis
• Session interrupted: partial synthesis offered as handoff file (working/)

Definition of Done Checklist

Development Completion

• All acceptance criteria implemented and verified
• Skill follows authoring conventions (composition interface documented)
• Code review completed and approved
• Documentation updated — docs site page

Quality Assurance

• Composition contract verified with a mock caller
• Write-free property verified (no adoption/issue writes in any mode)

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 3 (M)
Confidence Level: High
Sizing Justification: skill text + question framework; no runtime code

Sprint Capacity Validation

Sprint Fit Assessment: yes, single sprint
Total Effort Assessment: fits — Yes

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: none
Dependent Stories: #230 brainstorm (phase 1), refine-story extension (#202 epic)

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: scripted session transcripts (interview + sync); write-free audit

Notes and Additional Context

Refinement Session Insights: Q8 decided — standalone yes, write-free with optional working/ handoff
Documentation Links: R3.2, R3.11 · Spec G3 · D24 · ref. mattpocock grilling

Technical Analysis

Implementation Approach

Technical Strategy: new capability in .skills/capability/pair-capability-grill/ adapting mattpocock grilling rules (one-at-a-time, recommendation, explore-first, shared-understanding exit) + sync question framework over the story template sections
Key Components: SKILL.md; sync coverage checklist (maps to user-story template sections); composition interface
Integration Points: brainstorm (#230), refine-story (epic #202), checkpoint (handoff format, #206)

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
Sessions too long in sync mode	Medium	Medium	coverage checklist ordered by risk; explored answers skipped

Task Breakdown

Checklist

• T1 — Author SKILL.md (rules, modes, exit condition, write-free contract)
• T2 — Sync coverage framework (story-template section map)
• T3 — Composition interface + optional handoff file (working/)
• T4 — QA transcripts + docs site page + distribution

Dependency Graph

T1 → T2 → T3 → T4

AC Coverage

Task	AC1	AC2	AC3	AC4
T1	✓		✓	✓
T2		✓
T3		✓	✓
T4	✓	✓	✓	✓

---

T-1: Author SKILL.md (rules, modes, exit condition, write-free contract)

Priority: P0 | Estimated Hours: 4h | Bounded Context: Development Collaboration

Summary: Author the pair-capability-grill skill definition: an interview engine with interview and sync modes, explore-before-ask discipline, one-question-at-a-time flow, a mandatory recommendation on every question, and an explicit-confirmation exit condition.

Type: Documentation (skill authoring — prompt/text asset, no runtime code per story sizing)

Description: Created .claude/skills/pair-capability-grill/SKILL.md (211 lines) with frontmatter (name, description, version: 0.4.1, author), an Arguments table ($mode, $topic, $story, $context, $aspects), a Modes section describing interview (freeform, topic-driven) and sync (systematic, checklist-driven), and a 7-step Algorithm: Step 0 detects mode/target and HALTs sync mode without a resolvable $story; Step 1 explores KB/codebase before any question is drafted; Step 2 builds the question queue; Step 3 asks exactly one question at a time, each with a **Recommendation**: ... — ... line, and handles accept/override/"don't know"/new-sub-question branches; Step 4 loops until an explicit "yes" to "Do we have shared understanding here?" — an empty queue alone never ends the session; Step 5 assembles the synthesis; Step 6 returns it to the caller and never writes to adoption/issues (the only write is an optional .pair/working/ handoff). The skill also documents HALT Conditions, Graceful Degradation, and Notes reinforcing the write-free contract. A follow-up commit (0b55179) corrected a mapping bug found in this same file (see T-2) — the SKILL.md content covered by this task went through one round of self-correction before the branch was considered complete.

Acceptance Criteria:

• Primary deliverable: .claude/skills/pair-capability-grill/SKILL.md exists with frontmatter, Arguments, Modes, Algorithm (Steps 0–6), HALT Conditions, Graceful Degradation, and Notes sections.
• Quality standard: the exit condition is explicit-confirmation-only (Step 4) and the write-free contract is stated in at least two places (Step 6, Notes) — both present in the merged file.
• Integration requirement: the skill's HALT condition for sync mode without a target story is documented (Step 0.4, HALT Conditions section) — present.
• Verification method: manual read-through of the authored SKILL.md against the AC1/AC3/AC4 language in the story (one-at-a-time + recommendation + explore-first, write-free, standalone-allowed) — all three are traceable to specific sections (Step 3, Step 6, Composition Interface "standalone" bullet).

Implementation Approach:

• Technical Design: single markdown skill file, no code — algorithm expressed as an imperative step list per the project's skill-authoring convention (Check/Act/Verify sub-bullets), matching the pattern used by other pair-capability-* skills.
• Files to Modify/Create:
  • .claude/skills/pair-capability-grill/SKILL.md - the skill definition itself (rules, modes, algorithm, write-free contract).

Dependencies:

• Tasks: none (root of the dependency chain — T2, T3, T4 depend on this).

Implementation Steps:

1. Draft frontmatter and Arguments table for $mode/$topic/$story/$context/$aspects.
2. Write the 7-step Algorithm (Step 0 mode/target detection through Step 6 return-never-write), embedding the recommendation-always and explicit-confirmation-exit rules directly in Steps 3 and 4.
3. Write HALT Conditions, Graceful Degradation, and Notes, restating the write-free contract for redundancy/robustness.
4. Fix the Goal-aspect table row in a follow-up commit once the mismatch against the Refined template was noticed (see T-2's Notes).

Testing Strategy:

• Unit Tests: none — this is a prose skill file; no automated test suite exists for skill content in this repo.
• Manual Testing: no scripted session transcript was actually run and recorded as a verification artifact; the only "transcripts" that exist are the two illustrative examples embedded in the SKILL.md itself (see T-4), which are documentation, not test evidence.

Notes: The story's Validation and Testing Strategy calls for "scripted session transcripts (interview + sync); write-free audit" and the DoD checklist has unchecked boxes for "Composition contract verified with a mock caller" and "Write-free property verified (no adoption/issue writes in any mode)". No such verification artifact exists anywhere in the diff (confirmed via repo-wide search for "transcript" and "write-free" — only doc prose and the two in-file illustrative examples turned up). This is a real, unresolved gap, not a formality: the write-free property that Step 6 promises has not been independently exercised or audited on this branch.

---

T-2: Sync coverage framework (story-template section map)

Priority: P0 | Estimated Hours: 2h | Bounded Context: Development Collaboration

Summary: Build the six-aspect Sync Coverage Checklist that drives sync mode, mapping each aspect (Goal, AC, Edge Cases, Dependencies, Design, Risks) to the exact section(s) of user-story-template.md's Refined template.

Type: Feature Implementation (specification/framework embedded in the skill's prose)

Description: Implemented as the "Sync Coverage Checklist" table inside .claude/skills/pair-capability-grill/SKILL.md (six rows: Goal → Story Statement; AC → Acceptance Criteria/Functional Requirements/Business Rules; Edge Cases → Edge Cases and Error Handling; Dependencies → Dependencies and Coordination; Design → Technical Analysis/Implementation Approach/Key Components/Integration Points; Risks → Technical Risks and Mitigation), each row also carrying an "Explore First" source and a "Sample Probe". The ordering is deliberately risk-of-omission-based with Goal pinned first. Checked against .pair/knowledge/guidelines/collaboration/templates/user-story-template.md's Refined User Story Template headings — every mapped section name (Story Statement, Acceptance Criteria → Functional Requirements/Business Rules, Edge Cases and Error Handling, Dependencies and Coordination, Technical Analysis → Implementation Approach, Technical Risks and Mitigation) exists verbatim in the template. The initial version of the Goal row also listed "User Value" as a target section; commit 0b55179 removed it because User Value only exists in the template's Initial Breakdown Template, not in the Refined User Story Template that sync mode actually targets — a genuine correction, not cosmetic, since sync mode explicitly operates on stories being refined toward the Refined template.

Acceptance Criteria:

• Primary deliverable: a six-row Sync Coverage Checklist table present in SKILL.md covering Goal, AC, Edge Cases, Dependencies, Design, Risks.
• Quality standard: every "Story Template Section(s)" cell resolves to a heading that actually exists in the Refined User Story Template — verified directly against user-story-template.md for all six rows.
• Integration requirement: $aspects argument (Step 0/Step 2 of T-1's algorithm) can restrict the sync queue to a named subset of this same six-aspect list — the argument description and the checklist use identical aspect names (goal/AC/edge cases/dependencies/design/risks).
• Verification method: line-by-line diff of the checklist's section names against grep -n "^##\|^###" user-story-template.md output — all six resolve; no orphaned or invented section names remain after the 0b55179 fix.

Implementation Approach:

• Technical Design: a markdown table embedded in SKILL.md, not a separate data file — chosen because the skill has no runtime and the checklist is only ever consumed by an LLM reading the skill prose.
• Files to Modify/Create:
  • .claude/skills/pair-capability-grill/SKILL.md - "Sync Coverage Checklist" section (table + explanatory paragraph on skip-if-explored behavior).

Dependencies:

• Tasks: T1 (the checklist lives inside and is referenced by T1's Step 2/Step 5 algorithm text).

Implementation Steps:

1. Enumerate the six aspects in risk-of-omission order with Goal pinned first.
2. Map each aspect to its Refined-template section(s) by reading user-story-template.md.
3. Add an "Explore First" source and a "Sample Probe" per row.
4. Correct the Goal row's section mapping (Story Statement, User Value → Story Statement) after verifying against the template that User Value isn't part of the Refined template — landed as a dedicated fix commit rather than caught before the first commit.

Testing Strategy:

• Unit Tests: none (no runtime code to unit test).
• Manual Testing: the section names were manually cross-checked against user-story-template.md's actual headings as part of this verification pass; all six now resolve correctly post-fix. No evidence exists that this cross-check happened before the fix commit was authored — i.e., the initial version shipped with an unverified mapping that turned out to be wrong.

Notes: The fact that a real mapping error (User Value) shipped in the first commit and needed a follow-up fix commit is worth flagging plainly: T2's own acceptance bar ("section names must resolve in the template") was not met on the first attempt. It was caught and fixed within the same branch before this documentation pass, so the checklist is now correct, but the task did not get it right the first time despite being a small, fully-offline, checkable mapping.

---

T-3: Composition interface + optional handoff file (working/)

Priority: P0 | Estimated Hours: 2h | Bounded Context: Development Collaboration

Summary: Specify how pair-capability-grill is composed by /pair-process-brainstorm (phase 1) and /pair-process-refine-story (phase 0), how it behaves standalone, and the optional .pair/working/ handoff file for interrupted or standalone sessions.

Type: Feature Implementation (composition contract + I/O specification, embedded in the skill's prose)

Description: Implemented as the "Composition Interface" section of SKILL.md, with three sub-cases: composed by brainstorm ($mode defaults interview, $topic from free theme text or $root issue body, returns the raw requirements blob that brainstorm carries into its own phase 2 — grill never touches the PM tool itself); composed by refine-story ($mode: sync, $story set, $context carries the current draft body, returns the alignment synthesis pre-mapped to Refined template sections — refine-story is the one that calls /pair-capability-write-issue, not grill); and standalone (no composition context required per decision Q8, $mode defaults to interview, synthesis printed in conversation, handoff offered not auto-written). The handoff mechanism itself is specified in Step 6.2 and in Graceful Degradation: on interruption or standalone request, ask "Save this as a handoff file in .pair/working/? (y/n)"; if yes, create .pair/working/ if absent and write grill-<mode>-<slug>-<YYYYMMDD-HHMM>.md with the synthesis-so-far and per-aspect/per-topic coverage state; if the directory can't be created, fall back to presenting the content inline and telling the human to save it manually.

Acceptance Criteria:

• Primary deliverable: a "Composition Interface" section in SKILL.md covering brainstorm, refine-story, and standalone invocation, each with explicit Input/Output.
• Quality standard: for every composed case, the section states which side (grill vs. the composer) performs any write — grill's output side never names /pair-capability-write-issue as something it calls.
• Integration requirement: refine-story composition (phase 0) is documented as a "future extension" in the SKILL.md text itself, since /pair-process-refine-story does not yet have a phase 0 that calls grill.
• Verification method: cross-check against /pair-process-refine-story and /pair-process-brainstorm skill definitions for whether they actually invoke pair-capability-grill yet.

Implementation Approach:

• Technical Design: prose specification of the composition contract (inputs/outputs/side-effects per caller), plus a file-naming convention for the handoff artifact — no code, consistent with story sizing ("no runtime code").
• Files to Modify/Create:
  • .claude/skills/pair-capability-grill/SKILL.md - "Composition Interface" section, Step 6.2 (handoff), Graceful Degradation (handoff failure fallback).

Dependencies:

• Tasks: T1 (composition interface is one of T1's algorithm steps/sections); informs T4 (docs/catalog description references the write-free, caller-returns-synthesis contract).

Implementation Steps:

1. Write the brainstorm composition case (inputs from free theme/$root, output = raw requirements blob).
2. Write the refine-story composition case, explicitly marked "(future extension)" since refine-story's phase 0 doesn't exist yet on this branch.
3. Write the standalone case per decision Q8 (no composition context required).
4. Specify the .pair/working/ handoff naming convention and its degradation path if the directory is unwritable.

Testing Strategy:

• Unit Tests: none (no runtime code).
• Manual Testing: none performed. No mock caller was exercised against grill to confirm the composition contract actually works when /pair-process-brainstorm or /pair-process-refine-story invoke it with the documented $context/$story shapes.

Notes: This is the clearest gap on the branch. AC2 of the story requires sync mode to be usable when composed by refine-story, but /pair-process-refine-story's phase 0 composition doesn't exist yet — the SKILL.md itself says "(future extension)" for that case. That's an honest disclosure in the doc, but it means T3's "composition interface" is, for the refine-story half, a one-sided contract: grill declares what it will accept and return, but nothing on the other end has been built or run to confirm it actually receives and consumes that shape correctly. The DoD box "Composition contract verified with a mock caller" is unchecked and no mock-caller artifact exists in the diff — consistent with this being genuinely unverified rather than just administratively unchecked.

---

T-4: QA transcripts + docs site page + distribution

Priority: P0 | Estimated Hours: 2h | Bounded Context: Development Collaboration

Summary: Produce validation evidence for the skill (interview + sync transcripts, write-free audit), add it to the public skills catalog docs page, and distribute it into the packaged skill dataset.

Type: Testing / Documentation / Configuration (three sub-deliverables bundled in one task)

Description: Docs site: added a "Discovery Capabilities" subsection to apps/website/content/docs/reference/skills-catalog.mdx with a one-row table for grill, and bumped the stale skill counts (31/32/33 → 33/34, capability 19/20 → 22) across apps/website/content/docs/contributing/writing-skills.mdx, apps/website/content/docs/reference/skill-management.mdx, and .pair/knowledge/skills-guide.md (project and distributed copies). The count fix landed in two passes: the first commit under-counted (bumped capability count from 20→21 when the actual directory count on main was already 21, i.e. it should have gone to 22 with grill added); the second commit (0b55179) reconciled it to the verified directory count of 22. Distribution: added packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md, the packaged copy consumed by the knowledge-hub distribution pipeline, kept byte-for-byte in sync with .claude/skills/pair-capability-grill/SKILL.md (same content, same fix applied to both in 0b55179). QA transcripts: no dedicated transcript artifacts, write-free audit report, or mock-caller test were produced anywhere in the diff — the only transcript-shaped content is the "Example Transcripts" section inside SKILL.md itself (two illustrative dialogues: standalone interview, composed sync), which is documentation prose written by the skill's author to show the format, not a session that was actually run and captured as evidence.

Acceptance Criteria:

• Primary deliverable: catalog entry in skills-catalog.mdx, correct capability/total counts across all doc locations, and a distributed copy under packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md.
• Quality standard: doc counts match the actual directory count (22 capability skills) — true as of 0b55179, false as of the preceding commit alone.
• Integration requirement: the distributed dataset copy must be identical in content/behavior to the .claude/skills/ source copy — confirmed (both files carry the same fix in the same commit).
• Verification method: "scripted session transcripts (interview + sync); write-free audit" per the story's own Validation and Testing Strategy section — not met; no such artifacts exist in the diff or elsewhere in the repo (verified via find/grep for "transcript" and "write-free" across the whole tree).

Implementation Approach:

• Technical Design: docs-as-markdown catalog update + count reconciliation; dataset distribution via direct file copy (matching the pattern used by every other capability skill in packages/knowledge-hub/dataset/.skills/capability/).
• Files to Modify/Create:
  • apps/website/content/docs/reference/skills-catalog.mdx - new "Discovery Capabilities" table row for grill; updated total count and "Last updated" date.
  • apps/website/content/docs/contributing/writing-skills.mdx - capability/total count bump.
  • apps/website/content/docs/reference/skill-management.mdx - capability/total count bump.
  • .pair/knowledge/skills-guide.md - new "Discovery Skills (1)" subsection, directory tree entry, count bump.
  • packages/knowledge-hub/dataset/.pair/knowledge/skills-guide.md - same as above, distributed copy.
  • packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md - distributed copy of the skill file.

Dependencies:

• Tasks: T1, T2, T3 (docs and distribution describe/package the finished skill; nothing to catalog or distribute until the skill file exists).

Implementation Steps:

1. Add the grill row and "Discovery Capabilities" heading to skills-catalog.mdx; bump its total-skills count and "Last updated" date.
2. Bump the capability/total counts in writing-skills.mdx and skill-management.mdx to match.
3. Add the "Discovery Skills (1)" subsection and directory-tree entry to .pair/knowledge/skills-guide.md (both the project copy and the distributed dataset copy).
4. Copy the finished SKILL.md into packages/knowledge-hub/dataset/.skills/capability/grill/SKILL.md for distribution.
5. Reconcile the count discrepancy discovered after the first commit (fix commit 0b55179), verifying against the actual .claude/skills/ directory count rather than arithmetic on the previous stated count.

Testing Strategy:

• Unit Tests: none.
• Manual Testing: none performed for this task's stated QA deliverable. The docs/count changes were self-consistency-checked (count now matches ls .claude/skills | grep -c pair-capability- = 22), but the "QA transcripts" and "write-free audit" called for by both the task title and the story's Validation and Testing Strategy section were not produced.

Notes: This task's title bundles three deliverables and only two were actually delivered. "Docs site page" and "distribution" are done and correct (counts now verified against the real directory, distributed copy matches source). "QA transcripts" — actual scripted interview/sync session transcripts and a write-free audit — were not produced; the in-SKILL.md "Example Transcripts" are illustrative documentation authored alongside the skill, not evidence from an executed verification session. Since AC3 (write-free) is the story's most safety-relevant acceptance criterion (grill must never write to adoption/issues), shipping without an actual write-free audit is the most significant gap found in this review — it was asserted in prose (three separate places in SKILL.md) but never independently exercised.