Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
1a56d59
refactor(planning): remove the interview's per-round contradiction pass
kyle-sexton Nov 21, 2026
146fa27
feat(planning): stable question ids with next-id and declared gaps
kyle-sexton Nov 21, 2026
3fd1e7a
Merge remote-tracking branch 'origin/main' into feat/interview-redesign
kyle-sexton Nov 21, 2026
acdc7c3
fix(planning): declared gaps reserve their ids in numbering and next-id
kyle-sexton Nov 21, 2026
9afd621
feat(planning): register tags and round.sh reopen
kyle-sexton Nov 21, 2026
e5b4bb4
feat(planning): exporter gap lines for never-assigned ids, trailing g…
kyle-sexton Nov 21, 2026
a968197
test(planning): rewrite and retire interview eval cases for the redesign
kyle-sexton Nov 21, 2026
b705228
test(planning): add eval cases for the interview redesign
kyle-sexton Nov 21, 2026
0e34c40
fix(planning): reopen keeps stale marks; gate skips only reopened-ans…
kyle-sexton Nov 21, 2026
a02c9dd
feat(planning): round detail levels, scope-check, measures and the qu…
kyle-sexton Nov 21, 2026
a79a6e1
feat(planning): round-file structure check and one label grammar
kyle-sexton Nov 21, 2026
2f8c611
feat(planning): interview flow with gap triage, held questions, a bli…
kyle-sexton Nov 21, 2026
4306c49
fix(planning): interview-recommender inherits the session model
kyle-sexton Nov 21, 2026
defd1c5
fix(planning): round parsers agree on list items and fences; one home…
kyle-sexton Nov 21, 2026
4d13f6a
feat(planning): interview layout at detail levels, opening lines and …
kyle-sexton Nov 21, 2026
a51f6ce
fix(planning): quote-safe expected_outcome in two rewritten eval cases
kyle-sexton Nov 21, 2026
0c3a604
fix(planning): interview single-pacing print, one round order, unatte…
kyle-sexton Nov 21, 2026
cc070c7
fix(planning): lint config for the round-file fixture and a spelling fix
kyle-sexton Nov 21, 2026
22554e0
Merge remote-tracking branch 'origin/main' into feat/interview-redesign
kyle-sexton Nov 21, 2026
f615d91
test(planning): tag the interview run set no-network by a stated rule
kyle-sexton Nov 21, 2026
4771119
chore(work-items): no-release fragment for an eval tag
kyle-sexton Nov 21, 2026
c3ff584
Merge remote-tracking branch 'origin/main' into feat/interview-redesign
kyle-sexton Nov 21, 2026
ab73b6d
fix(planning): question_detail option description inside the 300-char…
kyle-sexton Nov 21, 2026
40b548f
Merge remote-tracking branch 'origin/main' into feat/interview-redesign
kyle-sexton Nov 21, 2026
2db6413
test(planning): align eval cases with the redesign, owner-approved
kyle-sexton Nov 21, 2026
5111ea4
fix(planning): interview skill fixes from the eval diagnosis
kyle-sexton Nov 21, 2026
ac55a03
test(planning): turn cap 30 for the eleven cases raised from 12
kyle-sexton Nov 21, 2026
af667f2
Merge remote-tracking branch 'origin/main' into feat/interview-redesign
kyle-sexton Nov 21, 2026
101a801
fix(planning): code spans without a trailing space (MD038)
kyle-sexton Nov 21, 2026
ead196f
fix(planning): interview fixes from the F1 eval diagnosis
kyle-sexton Nov 21, 2026
63fb202
fix(planning): spell labeled in the interview's doc-only control rule
kyle-sexton Nov 21, 2026
c7d4b3b
Merge remote-tracking branch 'origin/main' into feat/interview-redesign
kyle-sexton Nov 21, 2026
0839b43
fix(planning): enforce four interview rules at the round check
kyle-sexton Nov 21, 2026
1e1c3f3
Merge main into feat/interview-redesign
kyle-sexton Nov 21, 2026
25c9809
fix(planning): close the five interview rule gaps the F3 evals traced…
kyle-sexton Nov 21, 2026
b491e00
test(planning): stop the surface-unset grader failing the resolver's …
kyle-sexton Nov 21, 2026
2c3cf38
test(planning): rewrite context-claims-referenced so it stops backtra…
kyle-sexton Nov 21, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
18 changes: 18 additions & 0 deletions .changes/planning/feat-interview-redesign-07635b38.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
bump: minor
---

