feat(planning): interview pairs every code with its plain name at every use #7480

Problem

/planning:interview rounds use short codes (work classes C1-C5, decision ids, constraint ids like C1 on a Checked against: line, candidate ids like K37) without their meaning. The user context-switches across sessions and reads only the latest message, so a code defined once, earlier, is undefined by the time it is read. Observed 2026-10-14: a merge-evidence round used work-class codes and constraint codes that share the same letters; the owner could not read it ("I don't know what those are... someone who has no idea what this stuff is can come in and understand").

The skill's "Define session shorthand once, then park it" rule (SKILL.md) defines a term at first use only; #6136's terminology matrix also defines once. Neither covers a reader arriving mid-session.

Requested behavior

• 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 an agent can reverse-map. 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 built-in 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 for it (/education:explain). Observed the same day: a rewrite that swapped real terms for metaphors drew "You don't have to dumb it down".
• Checked against: names constraints in words, not ledger ids (the page wording lint already flags a bare C<N>; the terminal shape should match).
• The ledger may keep bare ids; anything shown to the person may not.

Layout (owner-approved shape, same day)

Stay close to the existing question shape; 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. How many and how much detail scales with the question's size, scope and complexity.
• No --- rule between questions: the emoji markers and the bold question title already separate them.
• Rejected in the same session: a separate index table and terms table at the top of the round, and per-question alternatives tables. They separate information from the question that needs it.

One presentation per round when async work is pending

Observed the same day: a round (Q86-Q89) was shown while research agents were still running; their results then arrived as a second set (Q78, Q90-Q97) in a later message, so the open questions were split across messages and the owner had to scroll back to find them.

• When dispatched agents, background tasks or lookups could change or add to the questions, hold the round until they finish and present every open item once, at the end. A status note while waiting is fine; a partial question set is not.
• If something must be shown before everything is in, the final message restates every open item in full, so the latest message is always the complete set.
• A restatement of an open question uses the identical question layout (context, recommendation, Basis, alternatives), never a condensed form. Condense only when the user asks, or in a summary of items already answered. Observed the same day: a restatement dropped context and Basis lines and drew "Now you change the format on the restate". feat(planning): every interview question opens with the context that drives the decision, with links to verify it #7475 item 7 states the same rule for content.
• This conflicts with the interview's "Out-of-band drift ... never hold the round" rule and the frontier-rounds "do not wait for the lookup" rule; resolve it in favor of one complete presentation when a pending result could reshape the round.
• Scope: every skill that dispatches async agents and then presents results or decisions (/planning:interview, /discovery:research, /discovery:explore, review fan-outs). Consider a shared convention rather than per-skill text.

Acceptance

• SKILL.md states the rules beside the shorthand rule; 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: a round relying on coded terms, graded answerable by a reader with no prior session context, with technical terms preserved.

Related

• feat(planning): interview questions must be self-contained, with an agreed terminology matrix and references #6136 (terminology matrix, self-contained questions): this adds the at-every-use pairing feat(planning): interview questions must be self-contained, with an agreed terminology matrix and references #6136 does not require.
• feat(planning): every interview question opens with the context that drives the decision, with links to verify it #7475 (per-question context block).
• feat(planning): interview rounds a person can answer in batches: topic groups, an index, a discussing status, held and origin lines, one-at-a-time #7478 (round ergonomics).

🤖 Generated with Claude Code

https://claude.ai/code/session_01J5d23i6K8cwkJC4ZFxVyJh