feat(planning): interview questions must be self-contained, with an agreed terminology matrix and references

Problem

/planning:interview rounds can reach the user with undefined terms and context the question depends on but does not carry. The user then has to stop and ask what a question means before they can decide anything. The skill's purpose is for the user to make every decision, and a decision is only theirs if they understand exactly what they are choosing.

Observed in a me-mode interview on designing a CI lane (2026-10-03):

A question asked "When the PR side is done, what does a normal day look like?" without defining "PR side" or "done". The user had to ask what it meant.
A question used work classes C4/C5 and a finish line taken from a handoff without defining either. Definitions came only after the user pushed back.
One recommendation used a name ("pr-babysit") the user had never agreed to, as though it were settled. That is a decision taken on the user's behalf.

Where the skill allows this (plugins/planning/skills/interview/SKILL.md):

Line 125 and line 145 ("One verdict marker, at most one context line") cap a question's own context at one line, usually none, and rely on the round-header restate. A question that depends on a term or source the user has not seen is then not self-contained.
Line 153 ("Define session shorthand once, then park it") defines a term once, at first use, in the ledger. It covers coined labels, but not domain or repository terms the question depends on (work classes, lifecycle stages, convention names). It also does not require the user to agree to a definition before questions rely on it.

Requested behavior

Terminology matrix before the first round. Build a table of every term the rounds will rely on: term, definition, source (file:line or URL), and status (proposed / agreed). Show it to the user, and get it agreed as the first item, before any decision question uses those terms. Keep it in the ledger. Any later round that adds a term adds a row and gets it agreed.
Self-contained question blocks. Every question carries all the context needed to decide it without scrolling back: the terms it uses (or a pointer to their agreed rows), the current state it rests on, and a reference for each factual claim. Replace the one-context-line cap with "as much context as the decision needs, and no more".
References on every claim. Each statement of fact in a question (what exists, what a convention says, what a tool does) cites file:line, tool output, or a URL. A claim with no reference is labeled judgment.
No undecided names or choices presented as settled. A name, scope, or design the user has not agreed to appears only as a recommendation inside a question, never as a working assumption in prose.
A gate check. Before a round is shown, check that every term in it has an agreed row (or is defined in the block) and every factual claim has a reference. Make the check a script where the ledger makes that possible, as check-open-questions.sh does for the register.

Acceptance

A round contains no term missing from the agreed matrix, and no undefined term in its own block.
Each question can be read alone, and a reader can decide it without asking what something means.
The ledger template carries a ## Terminology matrix section.

The user approved the corrected round from the same session as the target default shape:

A Definitions block before any question. Each term has a one-line definition and its source (file:line).
A current-state table of what the questions act on (here, each PR lifecycle stage and who does it today), so the options are concrete.
Each question then carries: the source it rests on, quoted with file:line; one recommendation with Basis: and Checked against:; the alternatives; and no term outside the definitions block.
A Found: note when a source contradicts itself (here, a handoff naming a work class that cannot produce a PR), raised for the user to decide, never silently corrected.

Make this the default in SKILL.md and the ledger template, not something a user has to ask for.

Proposed work class: work-class: scoped
Basis: automated intake triage; the lanes App applied this class.

Size: Medium
Complexity: Medium
Uncertainty: Knowable
Flags: none
Blocked by: none

Decision recorded.

Question: Where does this issue's work land, given the 2026-10-12 split into (a) default question shape and ledger template, (b) terminology and reference gate script, and (c) register recap script, with (b) after (a)?

Owner's answer (2026-10-19): "Go with recommendations." Part (a) is folded into #7475, which lands the whole interview question shape in one change. This issue narrows to parts (b) and (c), and is admitted after #7475 merges. Its acceptance for (b) and (c) is unchanged: a gate check, scripted where the ledger allows (as check-open-questions.sh does for the register), confirms every term in a round has an agreed matrix row or an in-block definition and every factual claim has a reference, before the round is shown; and (c) a register recap script with changed-rows-only recaps and terminal-safe formatting.

#6136 (comment)

The decision settles the open questions. The remaining work is the terminology and reference gate script and the register recap script. #7475 is not in the open-issues list I was given, so I recorded no blocker. Admission should confirm that #7475 has merged.