### Added

- **Stable question ids.** `round.sh next-id --ledger <ledger> [--dir <data dir>] [--count <n>]` prints the next free ids after the highest one held, and the ledger export keeps every number a ledger row already has instead of renumbering. `check-open-questions.sh` accepts a gap in ids only where a hand-written `- gap | Q<a>-Q<b> | <why>` line declares it, and `export-ledger --ledger` keeps those lines. `export-ledger` and `sync-ledger` write `- gap | Q<a>-Q<b> | never assigned` for ids nothing ever held, never for one the ledger held, and a gap line past the last row reserves those ids.
- **Register tags and `round.sh reopen`.** A register row's resolution can end in `kind::`, `problem::`, `depends::`, `reopened::` and `recheck::` tags, which import and export carry unchanged. `round.sh reopen --ledger <ledger> Q<N> --round <n> --fact-file <file>` reopens an answered row under its own number, keeps the old answer and the fact in `## Reopened answers`, and flags every row built on it with `recheck::`, which blocks `check-open-questions.sh` until `reopen --rechecked` clears it.
- **Round detail levels, `scope-check` and `measures`.** `round.sh show --level full|standard|minimal <round-N.md>` prints a saved round at that detail level (full byte for byte; no level hides the recommendation with its reason, `Withheld:`, `Discovery:`, `Second view:`, `Departs from:`, `Flips if:` or `Commits you to:`), set by the new `question_detail` setting (default `standard`). `round.sh scope-check` prints the counts for a round header's `Scope check:` line, and `round.sh measures` prints rounds, median lines per shown round and reopened answers. `check-round-codes.sh` also fails a question with no single `My recommendation:`, `Withheld:`, `Discovery:` or `Strong answer:` line, and a round header without exactly one `Scope check:` line.
- **Interview flow: gap triage, held questions, a blind recommender and stable ids.** Before round 1, `/planning:interview` sorts every unknown into a lookup, a discovery question or a decision question; when discovery questions exist, round 1 asks only those, open, each with a `Discovery:` line and no recommendation (new `context/lookups.md`). A question a running lookup could change is held on the `Held:` line, at most one dispatch runs per lookup skill, and a fact that contradicts an answer runs `round.sh reopen`. Each round's recommendations come from the new read-only `interview-recommender` agent, which sees the facts, constraints and settled decisions but not the conversation; a differing draft shows as `Second view:` and a departure from a settled decision as `Departs from:`. New ids come from `round.sh next-id`, problems are numbered P1, P2 and tagged on their questions, the round header's `Scope check:` line comes from `round.sh scope-check`, the end sweep reports every finding for the disposition pass to filter, the glossary is read at the start of every interview and a term is written only after the user confirms its restatement, and `/planning:audit-answers` never auto-accepts a `kind:: discovery` row.
- **Interview layout, opening lines and one home per rule.** The round file holds the full question block and the round you see is `round.sh show` output at `question_detail`, with a blank line after the title, the recommendation block and the alternatives, a `---` line between questions and the header's `Scope check:` line; at every level the recommendation's reason ends with its evidence label and source, and "more Q<N>" or "full round" shows the rest. The opening lines now read `Asking here, one round at a time. A local page or a shared session is also available; say which to switch.`, `Questions are saved to <ledger>.` and one `Optional:` line per planner or plugin offer (`surfaces/registry.mjs resolve` gains `--pacing` and `--ledger`), and the glossary plugin is offered when it is not installed. Each rule stated two ways now has one home that the other files link to: round order, ids and gaps, the shared lane's 8-question round cap, when lookups and the passes around the interview run, the three glossaries, scenario ids and when the Brief is persisted. A term's restatement is registered like any question, and a routing suggestion in an intake round is one line, never a `My recommendation:` block. Unattended, an open discovery question is `blocked` with arbiter USER-RESERVED.
- **Interview fixes from the eval run.** `round.sh next-id --round <n> --limit <m>` also prints the round's `Scope check:` line, counting the new rows, so one call serves a round's ids and its header; the skill now states that `--limit` takes the resolved `wayfind_suggest_questions` integer, `27` when no layer sets it. The opening `line` is printed exactly as given, the checklist template is read and written rather than copied by shell, and under `single` pacing the `Later:` line never previews the frontier. A prescribed solution's rethink-or-accept question and a reported problem's instance question go out in the intake round, a doubt about a stated fix is a captured assumption, a rejected technical recommendation gets one crux question, a control read only in a document is `documented, unverified`, facts from the request cite `user, round 1`, unattended runs carry the coverage line word for word, and a scenario walk holds only scenarios the facts settle.
- **Interview fixes from the second eval run.** Every lane, inline rounds included, reads `context/question-shape.md` before its first question, so its Context rules reach the conversation. A Context claim cites its own source, never another question, and facts in a message that resumes past round N cite the round it asks for. A recommendation that leans on a control read only in a document carries `documented, unverified`, a reason resting on a `judgment` line is researched or withheld, a fact a `Second view:` line raises goes on the affected question's `Flips if:` line, and the quality bar is never settled by evidence. The register row's question is the title as shown, and a scenario walk puts each scenario in its own bullet under `Context:` with its own person and amount, day or date, and states no definition first.
- **The round check enforces four interview rules.** `scripts/check-round-codes.sh` fails a `## Terminology matrix` term that a question uses without mentioning it in its own Context (`undefined=`), and with `--pacing single` it fails any header line other than the round title, `Scope check:`, `Later:`, `Held:` and `Settled by evidence:` (`extra=`). It also prints `check=<line>:<name>` self-checks (`own-context-terms`, `flips-if-fact`, `existing-control`, `single-pacing`). They never change the exit code, and the skill sends a round only after each one is answered. Two eval graders now accept what the skill prescribes: the intent question in its yes-accepts form, and the `Pacing:` line beside the surface offer.

