feat(planning): every interview question opens with the context that drives the decision, with links to verify it #7475

Problem

A /planning:interview question is only the user's decision if the user can decide it from the question alone. In a long design interview (2026-10-14, about 70 questions over 15 rounds, absorbing two upstream workflows), questions with a recommendation, a basis line and alternatives still left the user unable to decide. They had to come back with "what does this term mean?", "is this hers or yours?", "what does this tool actually do?", "what does the upstream source say?", before answering. Several recommendations changed once that context was supplied: for example, a lens name picked only to avoid a folder collision was reversed when the user asked what the word means, and a skill placement was reversed once the scope of each candidate skill was laid side by side.

The rounds that worked were the ones where each question opened with its own context. The user said of them: "I'm armed with enough information to make those decisions now."

The skill today caps a question's own context at one line, usually none (plugins/planning/skills/interview/SKILL.md, "One verdict marker, at most one context line"), and relies on the round-header restate. That cap is what produced the follow-up loops.

Requested behavior

Make a per-question context block the default for every question, on both surfaces (terminal prose rounds and the page):

1. Context first. Before My recommendation:, a Context: block carries everything that drives or influences the decision, and nothing that doesn't:
   • the problem the decision solves, in one or two sentences;
   • what the source material says or ships (upstream docs, a talk, a repo file), paraphrased accurately, with quotes under 15 words where the exact words matter;
   • what exists today on our side, and the gap;
   • for any absorbed idea, whether each part comes from the source or is our addition, labelled;
   • definitions of any term the question relies on that the user may not share.
2. Links to read. Every factual claim carries a link or file:line the user can open to check it (a URL with its section anchor, a timestamp for a video, a repo path). The user must be able to trust the paraphrase and verify it in one click.
3. Bounded, not exploded. The block holds only what changes the decision. A rule of thumb: if removing a line would not change how a reasonable person decides, remove it. Long material goes behind a link, not into the question.
4. Same on the page. The page surface's question card shows the same block (a context field next to facts), so the terminal and browser carry identical information.
5. Alternatives with their tradeoffs. Every question keeps the skill's existing Alternatives to consider list (SKILL.md question shape), and each alternative carries what it would cost, what it would gain, and the source behind that, so it can be weighed against the recommendation. A question with only one viable answer says why the others were ruled out.
6. Basis stays a label; context carries the evidence. The existing Basis: line keeps its job (SKILL.md "Recommended answers"; context/recommendation-basis.md): it labels the recommendation verified with the sources it rests on, or judgment. The links inside Context: are the evidence for each claim; Basis: names which of them the recommendation itself rests on, so the user sees at a glance whether it is grounded or a judgment call.
7. Restatements keep the whole contract. When open questions are shown again (an unanswered-from-last-round list, a condensed table after async input), each still carries its context, its recommendation with Basis:, and its alternatives. Observed in the same session: a condensed table of eight open questions kept the recommendations and dropped both basis and alternatives.
8. Revisions say so. When a recommendation changes after the user asks for context, the question is re-asked with the old and new recommendation and the reason, as the skill already requires for re-emitted recommendations.

Example of the shape that worked

Q55: Should triage gain a cluster step?
Context: <problem>. <what the source does, with link>. <what we have today, with file:line>. <the gap>.
Proposal: <one or two sentences>.
My recommendation: yes. <why>.
Basis: verified, <links>.
Alternatives to consider: ...

Acceptance

• The SKILL.md question shape gains the Context: block and drops the one-line cap; alternatives carry their tradeoffs; restatements keep context, basis and alternatives; the page template gains the matching fields.
• An eval case: a question that rests on an unfamiliar term and an upstream source is asked; the graded reply is answerable without a follow-up question (judge rubric), and every factual claim in it carries a link or file:line (deterministic check).
• /planning:audit-answers reads the context block as the evidence the answer rested on.

Folded scope (owner decision, 2026-10-19)

