Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/upstream/aihero-course.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion plugins/planning/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
35 changes: 35 additions & 0 deletions plugins/planning/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion plugins/planning/skills/interview/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 2 additions & 0 deletions plugins/planning/skills/interview/context/gotchas.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
1 change: 1 addition & 0 deletions plugins/planning/skills/interview/context/loop.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 3 additions & 1 deletion plugins/planning/skills/plan/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down