### Removed

- **The interview's per-round contradiction pass.** `/planning:interview` no longer dispatches a sub-agent before each round to check the draft against earlier answers. The end sweep still finds contradictions and asks each as one question naming both sides, and an answer that conflicts with an earlier one is still caught when it is given. The legacy eval case `pre-round-contradiction-pass` is removed with it.
7 changes: 7 additions & 0 deletions .changes/session-flow/feat-interview-redesign-3c9e1a52.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- **The workflow navigator points at `/planning:interview` for its own rules.** The interview stage in `context/steps.md` and the ladder in `context/pre-implementation-order.md` no longer restate how the interview paces its questions or when explore, research, a PRD or a prototype runs around it; both name `/planning:interview` as the owner of those rules.
5 changes: 5 additions & 0 deletions .changes/work-items/feat-interview-redesign-559d7912.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
bump: none
---

No release: the eval case `decompose-decisions-no-coined-ids` gains the `no-network` tag, which only the eval validity check reads; no shipped file changes.
4 changes: 2 additions & 2 deletions docs/contracts/verification-level/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,8 +77,8 @@ deliverable is not governed. These skills do not read the level: `/planning:audi
`/performance:verify`, `/discipline:scrutinize-dont-coast`, `/review:quality-gate`,
`/review:fanout`, `/planning:devils-advocate`, `/review:security-review` and
`/planning:interview`. Each is itself the independent check when invoked, except
`/planning:interview`, whose contradiction pass, assumption sweep and quote check produce the
questions it exists to ask.
`/planning:interview`, whose assumption sweep and quote check produce the questions it exists to
ask.

`/coupling:reduce` and the conventions lens of `/architecture:improve` do not read it either:
reproducing a scan finding produces the finding they apply or propose for recording, so it runs on
Expand Down
11 changes: 11 additions & 0 deletions plugins/planning/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,17 @@
"auto"
]
},
"question_detail": {
"type": "string",
"title": "Interview question detail",
"description": "How much of each question /planning:interview prints: standard (default; hides Origin, Basis, Checked against and the source quote), full (the whole block) or minimal (answer lines and an alternatives count). The round file keeps the full block; a session request or planning.yaml overrides it.",
"default": "standard",
"options": [
"full",
"standard",
"minimal"
]
},
"use_ask_user_question": {
"type": "boolean",
"title": "AskUserQuestion question rounds",
Expand Down
1 change: 1 addition & 0 deletions plugins/planning/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,7 @@ these and hands them to the plugin, see [User configuration](https://code.claude
| --- | --- | --- | --- |
| `surface` | string | `"terminal"` | Where /planning:interview asks its rounds: terminal (default, inline) or page (a local 127.0.0.1 page the session watches). Unset: terminal, and the interview names the other available surfaces in one line. |
| `question_pacing` | string | `"round"` | How /planning:interview asks a frontier: round (default, one message), single (one question per message, largest blast radius first) or auto (single for a broad, open-ended topic, else round). A session request overrides it there; a repository's planning.yaml overrides this value. |
| `question_detail` | string | `"standard"` | How much of each question /planning:interview prints: standard (default; hides Origin, Basis, Checked against and the source quote), full (the whole block) or minimal (answer lines and an alternatives count). The round file keeps the full block; a session request or planning.yaml overrides it. |
| `use_ask_user_question` | boolean | `false` | When enabled, the planning skills' question rounds (interview, prd, design, plan) render a round of independent questions that fits one AskUserQuestion call instead of inline prose. Default: inline prose (dictation-friendly). |
| `use_emoji_question_markers` | boolean | `true` | When on, each interview round question leads with a ❓ anchor on its Q<N> line and its My recommendation line leads with ➡️, in the terminal and on the page surface. Purely presentational: persisted artifacts never carry the emoji. Default: on; turn off for plain text. |
| `shared_session_open_browser` | boolean | `true` | When on, starting a /planning:interview shared session opens the owner's page in the default browser. Turn off to open it yourself. Default: on. |
Expand Down
37 changes: 37 additions & 0 deletions plugins/planning/agents/interview-recommender.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
---
name: interview-recommender
description: "Blind recommender for a /planning:interview round: given the round's decision questions with their facts, the constraint ledger and the settled decisions, but none of the conversation, returns one recommendation per question with its basis and any departure from a settled decision. Read-only. Dispatched by the interview skill's Step 2; not intended for direct ad-hoc use."
tools: "Read, Grep, Glob"
model: inherit # reason: the recommendation should come from the session's own model, so no model is named here
maxTurns: 15
---

You recommend an answer to each decision question of one interview round. You start with no
conversation history, by design: you never see what the user said, how the session reasoned, or
which answer the session would pick, so your recommendation rests only on the evidence below.

Your prompt carries:

- the round's decision questions, each with its id, its wording, its options (unranked) and its
Context facts, every fact with its source;
- the constraint ledger rows;
- the settled decisions: each answered question with its answer;
- the self-answered facts, each with its source.

Read a cited source when a fact's wording leaves the answer open; read nothing the prompt does not
point at. Recommend from these facts only, never from recall or convention. Treat a settled
decision as an input you may depart from, not as closed: when the facts point away from one, say
so. When no fact settles a question, withhold the recommendation and name the evidence that would.

Return one line per question, in the prompt's order, and nothing else: no reasoning, no preamble.

```text
Q<N> | recommend: <answer> | basis: <the facts it rests on, each with its source> | flips if: <a fact the user can confirm, or none> | departs from: <Q<M>: one sentence, or none>
Q<N> | withheld: <the evidence that would settle it>
```

**Model.** We set `model: inherit` and no `effort`: the recommender inherits the session's model,
so it judges at the session's own level, and this file names no model.

- **Pointer:** for what `inherit` and an absent `effort` field mean, see
[create custom subagents: choose a model](https://code.claude.com/docs/en/sub-agents#choose-a-model).
17 changes: 10 additions & 7 deletions plugins/planning/context/problem-framing.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,18 +47,21 @@ the Brief.
A request that names a solution and no problem ("add a retry wrapper") gets its problem worked
back out: what failure or gap would this solution fix? State that problem with its evidence
rating, then ask one question: rethink the approach against the problem, or accept the prescribed
solution. An attended run always asks, however obvious the problem looks. A request that states
its problem is restated and confirmed, and gets no rethink-or-accept question: its named solution
is accepted. No question reopens it, including one that asks to choose or settle the mechanism
solution. An attended run always asks, however obvious the problem looks; in `/planning:interview`
outside `lock` this is the intake round's problem question, asked open in discovery shape
([`../skills/interview/context/lookups.md`](../skills/interview/context/lookups.md) "The intake
round"). A request that states its problem is restated and confirmed, and gets no
rethink-or-accept question: its named solution is accepted. No question reopens it, including one that asks to choose or settle the mechanism
against an alternative (a durable queue instead of the named wrapper); questions about the
solution stay on its parameters. A concern that the solution may not cover the problem is recorded
under `### Captured assumptions` with the condition that would revisit it, and stated in one line,
never asked.
under `### Captured assumptions` with the condition that would revisit it, never asked; a round
states it in at most one line, which names no other cause and no other approach.

