From 54657daeede8b5aab747a0699eec7f89b04081af Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Fri, 17 Jul 2026 15:57:55 -0400 Subject: [PATCH 1/7] feat(planning): propagate frontier-rounds cadence to prd, design, plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The one-question-at-a-time cadence the interview skill dropped in 0.13.0 still appeared in sibling skills. prd Step 4, design's collaborative stance, and plan's scope-clarity check and confidence-gate routing now ask in frontier rounds, and all render a round via AskUserQuestion only through the shared use_ask_user_question user config. The plan skill's interview-round description is stated once in context/tag-decisions.md instead of duplicated in SKILL.md. brainstorm's single intake question is intentionally unchanged. Also files the 0.14.0 (architect-to-plan rename) and 0.15.0 (domain-modeling extraction) CHANGELOG entries under their own version headings — both had been folded into the 0.13.0 section while the manifest version advanced. Closes #282 Co-Authored-By: Claude Fable 5 --- plugins/planning/.claude-plugin/plugin.json | 2 +- plugins/planning/CHANGELOG.md | 27 ++++++++++++++++++- plugins/planning/skills/design/SKILL.md | 2 +- .../planning/skills/design/evals/evals.json | 6 ++--- plugins/planning/skills/plan/SKILL.md | 4 +-- .../skills/plan/context/tag-decisions.md | 2 +- plugins/planning/skills/prd/SKILL.md | 4 +-- 7 files changed, 36 insertions(+), 11 deletions(-) diff --git a/plugins/planning/.claude-plugin/plugin.json b/plugins/planning/.claude-plugin/plugin.json index f896d747d..79fb52b57 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.17.0", + "version": "0.18.0", "userConfig": { "use_ask_user_question": { "type": "boolean", diff --git a/plugins/planning/CHANGELOG.md b/plugins/planning/CHANGELOG.md index 448bf1e57..6a4eb52c8 100644 --- a/plugins/planning/CHANGELOG.md +++ b/plugins/planning/CHANGELOG.md @@ -3,6 +3,22 @@ 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.18.0] + +### Changed + +- **Frontier-rounds cadence propagated to sibling skills** (`/planning:prd` Step 4, `/planning:design` + collaborative stance, `/planning:plan` scope-clarity check and confidence-gate interview + round): each asks every settled-prerequisite question as one numbered round with recommendations, + dependent questions waiting on their prerequisites — replacing the one-question-at-a-time cadence + the interview skill dropped in 0.13.0. `/planning:brainstorm`'s single intake question is + intentionally unchanged. +- Siblings now render a round via `AskUserQuestion` only through the same `use_ask_user_question` + user config the interview skill reads (on, and ≤4 independent questions) instead of deciding + prose-vs-card inline. +- The interview-round description in `/planning:plan` is stated once in + `context/tag-decisions.md`; the SKILL.md confidence-gate summary no longer duplicates it. + ## [0.17.0] ### Changed @@ -34,7 +50,7 @@ All notable changes to the `planning` plugin are documented here. Format follows - **Tripwire test** `tests/standards-binding.test.sh` guards the load-bearing grounding markers (heading placement, binding references, ladder-pointer discipline) against future prose edits. -## [0.13.0] +## [0.15.0] ### Changed @@ -46,6 +62,11 @@ All notable changes to the `planning` plugin are documented here. Format follows - **Declared a dependency on `domain-driven-design`**, so installing `planning` auto-installs the glossary steward and the pipeline's inline vocabulary updates (`interview`, `design`) keep working cross-plugin. + +## [0.14.0] + +### Changed + - **BREAKING: `/planning:architect` is renamed `/planning:plan`** (skill directory, frontmatter `name`, and every in-repo reference). The `architect` name was a pre-migration shadow-compromise: before plugins, a flat local skill named `plan` would have collided with surfaces already using @@ -56,6 +77,10 @@ All notable changes to the `planning` plugin are documented here. Format follows `/planning:plan`; no `renames`-map entry is provided (clean break while the marketplace settles). "architect this" remains a trigger phrase in the skill description. +## [0.13.0] + +### Changed + - **`/planning:interview` asks in frontier rounds instead of one question at a time** (behavioral change): each round asks every question whose prerequisites are settled as one numbered set, each with a recommendation; the answers recompute the frontier, and dependent questions wait for the diff --git a/plugins/planning/skills/design/SKILL.md b/plugins/planning/skills/design/SKILL.md index 473791375..306e6b485 100644 --- a/plugins/planning/skills/design/SKILL.md +++ b/plugins/planning/skills/design/SKILL.md @@ -165,7 +165,7 @@ The in-session shortcut to the design→plan gate. Delegate to `/planning:design ## Key behaviors -- **Collaborative always.** Never autonomously decide design. One question at a time, depth-first — resolve the load-bearing question before surfacing the next. Use `AskUserQuestion` when 2-4 discrete choices exist; prose for open-ended questions +- **Collaborative always.** Never autonomously decide design. Ask in frontier rounds — every open thread whose prerequisites are settled surfaces in the same numbered round, each with a recommendation; a thread that depends on an unresolved thread waits for the round after it resolves. Render a round via `AskUserQuestion` only when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on and the round is ≤4 independent questions — inline prose otherwise - **Track resolution status.** Every question and thread gets a status: resolved / directional / deferred. Deferred items carry a research tag describing what external investigation is needed - **Codify rules when discovered.** When discussion surfaces a principle that applies project-wide, suggest codifying it immediately in the project's own rules files - **Incremental artifacts.** Don't produce all artifacts at once. Build them as discussion progresses. Update existing artifacts as decisions evolve. Multi-turn shared artifacts (`design-threads.md` and peers): re-read from disk before every write — another turn or agent may have modified them — and prefer appending or refining over wholesale rewrites diff --git a/plugins/planning/skills/design/evals/evals.json b/plugins/planning/skills/design/evals/evals.json index ccddac4a3..7f3fd9f93 100644 --- a/plugins/planning/skills/design/evals/evals.json +++ b/plugins/planning/skills/design/evals/evals.json @@ -5,7 +5,7 @@ "id": 1, "name": "library-design-collaborative-artifacts", "prompt": "/planning:design library — I'm building a small result/error-handling library and want to figure out the types, contracts, and package topology before planning.", - "expected_output": "The skill decomposes the problem space, opens design threads with tracked resolution status, and builds design artifacts (capability-matrix, type-inventory, design-threads, topology) incrementally through collaborative discussion — one question at a time — rather than autonomously deciding the design.", + "expected_output": "The skill decomposes the problem space, opens design threads with tracked resolution status, and builds design artifacts (capability-matrix, type-inventory, design-threads, topology) incrementally through collaborative discussion — asking in frontier rounds, dependent threads waiting on their prerequisites — rather than autonomously deciding the design.", "files": [], "expectations": [ "Output explores the design collaboratively, asking the user rather than unilaterally deciding the types/boundaries", @@ -17,11 +17,11 @@ "id": 2, "name": "never-autonomously-decides-design", "prompt": "/planning:design module for a new Notifications module — just design the whole thing for me and pick all the types and boundaries yourself.", - "expected_output": "The skill declines to autonomously finalize the design; it surfaces the decisions one at a time with recommendations marked (RECOMMENDED) and their basis, and drives resolution through the user rather than deciding alone.", + "expected_output": "The skill declines to autonomously finalize the design; it surfaces the open decisions as numbered rounds with recommendations marked (RECOMMENDED) and their basis, and drives resolution through the user rather than deciding alone.", "files": [], "expectations": [ "Output does NOT autonomously decide the full design without user input", - "Output surfaces design decisions one at a time with a recommendation marked (RECOMMENDED) and a basis", + "Output surfaces design decisions in numbered rounds, each with a recommendation marked (RECOMMENDED) and a basis", "Output leaves the resolution of each thread to the user's confirmation" ] }, diff --git a/plugins/planning/skills/plan/SKILL.md b/plugins/planning/skills/plan/SKILL.md index fe66ce2eb..7073b80b8 100644 --- a/plugins/planning/skills/plan/SKILL.md +++ b/plugins/planning/skills/plan/SKILL.md @@ -67,7 +67,7 @@ Before planning, verify the knowledge base is ready: Check the topic's contract slice `//design/` (default `docs/topics/`; the memory slice under `contract_tier: local`) for design artifacts OR `design-resolution.md` at that path. If Tier A/B requirements are unmet, **stop** — offer `/design` or document the early-exit artifact. The user may override via `AskUserQuestion` only when they explicitly accept skipping design exploration. `/planning:plan` consumes design artifacts — do not re-derive design inline when design-significant. -- **Is the scope clear?** — If the task is ambiguous, ask clarifying questions before planning. A plan for "improve performance" is useless; a plan for "add a cache to the GetOrderById query handler" is actionable. When 2–4 discrete options exist (e.g. cache scope, eviction policy, key derivation), use `AskUserQuestion`; for open-ended ambiguity use prose, one question at a time +- **Is the scope clear?** — If the task is ambiguous, ask clarifying questions before planning. A plan for "improve performance" is useless; a plan for "add a cache to the GetOrderById query handler" is actionable. Ask the open questions as one numbered round, each with a recommendation; render the round via `AskUserQuestion` only when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on and the round is ≤4 independent questions — inline prose otherwise - **Open Decisions surfaced BEFORE plan body** — scan the resume prompt + conversation context + Brief for unresolved decisions (scope cuts, technique choices, ordering, exclusions) that the downstream plan body would otherwise lock inline. Surface them as a numbered "Open Decisions" block with research-backed recommendations + trade-offs per decision; resolve via `AskUserQuestion` (≤4 decisions) or single-prompt prose (≥5). Resolving once up front is cheaper than iterating during Step 5 approval If prerequisites are missing, state what's needed and offer to run the prerequisite skill. Don't silently skip this step. Note that the `/prd` check is **additive**, not blocking — proceed if the user has product intent locked elsewhere or if the work is engineering-internal. @@ -190,7 +190,7 @@ After the phase plan is locked but before Step 5 approval, compute the execution ### Step 4.6: Tag unilateral decisions -Before Step 5 approval, walk the PLAN body + Handoff section and classify every decision NOT explicit in the brief: `[EXEC-SHAPE]` (your discretion within briefed scope) or `[FALLBACK — confirm or override]` (an invented contingency the brief didn't anticipate); briefed decisions get no tag. **Then apply the confidence gate**: DECIDE only when the basis is evidence captured this session (a codebase pattern read, a research finding, or a directly-on-point project convention) with no surviving reasonable alternative; everything below the bar — judgment calls, sizing guesses, either-would-work placements — routes to an interview round (one question at a time, recommendation + basis) BEFORE the plan locks; hard-to-reverse decisions escalate EARLY regardless of confidence. Full gate, taxonomy, and presentation contract: [context/tag-decisions.md](context/tag-decisions.md). Surface every gate-passed decision at Step 5 in the "Decisions made (gate-passed)" TABLE (Decision | What it changes in the plan | Basis) so the user can override before implementation. +Before Step 5 approval, walk the PLAN body + Handoff section and classify every decision NOT explicit in the brief: `[EXEC-SHAPE]` (your discretion within briefed scope) or `[FALLBACK — confirm or override]` (an invented contingency the brief didn't anticipate); briefed decisions get no tag. **Then apply the confidence gate**: DECIDE only when the basis is evidence captured this session (a codebase pattern read, a research finding, or a directly-on-point project convention) with no surviving reasonable alternative; everything below the bar — judgment calls, sizing guesses, either-would-work placements — routes to an interview round BEFORE the plan locks; hard-to-reverse decisions escalate EARLY regardless of confidence. Full gate, taxonomy, and presentation contract: [context/tag-decisions.md](context/tag-decisions.md). Surface every gate-passed decision at Step 5 in the "Decisions made (gate-passed)" TABLE (Decision | What it changes in the plan | Basis) so the user can override before implementation. ### Step 4.7: Outcome gate (before Step 5 — verify the PLAN, not a recap) diff --git a/plugins/planning/skills/plan/context/tag-decisions.md b/plugins/planning/skills/plan/context/tag-decisions.md index ba24f57f6..376df03d4 100644 --- a/plugins/planning/skills/plan/context/tag-decisions.md +++ b/plugins/planning/skills/plan/context/tag-decisions.md @@ -13,7 +13,7 @@ Full taxonomy for `/planning:plan` Step 4.6. Before Step 5 approval, walk the PL A tag does NOT license deciding. Each `[EXEC-SHAPE]` / `[FALLBACK]` candidate passes the confidence gate first: - **DECIDE (and surface)** only when the basis is evidence captured this session — a codebase pattern read, a research finding, or a directly-on-point project convention — AND no reasonable alternative survives that evidence. -- **INTERVIEW** everything below that bar: queue it and run an interview round (one question at a time, recommendation + basis) BEFORE the plan body locks. Judgment calls, sizing guesses, taste-based placement, and "either would work" choices are below the bar by definition. +- **INTERVIEW** everything below that bar: queue it and run an interview round — every queued question whose prerequisites are settled asked as one numbered set, each with recommendation + basis — BEFORE the plan body locks. Judgment calls, sizing guesses, taste-based placement, and "either would work" choices are below the bar by definition. **Reversibility ceiling on discretion:** a decision that is risky or hard to reverse later (new public contract, irreversible deletion, architecture-shaping placement, dependency adoption) does NOT qualify for deciding regardless of confidence — escalate to `/interview me` (relentless mode) EARLY, before dependent plan work is authored, leading with the best-practice long-term default (never a hack or workaround). Tags cover only decisions cheap to change after the fact. diff --git a/plugins/planning/skills/prd/SKILL.md b/plugins/planning/skills/prd/SKILL.md index f58d1e465..f44b4e4b5 100644 --- a/plugins/planning/skills/prd/SKILL.md +++ b/plugins/planning/skills/prd/SKILL.md @@ -115,11 +115,11 @@ Use when conversation already contains rich product context and re-asking would If after the survey (Step 2) a required section has NO answerable content in the conversation, note it as an open question rather than forcing Q&A. The PRD with open questions is still useful — `/interview` or `/planning:plan` picks them up downstream. -### Step 4 — Drive depth-first Q&A +### Step 4 — Drive frontier-rounds Q&A **Skipped when `synthesize` action was invoked** — go directly to Step 5. -ONE question at a time, depth-first — resolve the load-bearing question, then surface the next; never batch unrelated questions. Use `AskUserQuestion` when there are 2-4 distinct named options the user benefits from seeing side by side; use prose for open-ended questions. +Ask in frontier rounds: each round surfaces every open question whose prerequisites are settled as one numbered set (grouped by PRD section), each with a recommendation; a question that depends on another still open waits for the round after its prerequisite resolves. Render a round via `AskUserQuestion` only when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on and the round is ≤4 independent questions — inline prose otherwise. Question shapes that recur, in priority order: From 55d4b1a9b6a46f43d91f56145797455fc9d6c758 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Fri, 17 Jul 2026 16:09:55 -0400 Subject: [PATCH 2/7] fix(planning): repair manifest description fields scrambled in DDD merge The domain-driven-design extraction merge landed the updated plugin description inside userConfig.use_ask_user_question, overwriting that entry's prompt text, and left the stale pre-DDD text at top level. Restores the userConfig prompt (updated to name all four round-asking skills) and puts the glossary-steward description at top level. Co-Authored-By: Claude Fable 5 --- plugins/planning/.claude-plugin/plugin.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/planning/.claude-plugin/plugin.json b/plugins/planning/.claude-plugin/plugin.json index 79fb52b57..4e3fb2239 100644 --- a/plugins/planning/.claude-plugin/plugin.json +++ b/plugins/planning/.claude-plugin/plugin.json @@ -6,11 +6,11 @@ "use_ask_user_question": { "type": "boolean", "title": "Use AskUserQuestion for interview rounds", - "description": "Pre-implementation planning pipeline: chart a too-big, foggy effort as a decision map, diverge on candidate approaches, lock product intent and the engineering contract, route resolved domain language to the domain-driven-design glossary steward, explore the design space, stress-test adversarially, and produce a structured implementation plan with an approval gate.", + "description": "When enabled, the planning skills' question rounds (interview, prd, design, plan) render a round of up to 4 independent questions through the AskUserQuestion tool instead of inline prose. Default: inline prose (dictation-friendly).", "default": false } }, - "description": "Pre-implementation planning pipeline: chart a too-big, foggy effort as a decision map, diverge on candidate approaches, lock product intent and the engineering contract, actively maintain resolved domain language, explore the design space, stress-test adversarially, and produce a structured implementation plan with an approval gate.", + "description": "Pre-implementation planning pipeline: chart a too-big, foggy effort as a decision map, diverge on candidate approaches, lock product intent and the engineering contract, route resolved domain language to the domain-driven-design glossary steward, explore the design space, stress-test adversarially, and produce a structured implementation plan with an approval gate.", "author": { "name": "Melodic Software", "email": "info@melodicsoftware.com" From f0c83137b34dc272c17dd441c3d4ac2b6fd0b068 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Fri, 17 Jul 2026 16:19:18 -0400 Subject: [PATCH 3/7] chore: regenerate README catalog for updated planning description Co-Authored-By: Claude Fable 5 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index efec789f1..ffd7c1802 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ Browse and manage with `/plugin`. To refresh after updates: `/plugin marketplace - [`architecture`](plugins/architecture) — Scans an existing codebase for module-level architecture friction — shallow modules, seam leaks, and locality gaps — using Ousterhout's deep-module lens, presents candidates as a self-contained HTML report, and runs an interview loop on the selected candidate before handing off for planning. - [`prototype`](plugins/prototype) — Builds throwaway code to answer a design question before committing to architecture — a logic facet (an interactive terminal app over a portable state model) and a UI facet (radically different visual variants on one route). -- [`planning`](plugins/planning) — Pre-implementation planning pipeline: chart a too-big, foggy effort as a decision map, diverge on candidate approaches, lock product intent and the engineering contract, actively maintain resolved domain language, explore the design space, stress-test adversarially, and produce a structured implementation plan with an approval gate. +- [`planning`](plugins/planning) — Pre-implementation planning pipeline: chart a too-big, foggy effort as a decision map, diverge on candidate approaches, lock product intent and the engineering contract, route resolved domain language to the domain-driven-design glossary steward, explore the design space, stress-test adversarially, and produce a structured implementation plan with an approval gate. - [`domain-driven-design`](plugins/domain-driven-design) — Domain-driven-design practice skills. Today: actively maintains a consuming project's ubiquitous-language glossary — resolves ambiguous or overloaded terms, records canonical language and rejected synonyms, sharpens what-it-IS definitions, and routes entries to already-known bounded contexts without discovering boundaries. - [`naming`](plugins/naming) — Generates and evaluates fresh name candidates for anything — an identifier, file, module, skill, repo, or domain term — by fanning out blind, fresh-context generators from distinct lenses (responsibility-literal, moment-of-use, domain-lore), then scoring a shortlist against the consuming org's naming criteria. The human always picks; it never auto-locks a name. An optional tournament mode adds elimination rounds with independent judges for high-stakes, hard-to-refactor names. - [`event-storming`](plugins/event-storming) — EventStorming for domain discovery — a methodology skill (Big Picture / Process Modeling / Design-Level facilitation reference, notation, patterns) and a simulation skill (agentic multi-persona workshops that produce a structured-markdown model by default; a live Miro-board rendering path is available when the first-party miro plugin is enabled). From 3038e454cb37fe86e760914ea4f08ce8f3b8d94f Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Fri, 17 Jul 2026 16:49:51 -0400 Subject: [PATCH 4/7] fix(planning): gate remaining plan-skill card renders on use_ask_user_question MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Open Decisions block, the confidence-gate round in tag-decisions.md, and the stress-test alternatives surface still rendered AskUserQuestion unconditionally; all three now honor the shared opt-in with the ≤4-independent-questions cap and inline-prose fallback. Addresses Codex P2 x2 on PR #294 (both confirmed by claude-review). Co-Authored-By: Claude Fable 5 --- plugins/planning/skills/plan/SKILL.md | 6 +++--- plugins/planning/skills/plan/context/tag-decisions.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/plugins/planning/skills/plan/SKILL.md b/plugins/planning/skills/plan/SKILL.md index 7073b80b8..33b1f0769 100644 --- a/plugins/planning/skills/plan/SKILL.md +++ b/plugins/planning/skills/plan/SKILL.md @@ -68,7 +68,7 @@ Before planning, verify the knowledge base is ready: Check the topic's contract slice `//design/` (default `docs/topics/`; the memory slice under `contract_tier: local`) for design artifacts OR `design-resolution.md` at that path. If Tier A/B requirements are unmet, **stop** — offer `/design` or document the early-exit artifact. The user may override via `AskUserQuestion` only when they explicitly accept skipping design exploration. `/planning:plan` consumes design artifacts — do not re-derive design inline when design-significant. - **Is the scope clear?** — If the task is ambiguous, ask clarifying questions before planning. A plan for "improve performance" is useless; a plan for "add a cache to the GetOrderById query handler" is actionable. Ask the open questions as one numbered round, each with a recommendation; render the round via `AskUserQuestion` only when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on and the round is ≤4 independent questions — inline prose otherwise -- **Open Decisions surfaced BEFORE plan body** — scan the resume prompt + conversation context + Brief for unresolved decisions (scope cuts, technique choices, ordering, exclusions) that the downstream plan body would otherwise lock inline. Surface them as a numbered "Open Decisions" block with research-backed recommendations + trade-offs per decision; resolve via `AskUserQuestion` (≤4 decisions) or single-prompt prose (≥5). Resolving once up front is cheaper than iterating during Step 5 approval +- **Open Decisions surfaced BEFORE plan body** — scan the resume prompt + conversation context + Brief for unresolved decisions (scope cuts, technique choices, ordering, exclusions) that the downstream plan body would otherwise lock inline. Surface them as a numbered "Open Decisions" block with research-backed recommendations + trade-offs per decision; render the block via `AskUserQuestion` only when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on and it holds ≤4 independent decisions — single-prompt inline prose otherwise. Resolving once up front is cheaper than iterating during Step 5 approval If prerequisites are missing, state what's needed and offer to run the prerequisite skill. Don't silently skip this step. Note that the `/prd` check is **additive**, not blocking — proceed if the user has product intent locked elsewhere or if the work is engineering-internal. @@ -219,7 +219,7 @@ Present the final plan to the user. The plan is a proposal, not a commitment — **Presentation order — tweak-likelihood first.** Order the presentation by what the user is most likely to change on review: data-model/schema choices, type interfaces and public contracts, and user-facing surfaces LEAD (flag close calls with their alternatives); mechanical refactoring and low-judgment work sits at the bottom. Presentation order only — phase EXECUTION order stays integration-first per Step 2. Optionally offer a self-contained HTML plan view (decisions-first layout, flagged choices with toggleable alternatives); PLAN.md stays the tracked record. -If 2–4 named alternatives surfaced during the stress-test, present them via `AskUserQuestion` — the side-by-side rendering helps the user pick faster than reading prose alternatives. For open-ended approval (single proposal, no alternatives) use prose. +If 2–4 named alternatives surfaced during the stress-test, present them side by side via `AskUserQuestion` when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on — numbered inline prose otherwise. For open-ended approval (single proposal, no alternatives) use prose. **After approval — branch-name check:** @@ -339,5 +339,5 @@ Lifecycle detail and the redaction bar for committed evidence: [`${CLAUDE_PLUGIN - **Research-iterate has a ceiling.** 3 iterations max before escalating to the user. Infinite loops waste context on diminishing returns. If 3 rounds can't resolve it, the approach may need to change, not just the evidence - **The plan is a proposal.** Never start executing without user approval. The approval gate is the point — it's where human judgment enters the loop - **Step 4.5 (Execution shape) is default ON for ≥2-phase plans.** Skip explicitly only for single-phase plans or trivial fixes — skipped = all-main-session execution, stated in one line -- **Open Decisions resolved BEFORE the plan body is authored.** Surfacing them mid-plan-body forces re-iteration during Step 5. The Step 1 prereq check enforces this — scan the resume prompt + conversation + Brief for unresolved choices; `AskUserQuestion` resolves cheaply +- **Open Decisions resolved BEFORE the plan body is authored.** Surfacing them mid-plan-body forces re-iteration during Step 5. The Step 1 prereq check enforces this — scan the resume prompt + conversation + Brief for unresolved choices; a numbered Open Decisions round resolves cheaply - **Sanity Check criteria are mechanically verifiable.** A future cleared session running the phase's sanity check needs an executable command (grep, Read assertion, build/test exit). Vague criteria invite inferential drift — rewrite as the exact command a reviewer would run diff --git a/plugins/planning/skills/plan/context/tag-decisions.md b/plugins/planning/skills/plan/context/tag-decisions.md index 376df03d4..30151574b 100644 --- a/plugins/planning/skills/plan/context/tag-decisions.md +++ b/plugins/planning/skills/plan/context/tag-decisions.md @@ -13,7 +13,7 @@ Full taxonomy for `/planning:plan` Step 4.6. Before Step 5 approval, walk the PL A tag does NOT license deciding. Each `[EXEC-SHAPE]` / `[FALLBACK]` candidate passes the confidence gate first: - **DECIDE (and surface)** only when the basis is evidence captured this session — a codebase pattern read, a research finding, or a directly-on-point project convention — AND no reasonable alternative survives that evidence. -- **INTERVIEW** everything below that bar: queue it and run an interview round — every queued question whose prerequisites are settled asked as one numbered set, each with recommendation + basis — BEFORE the plan body locks. Judgment calls, sizing guesses, taste-based placement, and "either would work" choices are below the bar by definition. +- **INTERVIEW** everything below that bar: queue it and run an interview round — every queued question whose prerequisites are settled asked as one numbered set, each with recommendation + basis — BEFORE the plan body locks. Render the round via `AskUserQuestion` only when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on and the round is ≤4 independent questions — inline prose otherwise. Judgment calls, sizing guesses, taste-based placement, and "either would work" choices are below the bar by definition. **Reversibility ceiling on discretion:** a decision that is risky or hard to reverse later (new public contract, irreversible deletion, architecture-shaping placement, dependency adoption) does NOT qualify for deciding regardless of confidence — escalate to `/interview me` (relentless mode) EARLY, before dependent plan work is authored, leading with the best-practice long-term default (never a hack or workaround). Tags cover only decisions cheap to change after the fact. From 2f300e5c390aaa34e73cb4da9c9b01f0d2688a63 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Fri, 17 Jul 2026 18:22:04 -0400 Subject: [PATCH 5/7] fix(planning): frontier qualifier on plan scope-clarity; gate prd tier card MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The plan scope-clarity round now restricts each round to settled-prerequisite questions like every sibling, and the prd tier prompt renders a card only under the use_ask_user_question opt-in — the manifest promises inline prose by default for prd surfaces. Addresses Codex P2 + claude-review Finding 1 on PR #294. Co-Authored-By: Claude Fable 5 --- plugins/planning/skills/plan/SKILL.md | 2 +- plugins/planning/skills/prd/SKILL.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/plugins/planning/skills/plan/SKILL.md b/plugins/planning/skills/plan/SKILL.md index 33b1f0769..a07983948 100644 --- a/plugins/planning/skills/plan/SKILL.md +++ b/plugins/planning/skills/plan/SKILL.md @@ -67,7 +67,7 @@ Before planning, verify the knowledge base is ready: Check the topic's contract slice `//design/` (default `docs/topics/`; the memory slice under `contract_tier: local`) for design artifacts OR `design-resolution.md` at that path. If Tier A/B requirements are unmet, **stop** — offer `/design` or document the early-exit artifact. The user may override via `AskUserQuestion` only when they explicitly accept skipping design exploration. `/planning:plan` consumes design artifacts — do not re-derive design inline when design-significant. -- **Is the scope clear?** — If the task is ambiguous, ask clarifying questions before planning. A plan for "improve performance" is useless; a plan for "add a cache to the GetOrderById query handler" is actionable. Ask the open questions as one numbered round, each with a recommendation; render the round via `AskUserQuestion` only when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on and the round is ≤4 independent questions — inline prose otherwise +- **Is the scope clear?** — If the task is ambiguous, ask clarifying questions before planning. A plan for "improve performance" is useless; a plan for "add a cache to the GetOrderById query handler" is actionable. Ask every question whose prerequisites are settled as one numbered round, each with a recommendation — a question that depends on another still open waits for the round after its prerequisite resolves; render the round via `AskUserQuestion` only when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on and the round is ≤4 independent questions — inline prose otherwise - **Open Decisions surfaced BEFORE plan body** — scan the resume prompt + conversation context + Brief for unresolved decisions (scope cuts, technique choices, ordering, exclusions) that the downstream plan body would otherwise lock inline. Surface them as a numbered "Open Decisions" block with research-backed recommendations + trade-offs per decision; render the block via `AskUserQuestion` only when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on and it holds ≤4 independent decisions — single-prompt inline prose otherwise. Resolving once up front is cheaper than iterating during Step 5 approval If prerequisites are missing, state what's needed and offer to run the prerequisite skill. Don't silently skip this step. Note that the `/prd` check is **additive**, not blocking — proceed if the user has product intent locked elsewhere or if the work is engineering-internal. diff --git a/plugins/planning/skills/prd/SKILL.md b/plugins/planning/skills/prd/SKILL.md index f44b4e4b5..9499fd9dd 100644 --- a/plugins/planning/skills/prd/SKILL.md +++ b/plugins/planning/skills/prd/SKILL.md @@ -54,11 +54,11 @@ If ambiguous (could go either way), surface the question once and let the user p ## Action Router -Parse `$ARGUMENTS` to determine the action. Tier choice can be passed as the first argument; if absent, ask via `AskUserQuestion`. +Parse `$ARGUMENTS` to determine the action. Tier choice can be passed as the first argument; if absent, ask for it (surface rules below). | Argument | Action | Use case | |----------|--------|----------| -| *(empty)* | **Smart default** | If a prior PRD exists for the topic, offer resume/revise/start-fresh. Otherwise prompt for tier + task via `AskUserQuestion`. | +| *(empty)* | **Smart default** | If a prior PRD exists for the topic, offer resume/revise/start-fresh. Otherwise prompt for tier + task. | | `` (no tier word) | **Full PRD, prompt for tier** | Run skip-condition check, then ask which template tier (one-pager / consumer-feature / B2B-internal). | | `one-pager ` | **Tier 1 — thin one-pager** | Small feature, single team, fast lock. ~½ page. | | `consumer ` or `consumer-feature ` | **Tier 2 — consumer feature** | User-facing app feature with metrics, user stories, risk surface. ~1 page. | @@ -66,7 +66,7 @@ Parse `$ARGUMENTS` to determine the action. Tier choice can be passed as the fir | `synthesize ` | **Synthesis-only PRD** | Skip Q&A — produce PRD from existing conversation context. Use when conversation already has rich product context and re-asking would waste the user's time. Still runs skip-condition check (Step 1) and survey (Step 2). | | `review` | **PRD review** | Critique an existing PRD.md against template + skip-conditions. | -Tier choice rationale lives in [`context/templates.md`](context/templates.md). When tier is unclear from the task description, present the three tiers via `AskUserQuestion` with one-line descriptions — the side-by-side rendering helps the user choose without skimming docs. +Tier choice rationale lives in [`context/templates.md`](context/templates.md). When tier is unclear from the task description, present the three tiers with one-line descriptions — via `AskUserQuestion` when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on (the side-by-side rendering helps the user choose without skimming docs), numbered inline prose otherwise. ## The PRD process @@ -95,7 +95,7 @@ Survey output is a one-paragraph summary in your reply. Then transition to depth ### Step 3 — Pick the template tier -If not specified in `$ARGUMENTS`, surface tier choice via `AskUserQuestion`: +If not specified in `$ARGUMENTS`, surface the tier choice (card only under the `use_ask_user_question` opt-in; numbered prose otherwise): | Tier | When | |------|------| From f20b77b00bcff666f858500b8d3faeeb03daea9c Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Fri, 17 Jul 2026 18:52:22 -0400 Subject: [PATCH 6/7] fix(planning): scrub depth-first residue; gate plan-mode clarifier cards Two stale depth-first Q&A handoffs in prd (Step 2 transition and the tier-2 template note) now say frontier-rounds, and the plan-mode clarifying-question note renders a card only under the shared use_ask_user_question opt-in. Addresses Codex P2 x2 on PR #294. Co-Authored-By: Claude Fable 5 --- plugins/planning/skills/plan/SKILL.md | 2 +- plugins/planning/skills/prd/SKILL.md | 2 +- plugins/planning/skills/prd/context/templates.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/planning/skills/plan/SKILL.md b/plugins/planning/skills/plan/SKILL.md index a07983948..2314a4792 100644 --- a/plugins/planning/skills/plan/SKILL.md +++ b/plugins/planning/skills/plan/SKILL.md @@ -245,7 +245,7 @@ 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 the canonical surface for `AskUserQuestion`-driven 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. +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 Review Mode diff --git a/plugins/planning/skills/prd/SKILL.md b/plugins/planning/skills/prd/SKILL.md index 9499fd9dd..8ea65d81c 100644 --- a/plugins/planning/skills/prd/SKILL.md +++ b/plugins/planning/skills/prd/SKILL.md @@ -91,7 +91,7 @@ Spend the first turn grounding yourself, in parallel: If a prior `PRD.md` exists for this topic, ask: **resume** (continue from open questions), **revise** (in-place edits, bump `updated:`), or **start fresh** (append a dated restart note capturing why below the PRD's frontmatter, then rewrite; the commit carrying the rewrite states the pivot rationale — the contract is branch-tracked, so git log is the history). -Survey output is a one-paragraph summary in your reply. Then transition to depth-first Q&A. +Survey output is a one-paragraph summary in your reply. Then transition to frontier-rounds Q&A. ### Step 3 — Pick the template tier diff --git a/plugins/planning/skills/prd/context/templates.md b/plugins/planning/skills/prd/context/templates.md index 68ff103ee..18298435f 100644 --- a/plugins/planning/skills/prd/context/templates.md +++ b/plugins/planning/skills/prd/context/templates.md @@ -148,7 +148,7 @@ Each metric must have a measurement window and a numeric or qualitative threshol ### Example shape — "Lyric search with fuzzy matching" -Same structure as above, applied to a music-platform feature. Skip body — agent fills via depth-first Q&A. Key tier-2 differences from tier-1: +Same structure as above, applied to a music-platform feature. Skip body — agent fills via frontier-rounds Q&A. Key tier-2 differences from tier-1: - Multiple user stories (1-2 minimum) covering distinct personas or distinct flows - Metrics table with baseline + target + window (not just threshold) From 2396ada700f10a583d1f4cd1363f6cfc2a37c94e Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Fri, 17 Jul 2026 19:03:04 -0400 Subject: [PATCH 7/7] fix(planning): frontier filter on Open Decisions; opt-in wording in tier helper The Open Decisions block now surfaces only settled-prerequisite decisions (dependent ones wait for the next round), and the PRD tier cheat sheet in templates.md carries the same card-only-under-opt-in wording as the skill body. Addresses Codex P2 x2 (round 4) on PR #294. Co-Authored-By: Claude Fable 5 --- plugins/planning/skills/plan/SKILL.md | 2 +- plugins/planning/skills/prd/context/templates.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/planning/skills/plan/SKILL.md b/plugins/planning/skills/plan/SKILL.md index 2314a4792..e003f45af 100644 --- a/plugins/planning/skills/plan/SKILL.md +++ b/plugins/planning/skills/plan/SKILL.md @@ -68,7 +68,7 @@ Before planning, verify the knowledge base is ready: Check the topic's contract slice `//design/` (default `docs/topics/`; the memory slice under `contract_tier: local`) for design artifacts OR `design-resolution.md` at that path. If Tier A/B requirements are unmet, **stop** — offer `/design` or document the early-exit artifact. The user may override via `AskUserQuestion` only when they explicitly accept skipping design exploration. `/planning:plan` consumes design artifacts — do not re-derive design inline when design-significant. - **Is the scope clear?** — If the task is ambiguous, ask clarifying questions before planning. A plan for "improve performance" is useless; a plan for "add a cache to the GetOrderById query handler" is actionable. Ask every question whose prerequisites are settled as one numbered round, each with a recommendation — a question that depends on another still open waits for the round after its prerequisite resolves; render the round via `AskUserQuestion` only when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on and the round is ≤4 independent questions — inline prose otherwise -- **Open Decisions surfaced BEFORE plan body** — scan the resume prompt + conversation context + Brief for unresolved decisions (scope cuts, technique choices, ordering, exclusions) that the downstream plan body would otherwise lock inline. Surface them as a numbered "Open Decisions" block with research-backed recommendations + trade-offs per decision; render the block via `AskUserQuestion` only when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on and it holds ≤4 independent decisions — single-prompt inline prose otherwise. Resolving once up front is cheaper than iterating during Step 5 approval +- **Open Decisions surfaced BEFORE plan body** — scan the resume prompt + conversation context + Brief for unresolved decisions (scope cuts, technique choices, ordering, exclusions) that the downstream plan body would otherwise lock inline. Surface every decision whose prerequisites are settled as a numbered "Open Decisions" block with research-backed recommendations + trade-offs per decision — a decision whose option set depends on another still open waits for the round after its prerequisite resolves; render the block via `AskUserQuestion` only when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on and it holds ≤4 independent decisions — single-prompt inline prose otherwise. Resolving once up front is cheaper than iterating during Step 5 approval If prerequisites are missing, state what's needed and offer to run the prerequisite skill. Don't silently skip this step. Note that the `/prd` check is **additive**, not blocking — proceed if the user has product intent locked elsewhere or if the work is engineering-internal. diff --git a/plugins/planning/skills/prd/context/templates.md b/plugins/planning/skills/prd/context/templates.md index 18298435f..8b8ae0839 100644 --- a/plugins/planning/skills/prd/context/templates.md +++ b/plugins/planning/skills/prd/context/templates.md @@ -249,7 +249,7 @@ Same structure as above, applied to a B2B internal feature. Tier-3 differences f ## Tier selection cheat sheet -If `/prd` is invoked without an explicit tier, use this to drive the `AskUserQuestion`: +If `/prd` is invoked without an explicit tier, use this to drive the tier prompt (card only under the `use_ask_user_question` opt-in; numbered prose otherwise): | Question | Tier 1 (one-pager) | Tier 2 (consumer-feature) | Tier 3 (B2B-internal) | |----------|--------------------|---------------------------|------------------------|