docs: improve planning assumption checks (#3629)

.agents/skills/fix/SKILL.md

@@ -35,8 +35,14 @@ If the cause remains uncertain, stop and ask the user.
 
 ## Phase 1: Reconcile specifications
 
-Read `docs/specs/README.md`, the owning system `README.md`, and the relevant
+Run the `/interview-me` assumption check for intended behavior and repair scope.
-requirement and system-design documents. Use this command for discovery:
+Reuse active acceptance criteria for clear regressions. Ask only about material
+choices that evidence and prior instructions do not settle.
+
+Read `docs/specs/README.md`, the owning system index, and the relevant
+requirement and system-design documents. Use the legacy catalog only when the
+system has not migrated.
+Read the owning system `README.md` and use this command for discovery:
 
     python3 scripts/list-docs.py specs --format paths
 

.agents/skills/interview-me/SKILL.md

@@ -1,92 +1,111 @@
 ---
 name: interview-me
-description: Clarify what the user wants before requirements, system design, plans, or code. Use when an ask is underspecified, when the user asks for an interview or stress test, or when important product or architecture assumptions are missing.
+description: Clarify a standalone idea or check assumptions before feature or fix planning. Use focused questions, stress-test intent, and map unresolved decisions for large uncertain initiatives.
 ---
 
 # Interview Me
 
-Use this before `/spec-driven-development`, `/spec`, or `/plan` when the requested outcome is not clear enough to implement without guessing.
+Run the assumption check before requirements, system designs, or implementation
+plans. Reuse settled answers throughout the design package. An assumption check
+does not require an interview when the material choices are already clear.
 
-## When To Use
+For a standalone interview or stress test, clarify intent without automatically
+creating a design package. Skip this workflow for mechanical edits and pure
+information requests.
 
-Use when the ask is missing one or more of:
+## 1. Check assumptions
-- Who the user/operator is
-- Why this matters now
-- What success looks like
-- The binding constraint or tradeoff
-- Explicit out-of-scope boundaries
 
-Skip for mechanical edits, obvious bug fixes, pure information requests, or when the user explicitly asks for speed over clarification.
+Read the request, relevant specifications, source, and tests. Separate:
 
-## Process
+- **Confirmed:** the user explicitly requested or previously settled it.
+- **Verified:** source, tests, or documentation establish a fact. Keep its source
+  reference and distinguish current behavior from intended behavior.
+- **Unresolved:** a choice or missing fact can change behavior, scope, ownership,
+  permissions, persistence, compatibility, or acceptance criteria.
 
-### 1. State A Hypothesis
+State the intended outcome and material unresolved assumptions briefly. Do not
+invent confidence percentages. Investigate facts that available tools can
+resolve before asking the user. Evidence of current behavior is not user
+agreement to preserve it.
 
-Write one sentence plus a confidence number.
+Ask about consequential choices that evidence cannot settle. Choose routine,
+reversible implementation details within the agreed scope. A request for speed
+reduces questions; it does not make an unanswered material choice confirmed.
 
-```text
+For a clear regression, use the active acceptance criterion without asking the
-HYPOTHESIS: You want workspace switching to preserve task context because agents lose momentum when users navigate between workspaces.
+user to define the behavior again.
-CONFIDENCE: 45% - missing: who feels the pain, what "preserve" means, and what counts as done.
-```
 
-### 2. Ask Focused Questions
+## 2. Ask questions in dependency order
 
-Format every question with a guess.
+Identify which decisions depend on other answers. Ask only questions whose
+prerequisites are settled. Use the active harness's user-question tool and obey
+its limits and waiting rules. Ask one to four independent questions per round,
+within those limits. Without a question tool, ask one question at a time in chat
+during a normal interactive session.
 
-```text
+If this is an autopilot root or another non-interactive session with no question
-Q: Is this primarily for human users switching between workspaces, or for office agents operating across workspaces?
+tool, record each unresolved material choice as an assumption. Continue only
-GUESS: Human users, because the pain sounds navigation-related rather than automation-related.
+when the caller permits autonomous planning for that choice and use the most
-```
+conservative reversible option. Otherwise return the assumption as a blocker to
+the caller. Never present an assumption as confirmed, and preserve the normal
+chat fallback for interactive sessions.
 
-If the active harness provides a native user-question UI that supports multiple
+Give each question concrete options, a recommended answer, and a short reason.
-questions in one turn, ask 2-4 focused questions together. Keep each question
+Align the question with the recommendation so agreement has one clear meaning.
-short, include your guess in the prompt or options, and make the options
+Do not ask the user to locate code or supply facts you can investigate.
-concrete enough that the user can answer quickly.
 
-If no multi-question tool is available, ask one question at a time in chat. Do not send a long questionnaire.
+For example, first settle what "preserve task context" includes. Ask about
+retention duration only after the user chooses persistent context.
 
-If a native single-question interaction resolves one material ambiguity, record
+Wait for answers before resolving dependent choices. After each round, update
-that decision and continue when the remaining outcome, success conditions, and
+the remaining questions. If an answer changes an earlier assumption, revisit
-scope are already explicit. Require the full restatement confirmation below
+the affected choices and artifacts. Do not repeat settled questions without new
-only when broad intent is still missing.
+evidence or changed scope.
 
-### 3. Probe Convention-Sounding Answers
+If the initiative has too many dependent unknowns to specify reliable work
+orders, use [decision mapping](references/decision-mapping.md). Ordinary features
+and clear fixes do not need a map.
 
-If the user says "modern", "scalable", "best practice", "dashboard", "robust", or "clean architecture" without concrete outcomes, ask:
+## 3. Stress-test the answers
 
-```text
+Use concrete scenarios to expose material gaps in success, failure, recovery,
-If you did not have to justify this as best practice, what would you actually want?
+and scope. Select scenarios relevant to the request; do not invent adjacent
-```
+features or an exhaustive questionnaire.
 
-### 4. Restate Intent
+Challenge vague terms such as "robust" with an observable outcome. Compare domain
+terms with the owning specifications and any existing glossary. If a term or
+claimed behavior conflicts with those sources, name the conflict and resolve it.
 
-When confidence is high, restate in this shape:
+Distinguish uncertainty that needs evidence from a choice that needs the user.
+If a design question needs an experiment, define the question and observable
+result first. Keep prototypes temporary and separate from production changes.
+Record what the experiment proves and what remains undecided.
 
-```text
+## 4. Capture decisions and continue
-Here's what I think you want:
-- Outcome:
-- User:
-- Why now:
-- Success:
-- Constraint:
-- Out of scope:
 
-Yes / no / refine?
+After each answer, preserve the choice and its reason in the current task notes.
-```
+Use the Kandev task plan when available, preserving user edits. Do not create a
+separate intent document unless requested.
 
-Do not proceed to `/spec`, `/plan`, or implementation until the user explicitly confirms or corrects the restate.
+During authorized specification or planning work, put settled behavior in the
+owning requirement and technical contracts in its system design. Use `/record`
+for significant decisions that meet its ADR criteria. Preserve meaningful
+alternatives and rationale there. Update an existing glossary when terminology
+changes; do not introduce a parallel glossary by default.
 
-## Output
+Keep unresolved choices visibly unresolved. A recommendation, silence, or timeout
+is not confirmation. If the user explicitly delegates a choice, record the
+selected option as an agent decision made under that delegation.
 
-The deliverable is a confirmed statement of intent. If the user wants it
+When intent is clear and no material choice blocks the next design phase,
-persisted, save it only after confirmation. Use `/spec` to update the owning
+finish the interview. This includes success criteria, constraints, and scope.
-system requirement. Do not create a standalone intent document unless the user
+Explicit answers and prior
-explicitly requests one.
+instructions count as confirmation; do not require a second approval of their
+restatement. If broad intent remains ambiguous, ask about the specific remaining
+gap before continuing.
 
-## Red Flags
+Summarize the settled intent and exclusions. If another skill called this check,
-
+return to its current phase without restarting specification or planning.
-- Long open-ended questionnaires with no guesses
+For a direct planning request, continue through `/spec` and `/plan` to the
-- A question with no guess attached
+existing design-package handoff. For a standalone interview, return the clarified
-- Accepting "whatever you think" as confirmation
+intent. Neither path authorizes implementation or delegation.
-- Starting a spec or plan before the user confirms the restate
-- No explicit out-of-scope line

.agents/skills/interview-me/references/decision-mapping.md

@@ -0,0 +1,65 @@
+# Decision mapping
+
+Use this mode for a large initiative whose dependent unknowns prevent reliable
+specifications or work orders. Start with the desired outcome and scope. Keep
+ordinary planning in the main interview workflow.
+
+## Map only what is known
+
+Use a section in the existing Kandev task plan when available. Otherwise use
+working notes. For work that must survive across sessions without that tool,
+use `docs/plans/<initiative>/discovery.md`. Read existing content before updates.
+
+The map contains:
+
+- **Destination:** the outcome this investigation must make possible.
+- **Open decisions:** precise questions, dependencies, evidence needed, and status.
+- **Settled decisions:** short summaries linked to their authoritative artifacts.
+- **Not yet specified:** in-scope areas whose questions depend on earlier answers.
+- **Out of scope:** excluded work and the reason for exclusion.
+
+For each open decision, use a short name and record:
+
+| Field | Content |
+| --- | --- |
+| Question | One decision or factual uncertainty to resolve |
+| Depends on | Questions that must resolve first, or none |
+| Method | Source investigation, external research, prototype, or user question |
+| Status | Open, blocked, or resolved |
+| Resolution | Answer, supporting evidence, and affected artifact links |
+
+An unanswered but precise question belongs in open decisions, even when blocked.
+Use "Not yet specified" only when the question itself is still unclear.
+Do not turn vague areas into speculative implementation tasks.
+
+## Resolve dependencies
+
+Work on questions with settled prerequisites. Investigate facts in the primary
+session. Ask the user about material choices through the interview workflow.
+For a prototype, state the question, smallest experiment, and evidence needed
+before creating temporary files. A prototype does not authorize production code.
+
+After each resolution, revisit dependent questions. Add questions that are now
+precise, update invalidated answers, and remove resolved uncertainty. If a
+question is outside the destination, record its exclusion instead of expanding
+the initiative.
+
+Continue while useful investigation is possible within the authorized scope.
+There is no one-decision-per-session limit. Do not create tracker issues,
+persistent Kandev tasks, additional sessions, or subagents without explicit
+authorization for those operations.
+
+## Return to the design package
+
+Finish discovery when no unresolved decision blocks the requirements, system
+design, or reliable implementation order. Exclude remaining uncertainty from
+the current scope explicitly, or keep the affected work blocked.
+
+Move settled contracts into the owning requirements and system designs. Use
+`/record` only when its ADR criteria apply. Replace detailed map resolutions
+with summaries and links after those artifacts become authoritative.
+
+Continue to `/plan` for implementation work orders. Each work order delivers
+behavior; a discovery question resolves uncertainty. The map is neither an
+implementation plan nor an additional approval checkpoint. Preserve the normal
+design-package handoff before implementation.

.agents/skills/plan/SKILL.md

@@ -45,6 +45,10 @@ docs/plans/<initiative>/task-<NN>-<short-slug>.md
 
 ### 1. Map the change
 
+Run the `/interview-me` assumption check, reusing settled specification choices.
+Resolve material blockers before decomposing the affected work. For large
+uncertain initiatives, use that skill's decision-mapping reference first.
+
 Identify:
 
 - The required outcomes and acceptance criteria.
@@ -205,8 +209,16 @@ Name prior work orders or write `None`.
 Pending.
 ````
 
-Each work order must fit one focused implementation pass. Split work that has
+Each work order must deliver one independently verifiable outcome in one focused
-unrelated outcomes, independent verification, or a title that contains “and.”
+implementation pass. Prefer a narrow end-to-end slice. Split by layer only for
+a real dependency or verification boundary, not because files occupy different
+directories. Title wording does not determine task boundaries.
+
+For broad migrations that cannot proceed in vertical slices, sequence compatible
+expansion, bounded caller migrations, and final removal of the old contract.
+If a batch cannot pass independently, keep it with its required integration in
+one work order. Add only dependencies that actually block the outcome. Preserve
+the exact acceptance IDs, likely files, and verification commands in each work order.
 
 Use `parallel-safe` only when files are disjoint and the tasks share no schema,
 migration, generated contract, lockfile, or package configuration. A wave does

.agents/skills/spec-driven-development/SKILL.md

@@ -59,7 +59,10 @@ implementation package; neither plan replaces the other.
 
 ## Phases 1 to 4: Design
 
-Use `/interview-me` only when the request needs clarification.
+Run the `/interview-me` assumption check before drafting the package. Reuse
+confirmed choices across phases; ask only about material unresolved decisions.
+For large uncertain initiatives, use its optional decision-mapping reference
+before creating detailed work orders. Continue the package once blockers resolve.
 
 Run the `/spec` ownership gate before you choose paths. Search adjacent systems
 for the same capability. Choose the owner from the durable contract, not from

.agents/skills/spec/SKILL.md

@@ -79,9 +79,10 @@ requirements. A new system needs a `README.md` based on the system template.
 
 ### 2. Confirm intent
 
-Use `/interview-me` when a missing product choice changes behavior, ownership,
+Run the `/interview-me` assumption check, reusing answers from earlier phases.
-permissions, persistence, or a public contract. Do not hide an unresolved
+Resolve material choices before writing the affected contract. Preserve settled
-choice in a draft.
+terminology and decision rationale in the owning artifacts through that skill.
+Do not hide an unresolved choice in a draft.
 
 ### 3. Write requirements
 

.agents/skills/using-agent-skills/SKILL.md

@@ -12,7 +12,9 @@ Use this as the routing map for Kandev's local skills. Prefer the repo's existin
 ```text
 Task arrives
 |
-|-- Need to clarify intent first? ----------> /interview-me
+|-- Standalone interview or stress test? --> /interview-me
+|-- Feature/fix planning assumptions? -----> /interview-me (question only material unknowns)
+|-- Large initiative with dependent unknowns? -> /interview-me decision-mapping reference
 |-- Create/change/fix/publish Kandev plugin? -> /create-kandev-plugin plus /fix or /tdd as needed
 |-- New feature or behavior-changing fix? --> /spec-driven-development
 |-- Bug regression? ------------------------> /fix -> requirement/design check -> fix plan/work orders -> /tdd

docs/specs/INDEX.md

@@ -48,4 +48,3 @@ file-size limits.
 Keep system purpose, ownership, exclusions, migration history, and related
 links in each system README. Do not add catalog rows to this page or repeat
 requirement and system-design lists in a system README.
-