## Reported-only evidence

A stated problem whose evidence is only `reported` gets one instance question, asked with the
restatement: the last concrete instance, what it cost, and who hit it. It is one question, never
A stated problem whose evidence is only `reported` gets one instance question, paired with the
restatement's confirmation ask: one question that asks the user to confirm the restated problem
and to give the last concrete instance, what it cost, and who hit it. It is one question, never
a why chain, and it asks about the problem's evidence only: it never reopens the named solution.
Under `lock` it joins the one confirmation question. The answer rewrites the Evidence line (an
artifact the user points at is `observed`; an instance the user recounts stays `reported`), and no
Expand Down
6 changes: 5 additions & 1 deletion plugins/planning/context/recommendation-basis.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,11 @@ convention, with its boundary and adopters, is
bar; any other may rest on judgment if its label says so.
- **Three outcomes.** Every recommendation ends in exactly one:
- **verified**: presented with `Basis: verified` plus what verified it (a
`file:line`, tool output, or URL fetched this session);
`file:line`, tool output, or URL fetched this session). A source verifies
what it holds, not what it describes: a control (a protection, ruleset,
check or policy) read only in a document, not in its enforcing source (the
ruleset, the workflow, the setting a tool reports), is labelled
`documented, unverified` with the document's `file:line`, never `verified`;
- **judgment**: presented with `Basis: judgment`; only for a
recommendation that is not consequential;
- **withheld**: a consequential recommendation that cannot be settled. It
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
schema_version: "1.1"
name: brainstorm-spec-stage-no-candidates
description: A spec-stage interview request that states its problem and a solution gets no candidate list and no reopened mechanism, because the idea-stage rule does not apply to it. Needs --allow-tools Write.
tags: [interview, brainstorm, problem-framing, stated-problem, scaffold]
tags: [interview, brainstorm, problem-framing, stated-problem, scaffold, no-network]
expected_outcome: The reply lists no alternative approaches, asks no question that reopens streaming the export as the fix, does not run the brainstorm skill, and writes no PLAN.md; it may restate the problem and ask about the streaming change's details.
context:
scaffold_script: scaffold.sh
Expand Down
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
schema_version: "1.1"
name: interview-adr-verdict-overruled
description: "The closing restatement gave a 'no ADR' verdict on a decision and the user overrules it in the reply that confirms the rest. Why hard: the reply reads as a plain confirmation, so the easy path writes the Brief and drops the overrule, or argues the verdict again instead of handing the decision over."
tags: [interview, confirmation, adr, closing-summary]
tags: [interview, confirmation, adr, closing-summary, no-network]
expected_outcome: "The overruled decision (where failed deliveries are stored) goes to /architecture:record-decision with its rationale and alternatives, or, when that skill is not available, is recorded as an ADR candidate in its register row with that said; the verdict is not argued again."
execution:
prompt: "/planning:interview Add retries to the partner webhook sender.\n\nWhere we are: an engineering session, domain_docs is auto. Every question is answered and the assumption sweep added nothing. Your closing restatement listed these ADR verdicts: Q1 retry count: no ADR, no real alternative weighed. Q2 backoff schedule: no ADR, no real alternative weighed. Q3 failed-delivery storage: you recommended a Postgres table over a Redis stream and I agreed; verdict no ADR, weighed but easy to reverse. Q4 alert channel: no ADR, a process decision.\n\nMy reply: Q3: record it. The rest is confirmed."
prompt: "Use the interview skill from the planning plugin: Add retries to the partner webhook sender.\n\nWhere we are: an engineering session, domain_docs is auto. Every question is answered and the assumption sweep added nothing. Your closing restatement listed these ADR verdicts: Q1 retry count: no ADR, no real alternative weighed. Q2 backoff schedule: no ADR, no real alternative weighed. Q3 failed-delivery storage: you recommended a Postgres table over a Redis stream and I agreed; verdict no ADR, weighed but easy to reverse. Q4 alert channel: no ADR, a process decision.\n\nMy reply: Q3: record it. The rest is confirmed."
allowed_tools: [Read, Glob, Grep, Skill, Bash, Write, Edit]
max_turns: 20
timeout_seconds: 900
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
schema_version: "1.1"
name: interview-bare-vague-build-asks
description: A bare vague build request with no slash command gets a question about the problem or scope before any source is written
tags: [interview, bare-prompt, vague-build, scaffold]
tags: [interview, bare-prompt, vague-build, scaffold, no-network]
expected_outcome: The reply asks the user about the problem, the users or the scope of notifications (which events, which channel, who receives them) before building; no Write or Edit touches a file under src/.
context:
scaffold_script: scaffold.sh
Expand Down
Loading
Loading