_{Automated triage, applied by the lanes App.}

Related idea from the user, to be scoped later: a terminal interview experience that saves screen space through information on demand.

Defined terms render as color-coded (e.g. blue) hover/click targets that show the term's definition and source, instead of a definitions table printed on every round.
Same idea for sources and long context: show them on demand, not inline.
This is the in-terminal experience, not the web page surface (surface: page).

Constraint: this would be a Claude Code mod, and mods are deferred in this repo under ADR 0035 (no hooks/hooks.json gains a modules key until its five go criteria pass). Treat this as a candidate use case for those criteria, not as work to start now.

Another display defect from the same interview, plus fixes. The model caused it, but the skill should prevent it.

What happened: the Step 3 confirmation recap was wrapped in an HTML <details> block to make it collapsible. The terminal does not render HTML, so the user saw raw tags around a 68-line list. The model also hand-shortened the register lines instead of printing them verbatim, and two lines were stale by the next reply.

Requested:

Surface awareness. The skill should know whether it is running in the terminal (CLI) or a web/desktop surface that renders rich Markdown, and pick its formatting to match. In the terminal that means no HTML and no collapsible blocks. This also applies beyond the recap.
A recap script. Ship a script that prints the open-question register in a fixed, compact, terminal-safe form (Q<N> <status> <short question>: <short resolution>). The confirmation recap is that script's output pasted verbatim, never the model's paraphrase. The skill already says "generated from the register on disk"; the script makes that true by construction.
Shorter long recaps. After the first confirmation, show only rows that changed since the last recap, and summarize the rest by status counts. A 60-plus-row recap on every confirmation is unreadable. (Related: the hover/click information-on-demand mod idea above.)

This was generated by AI during triage.