The owner chose to land the interview question shape in ONE change. This issue now also carries the parts below, quoted or closely paraphrased from their source issues. They are part of this issue's acceptance.

From #6136, part (a): default question shape and ledger template

The owner split #6136 on 2026-10-12 into (a) the default question shape and ledger template, (b) a terminology and reference gate script, and (c) a register recap script, with (b) after (a). Part (a) lands here; (b) and (c) stay on #6136, after this issue merges.

• 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. A 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 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.
• Acceptance (from feat(planning): interview questions must be self-contained, with an agreed terminology matrix and references #6136): 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 decided without asking what something means; the ledger template carries a ## Terminology matrix section.

From #7480: every code with its plain name, and the approved layout

• In every user-facing line (rounds, restatements, recaps, the page, labels, reports), show the human-readable name, never a bare code. When the name is short enough to stand alone, show only the name (scoped-change, not C3); codes live in an agent-facing legend. Pair code and name (C3: scoped change) only where the code itself must be quoted, such as a ledger id the user answers by.
• Define a term inline where the question uses it (head SHA (the commit the PR points at)), so a reader with none of the session's knowledge can answer from that message alone.
• Self-contained is not simplified. Keep the precise technical terms and register; expand a code to its real name, never a metaphor or lay substitute (pr-merge lane, not merge robot). Plain-language simplification happens only when the user asks (/education:explain). The owner said of a metaphor rewrite: "You don't have to dumb it down".
• Checked against: names constraints in words, not ledger ids. The ledger may keep bare ids; anything shown to the person may not.
• Owner-approved layout (2026-10-14). Stay close to it; do not split a question's information across the round:

❓ Q77: <bold one-line question title>
<context: source and what we have today, terms defined inline>
➡️ <recommendation>
Basis: <verified, source | judgment>
Alternatives:
- <option>. <gain>, but <cost>.
- <option>. <gain>, but <cost>.

Alternatives are a bulleted list, one option per bullet with its tradeoff, never a run-on sentence. No --- rule between questions. Rejected the same session: a separate index table and terms table at the top of the round, and per-question alternatives tables.

• A restatement of an open question uses the identical layout (context, recommendation, Basis, alternatives), never a condensed form, unless the user asks or the summary covers answered items only.
• Acceptance (from feat(planning): interview pairs every code with its plain name at every use #7480): SKILL.md states these rules beside the shorthand rule, and the shorthand rule no longer reads as define-once-then-bare; a deterministic check flags a bare code (a token matching a ledger id or shorthand-glossary entry with no name beside it) in a round before it is shown; an eval case shows a round relying on coded terms, graded answerable by a reader with no prior session context, with technical terms preserved.

Not in this issue

• The shared interview page (plugins/planning/shared/**, including shared/web/app.js). Item 4, "Same on the page", applies here to the single-user page only (plugins/planning/surface/). The shared page already stores a context field per question, so it needs only a display change. That change is sequenced after the Shared Interviews session's full-screen Inbox PR, which rewrites app.js.
• feat(planning): interview questions must be self-contained, with an agreed terminology matrix and references #6136 (b) gate script and (c) recap script: stay on feat(planning): interview questions must be self-contained, with an agreed terminology matrix and references #6136, admitted after this merges.
• fix(planning): interview assumption sweep misses coined terms used as if settled #8314 (assumption sweep coined-term category): separate issue, different file.
• feat(planning): interview pairs every code with its plain name at every use #7480's "one presentation per round when async work is pending" rule spans several skills (/discovery:research, /discovery:explore, review fan-outs). It moves to its own issue; see the comment on feat(planning): interview pairs every code with its plain name at every use #7480.

Related

• feat(planning): interview questions must be self-contained, with an agreed terminology matrix and references #6136, feat(planning): interview pairs every code with its plain name at every use #7480 (folded in as above).
• feat(planning): every /planning:interview recommendation shows its evidence, not bare judgment #6728 (every recommendation shows its evidence).