diff --git a/docs/upstream/aihero-course.md b/docs/upstream/aihero-course.md index ad34080bc6..85c0775891 100644 --- a/docs/upstream/aihero-course.md +++ b/docs/upstream/aihero-course.md @@ -249,8 +249,8 @@ the chain record's "course side UNVERIFIED" caveat on the clear step. | `grill-me` is a user-invoked pointer that calls the model-invoked `grilling` | One skill, three actions (`me`/`auto`/`lock`), user- and model-invocable under trigger discipline | **COVERED** (different shape, deliberate) | His two-skill split expresses his invocation-reach invariant; our single-skill shape predates it and the difference is recorded, not a gap. As-of 2026-08-17 | | Walkthrough machinery (npm run reset, `.agents/skills`, the `/` picker) and the lesson-comments example questions | Course-platform machinery and illustration | **NOT RELEVANT** | No repo counterpart owed. As-of 2026-08-17 | | The loop's "clear" leg (clear your mind between features) | Recommend-clear (never auto-clear) sits post-Brief, licensed by Brief/ledger persistence — which dissolves upstream's own recorded no-ledger complaint | **DELIBERATELY DIFFERENT** (course side resolved) | The chain record carried "course side UNVERIFIED (lesson unreachable)" with a reopen-on-text condition; the condition fired at harvest — the committed lesson paste teaches no clear-step mechanics beyond one sentence plus a dictionary link, so the deliberate difference is confirmed against the actual text and the UNVERIFIED caveat retires. Upstream's own repo docs teach the opposite of a mandatory clear ("Hand the same conversation straight to to-spec"); loop-position nuance recorded. As-of 2026-08-18 | -| Ungrillable question → prototype detour (upstream fires it mid-grilling: "stop grilling… build the throwaway version… come back and answer in one line") | Absent from the interview (grep-confirmed by both audit validators); our route exists only downstream (wayfind / plan / brainstorm) | **ADOPT** | Chain audit finding, upstream-repo-grounded. Filed: [#2998](https://github.com/melodic-software/claude-code-plugins/issues/2998). As-of 2026-08-18 | -| Plan-mode-off while grilling | Beyond upstream's taste point, a mechanical edge the audit surfaced: the ask-time register write is load-bearing and plan mode's read-only enforcement blocks it | **ADOPT** | Includes reconciling `planning:plan`'s clarifying-rounds-in-plan-mode sentence with the lane 4 asset-rush doctrine. Filed: [#2998](https://github.com/melodic-software/claude-code-plugins/issues/2998). As-of 2026-08-18 | +| Ungrillable question → prototype detour (upstream fires it mid-grilling: "stop grilling… build the throwaway version… come back and answer in one line") | Absent from the interview (grep-confirmed by both audit validators); our route exists only downstream (wayfind / plan / brainstorm) | **ADOPT** (delivered) | Chain audit finding, upstream-repo-grounded. Filed: [#2998](https://github.com/melodic-software/claude-code-plugins/issues/2998); delivered by [#3045](https://github.com/melodic-software/claude-code-plugins/pull/3045) — `interview` now carries the detour in "Mid-interview composition" (routing look-and-feel to `/prototype:explore-directions`, logic/state/data-shape to `/prototype:pressure-test`) plus a **Needs-an-artifact** arm in the `context/loop.md` categorization taxonomy; planning 0.32.0. As-of 2026-08-19 | +| Plan-mode-off while grilling | Beyond upstream's taste point, a mechanical edge the audit surfaced: the ask-time register write is load-bearing and plan mode's read-only enforcement blocks it | **ADOPT** (delivered) | Includes reconciling `planning:plan`'s clarifying-rounds-in-plan-mode sentence with the lane 4 asset-rush doctrine. Filed: [#2998](https://github.com/melodic-software/claude-code-plugins/issues/2998); delivered by [#3045](https://github.com/melodic-software/claude-code-plugins/pull/3045) — the gotcha lands in `interview/context/gotchas.md`, and `plan`'s plan-mode round is now scoped to a scoping confirm with substantive rounds routed to `/planning:interview` outside plan mode; planning 0.32.0. As-of 2026-08-19 | | Provenance correction (adjacent, from the chain audit) | SSOT PR-#532 row | **CORRECTED in SSOT** | The row's "ADR 3-gate + glossary purity are house additions" claim is contradicted on current upstream main (`domain-modeling` carries both near-identically); annotated as convergent-or-derived, direction unverifiable. As-of 2026-08-18 | House decisions recorded alongside the rows (Q36-Q37 this run; chain audit 2026-08-18): no term diff --git a/plugins/planning/.claude-plugin/plugin.json b/plugins/planning/.claude-plugin/plugin.json index 003e1ed326..e012268e6e 100644 --- a/plugins/planning/.claude-plugin/plugin.json +++ b/plugins/planning/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "planning", - "version": "0.32.0", + "version": "0.33.0", "userConfig": { "use_ask_user_question": { "type": "boolean", diff --git a/plugins/planning/CHANGELOG.md b/plugins/planning/CHANGELOG.md index 5cbcc3a706..36492031f9 100644 --- a/plugins/planning/CHANGELOG.md +++ b/plugins/planning/CHANGELOG.md @@ -3,6 +3,41 @@ All notable changes to the `planning` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.33.0] + +### Added + +- **The interview can stop grilling and go build one (#2998).** Some questions are ungrillable: the + user has to see a thing and react to it before they know what they think, and another round of + framing will not produce the answer. `interview` now carries that escape. "Mid-interview + composition" routes a look-and-feel question to `/prototype:explore-directions` and a + logic/state/data-shape question to `/prototype:pressure-test` (invoked via the Skill tool when + installed), then returns and answers it in one line; the categorization taxonomy in + `context/loop.md` gains a **Needs-an-artifact** arm beside resolvable / blocked / defer, marked + explicitly as a route rather than a deferral. The prototype is the instrument that produces the + answer, not a deliverable. The detour honors the prototype skills' own model-initiated entry gate: + confirm the spike's scope and checkpoint the interview before handing off, which the ask-time + register write and the per-lock-in ledger/Brief persistence already supply. Adopted from the grilling-family upstream at the course lane 5 audit, + where both validators grep-confirmed the route existed in our fleet only downstream, in + `wayfind` / `plan` / `brainstorm`. + +### Changed + +- **Leave plan mode off while interviewing (#2998).** New `interview` gotcha covering a mechanical + edge beyond upstream's taste point: the ask-time open-question register is a disk write (the + ledger's `## Open-question register` section), and plan mode's read-only enforcement blocks it, + so a round asked under plan mode leaves nothing on disk holding it — the exact failure the + register exists to prevent, reintroduced by the permission mode. +- **`plan`'s plan-mode round is a scoping confirm, not a substitute for the interview (#2998).** + "Plan Mode Integration" previously licensed open-ended clarifying questions inside plan mode, + which sat in tension with lane 4's asset-rush doctrine. That round is now scoped to what the plan + covers, and substantive *what are we building* questions route to `/planning:interview` outside + plan mode — on the register-write mechanics above and on the doctrine that plan mode primes the + run toward producing the asset while the job is still reaching shared understanding. Exiting is + the user's move, stated symmetrically to how the section already handles entering: the skill + toggles no permission mode, so it asks the user to exit (`shift+tab`) and invokes the interview + once they have. + ## [0.32.0] ### Added diff --git a/plugins/planning/skills/interview/SKILL.md b/plugins/planning/skills/interview/SKILL.md index a7f2fc7b79..4c1870db33 100644 --- a/plugins/planning/skills/interview/SKILL.md +++ b/plugins/planning/skills/interview/SKILL.md @@ -291,11 +291,12 @@ knob-picking signals in [`context/session-config.md`](context/session-config.md) | Product intent fuzzy (whose problem, what success) | `/planning:prd` | Upstream of `/planning:interview`; PRD answers *what for whom and why* | | Need codebase grounding | `/discovery:explore` (if installed) | Reads PLAN.md Brief as scope | | Need external evidence | `/discovery:research` (if installed) | Reads PLAN.md Brief as scope | +| A question needs something built to react to | `/prototype:explore-directions` (look and feel) or `/prototype:pressure-test` (logic, state, data shape) (if installed) | Mid-interview detour: confirm scope and checkpoint, build the throwaway, react to it, return and answer in one line | | Plan the implementation | `/planning:plan` | Reads PLAN.md Brief + explore + research findings | | Stress-test the plan | `/planning:devils-advocate` | Adversarial pass on `/planning:plan` output | | Validate the interview's answers via agents | `/planning:audit-answers` | Fresh validators challenge each answer in the filled ledger (hand-answered or auto-accepted); only the doubtful ones return as human questions | | Pause and resume later | `/session-flow:handoff` (if installed) | Captures session state, distinct from the Brief (mid-task pause vs pre-execution intent) | -**Mid-interview composition (`me` mode):** research, exploration, and handoff are not only downstream — invoke them *during* the interview when a recommendation needs external/codebase grounding or when branches outgrow the session. Return to the open branch after. +**Mid-interview composition (`me` mode):** research, exploration, prototyping, and handoff are not only downstream — invoke them *during* the interview when a recommendation needs external/codebase grounding, when a question needs something built to react to, or when branches outgrow the session. Return to the open branch after. **The ungrillable question:** when a look, feel, or behavior question cannot be answered by asking — the user has to see the thing to know what they think — stop grilling and route it to a throwaway prototype: `/prototype:explore-directions` (look and feel) or `/prototype:pressure-test` (logic, state, data shape), invoked via the Skill tool if installed. Those skills gate their own model-initiated entry, so confirm the spike's scope with the user and checkpoint this interview before handing off — the detour leaves an active workflow. Checkpointing is persistence the interview already owes: the question registered `open` at ask-time, plus the ledger and Brief written per lock-in, which is what lets the open branch survive the detour. Then come back and answer the question in one line. The prototype is the instrument that produces the answer, not a deliverable; it is thrown away. `/planning:interview` is sister to `/planning:plan`: one resolves *what*, the other resolves *how*. They share the topic slug, share the directory, feed each other. diff --git a/plugins/planning/skills/interview/context/gotchas.md b/plugins/planning/skills/interview/context/gotchas.md index 91b72aecf2..570ff5544a 100644 --- a/plugins/planning/skills/interview/context/gotchas.md +++ b/plugins/planning/skills/interview/context/gotchas.md @@ -16,6 +16,8 @@ Failure patterns from real sessions. Loaded on demand from `/planning:interview` - **Registering a question only once it is answered** — the register then holds exactly the questions that never needed it, and the gate over it grades nothing. The write belongs at ask-time. +- **Interviewing with plan mode on** — the ask-time register write is a disk write (the ledger's `## Open-question register` section), and plan mode's read-only enforcement blocks it, so the round gets asked with nothing on disk holding it: precisely the failure the register exists to prevent, reintroduced by the permission mode. Plan mode also primes the run to rush toward producing a plan when the job is still resolving *what*. Leave plan mode off while interviewing — it is `/planning:plan`'s mode, not this skill's. + - **Passing `--brief` to the Step 3 gate run** — Step 4 writes PLAN.md, so at Step 3 the file does not exist and a named-but-missing `--brief` exits 2; a first-time interview deadlocks before it can persist anything. Ledger-only at Step 3, `--brief` on the Step 4 re-run. - **Assuming `lock` never needs a register** — a clean lock synthesis writes none, but its STOP-on-gap and the unattended ladder both produce unresolved questions, and a question outside the register is a question outside the gate. diff --git a/plugins/planning/skills/interview/context/loop.md b/plugins/planning/skills/interview/context/loop.md index 739eac762a..a4b770763d 100644 --- a/plugins/planning/skills/interview/context/loop.md +++ b/plugins/planning/skills/interview/context/loop.md @@ -77,6 +77,7 @@ Each open item is one of: - **Resolvable** — the user can answer it now. Ask with recommended answer - **Blocked** — depends on another unresolved decision. Name the blocker +- **Needs-an-artifact** — ungrillable by asking: the answer only arrives once the user reacts to something concrete (a look, a feel, a behavior), and another round of framing will not produce it. Not a deferral — route it to a throwaway prototype now, then answer it in one line. The detour and the skills that own it: SKILL.md "Mid-interview composition" - **Defer-with-assumption** — the user can pick a working assumption, with a known revisit trigger. Capture the assumption and the trigger ("assume Postgres for now; revisit if write throughput exceeds X") - **Defer-fully** — out of scope for this task; record in **Deferred questions** so it doesn't silently become a hidden assumption later diff --git a/plugins/planning/skills/plan/SKILL.md b/plugins/planning/skills/plan/SKILL.md index 19240fd274..e4e459913d 100644 --- a/plugins/planning/skills/plan/SKILL.md +++ b/plugins/planning/skills/plan/SKILL.md @@ -248,7 +248,9 @@ Claude Code's built-in plan mode provides read-only enforcement — Claude reads The skill does not automatically enter plan mode — the user controls permission modes. But if you're about to plan a complex change and are NOT in plan mode, suggest it: "Consider entering plan mode (`shift+tab`) for safe exploration while we design this." -Plan mode is also a natural moment for clarifying questions — if you're entering plan mode for safe exploration during planning, treat it as a license to ask 1–4 clarifying questions before proposing the plan, as one numbered round. The round renders via `AskUserQuestion` only when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on and the questions are independent — inline prose otherwise. +Plan mode is also a natural moment for a **scoping confirm** — if you're entering plan mode for safe exploration during planning, treat it as a license to ask 1–4 questions that settle what this plan covers, as one numbered round before proposing it. The round renders via `AskUserQuestion` only when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on and the questions are independent — inline prose otherwise. + +**Substantive rounds do not belong in plan mode.** A question that resolves *what we are building* — real tradeoffs, contested requirements, anything whose answer changes the plan's shape — routes to `/planning:interview` via the Skill tool, run with **plan mode off**, for two reasons. Mechanically, that skill's ask-time open-question register is a disk write, and plan mode's read-only enforcement blocks it, so questions get asked with nothing on disk holding them. Doctrinally, plan mode primes the run toward producing the plan — the asset rush lane 4 records — when the job is still reaching shared understanding. Plan mode's round confirms scope; it is not a substitute for the interview. **Getting there is the user's move, not yours** — symmetric to entering plan mode above: you do not toggle permission modes, so when plan mode is active and a substantive round comes due, say why and ask the user to exit it (`shift+tab`), then invoke the interview once they have. Do not invoke it from inside plan mode on the assumption the register write will survive — it will not. ## Plan Review Mode