Routing: human-gated, status: needs-decision, priority: medium. The target question shape is already approved in the first comment above; what stays open is scope. As written, with the two later comments, this one item asks for: a new default question shape (reversing the skill's explicit "at most one context line" rule), a new ledger section, a terminology/reference gate script, a register recap script, terminal-vs-rich surface detection, and changed-rows-only recaps. That spans the skill text, the ledger format the exporter reads back, and two new scripts, too wide for one dispatch, so no work class is stamped until it is split.

Basis: verified, plugins/planning/skills/interview/SKILL.md:121-145 (question shape and "Per-question context is at most ONE line and usually absent"), :153 (shorthand glossary covers coined labels only), :384 (the Step 3 recap is a model-written line per Q<N>, not a script's output); plugins/planning/scripts/ has no recap or terminology gate script.

Decision for the operator: split this into three items? Recommended: yes.

(a) Default question shape in the interview skill and the ledger template: a Definitions block (term, one-line definition, source) agreed before the first decision question; a current-state table where the questions act on existing state; each question self-contained with its quoted source, one recommendation with Basis:, alternatives, and no term outside the Definitions block; a Found: note for a self-contradicting source; no unagreed name presented as settled. Docs-only, C3.
(b) A gate script that checks a round before it is shown: every term has an agreed row or is defined in the block, every factual claim has a reference or a judgment label, as far as the ledger makes that checkable. C3, after (a) fixes the ledger shape.
(c) A register recap script (fixed, compact, terminal-safe Q<N> <status> <short question>: <short resolution> lines, pasted verbatim), changed-rows-only recaps after the first confirmation, and terminal-aware formatting (no HTML or collapsible blocks in the CLI). C3.
Alternative: keep one item and brief it as one C3 change, which makes one large PR touching the skill, the template, and two scripts.

Out of scope either way: the in-terminal hover/click definitions idea from the second comment. It is a Claude Code mod, and mods stay deferred under ADR 0035 until its go criteria pass.

Related: slice (c)'s compact recap and #5893 item 4 (the page restatement cap cannot hold a full recap) share one decision, the compact recap form. Decide it once and point both at it.

Decision recorded. The owner approved applying independently verified recommendations on 2026-10-12.

Split this into three items (a: default question shape and ledger template; b: terminology and reference gate script; c: register recap script with changed-rows-only recaps and terminal-safe formatting)? → Split into (a), (b) and (c), with (b) after (a)
Basis: plugins/planning/skills/interview/SKILL.md:145 ('Per-question context is at most ONE line and usually absent', origin/main); triage comment 2026-10-04T06:04:13Z; owner shape approval comment 2026-10-03T21:14:06Z; fix(planning): interview page wrap-up friction: stale closed question, id count confusion, ops re-apply, restate cap #5893 OPEN

Wants /planning:interview questions to carry agreed definitions, current state and cited sources so the user can decide each one without asking what it means, plus a gate script, a terminal-safe recap script and changed-rows-only recaps. The owner approved the default shape on 2026-10-03; nothing has shipped and SKILL.md still caps per-question context at one line.

Verified by an independent fresh-context check (confirmed, risk low): gh issue view 6136 and 5 comments (owner shape approval 2026-10-03T21:14:06Z, triage split 2026-10-04T06:04:13Z); SKILL.md:145 one-context-line rule on origin/main; #5893 OPEN; no merged PR names #6136

Admission to an agent lane stays with the work-class rules and owner ratification.

Owner batch-ratified this admission in an attended session on 2026-10-12: work-class: scoped. Rule: class C1-C3, no trust surface, the independent check confirmed the recorded decision, and no owner step remains.

More evidence for the agreed terminology matrix, from a /planning:interview run on 2026-10-18 (Lane Funding), and a scope note from the owner.

What happened: recommendations used labels the session coined (OPS, "funding role", "role slot", "sink"), and "sweep" for three different workflows. The owner accepted a round with "go with recommended" and then had to ask what an OPS account was. A third assumption sweep, run with an explicit coined-term pass, found 20 such terms. The fix was a glossary written into the ledger and agreed as its own question (Q27). The sweep gap itself is fix(planning): interview assumption sweep misses coined terms used as if settled #8314.
Owner's scope note: every interview, however small, should settle an agreed glossary of the terms it relies on: ubiquitous language at session scale. In domain work the same glossary feeds domain modeling (bounded contexts, subdomain language), so the matrix should hand agreed domain terms to /domain-driven-design:curate-language instead of keeping them session-only.
Add to the requested behavior: the ledger template's ## Terminology matrix replaces the ephemeral "Session-shorthand glossary" (context/loop.md), with each row marked session or domain; domain rows go to curate-language when they are agreed. The owner also pointed to Matt Pocock's material on shared language as a reference to check (not yet read).

Decision recorded.

Question: Where does this issue's work land, given the 2026-10-12 split into (a) default question shape and ledger template, (b) terminology and reference gate script, and (c) register recap script, with (b) after (a)?

Owner's answer (2026-10-19): "Go with recommendations." Part (a) is folded into #7475, which lands the whole interview question shape in one change. This issue narrows to parts (b) and (c), and is admitted after #7475 merges. Its acceptance for (b) and (c) is unchanged: a gate check, scripted where the ledger allows (as check-open-questions.sh does for the register), confirms every term in a round has an agreed matrix row or an in-block definition and every factual claim has a reference, before the round is shown; and (c) a register recap script with changed-rows-only recaps and terminal-safe formatting.

The triage sweep dispatched intake triage for this issue (attempt 1 of 2).

Not admitted to the issue lane: a Feature needs an open parent issue a listed human filed that awaits no decision; no trusted-human acceptance criteria: a listed human must put the confirmed - [ ] criteria in the body or post them as their own comment, or, on an issue a listed human filed, intake's newest refinement comment must hold them unedited. Admission takes the issue once each of those is met, when intake triages it again (.github/actions/resolve-config/admission-rules.json).

The latest triage verdict holds nothing: admission moved the issue to status: needs-decision; its comment says why.

Refinement. A read-only run explored this repository, searched its issues and pull requests, and read the allowed docs to draft what follows. On an issue a listed human filed, it counts as the issue's spec once posted, while unedited; it is still model text, so check it.

Intended outcome: Add a terminology and reference gate script and a register recap script for the planning interview skill, after #7475 fixes the ledger shape.

Dependencies

#7475: lands the question shape and the ledger template's Terminology matrix section, which the gate script parses; this issue waits for it to merge.

Related work

feat(planning): show basis outcome chips and lint bare references in interview questions #9804 (related): Closed PR on linting bare references in interview questions; it may overlap the reference check. Whether it merged is not shown.
feat(planning): show the session shorthand glossary on the interview page #9830 (related): Closed PR on showing the session shorthand glossary; it may overlap the matrix replacing the glossary. Whether it merged is not shown.
feat(planning): interview pairs every code with its plain name at every use #7480 (related): Open issue on pairing every code with its plain name, overlapping the terminology matrix.
feat(planning): every /planning:interview recommendation shows its evidence, not bare judgment #6728 (related): Open issue requiring evidence on every recommendation, overlapping the reference-on-every-claim check.
fix(planning): warn on branch source links in interview questions #8234 (related): Closed PR warning on branch source links in questions, adjacent to the reference check.
feat(planning): check draft interview rounds against earlier answers and label sweep rounds #9695 (related): Open issue on checking draft rounds against earlier answers, a possible second user of the gate.

Open questions

Has #7475 merged, so the ledger's Terminology matrix format is fixed for the gate script to parse?
RECOMMENDED: Hold this issue until #7475 merges, then refine again against the merged template. Basis: Decision recorded 2026-10-19; plugins/planning/skills/interview/SKILL.md has no Terminology matrix section on the base checkout, so (a) has not landed there.
Do #9804 and #9830 already cover part of the reference check or the glossary, and did they merge?
RECOMMENDED: Check their merge state; if either merged, drop the overlapping criteria and keep only the gap. Basis: Candidates 9804 and 9830 are closed pull requests whose merge state is not visible to this run.
How must the gate script judge a term or claim: by a fixed machine-readable marker in the question block, or by free-text heuristics?
RECOMMENDED: Require markers: a Definitions block with term rows, and a source or judgment label on each claim, so the check is deterministic like check-open-questions.sh. Basis: plugins/planning/scripts/check-open-questions.sh is the model the owner named; judgment.
Should the recap script be one script or separate from the gate script, and where does it keep the last-recap state for changed-rows-only output?
RECOMMENDED: Two separate scripts, each with a .test.sh like the existing ones; keep last-recap state in the ledger on disk, not in memory. Basis: plugins/planning/scripts/ pairs each check script with a .test.sh; judgment on state.
Is the session or domain marking on matrix rows and the hand-off to /domain-driven-design:curate-language part of this issue?
RECOMMENDED: No: leave it to #7475's template and file a separate issue for the hand-off, since the owner's decision narrowed this issue to (b) and (c). Basis: Decision recorded 2026-10-19 narrows scope to (b) and (c); the 2026-10-18 comment predates it.

Sources read

/home/runner/work/_temp/refine-data/context.json: Decision recorded 2026-10-19 narrows the issue to (b) gate script and (c) recap script, after #7475.
plugins/planning/skills/interview/SKILL.md: has no Terminology matrix section on the base checkout; line 157 and 165 matches are long and were not read in full.
plugins/planning/scripts/: has check-open-questions.sh and its test but no recap or terminology gate script.

_{Automated refinement by the lanes App. Answer with a comment whose first line is **Decision recorded.**.}

Navigation Menu

Repository navigation

feat(planning): interview questions must be self-contained, with an agreed terminology matrix and references #6136

Problem

Requested behavior

Acceptance

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

feat(planning): interview questions must be self-contained, with an agreed terminology matrix and references #6136

Description

Problem

Requested behavior

Acceptance

Activity

kyle-sexton commented on Oct 3, 2026

github-actions commented on Oct 3, 2026

kyle-sexton commented on Oct 3, 2026

kyle-sexton commented on Oct 4, 2026

kyle-sexton commented on Oct 4, 2026

kyle-sexton commented on Oct 13, 2026

kyle-sexton commented on Oct 13, 2026

kyle-sexton commented on Oct 18, 2026

kyle-sexton commented on Oct 19, 2026

github-actions commented on Oct 25, 2026

melodic-automation-lanes commented on Oct 25, 2026

melodic-automation-lanes commented on Oct 25, 2026

melodic-automation-lanes commented on Oct 25, 2026

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions