pan-wizard 3.36.0 → 3.37.0

package/pan-wizard-core/workflows/help.md

@@ -36,26 +36,26 @@ Best for: new projects, structured milestones, large multi-phase builds.
 Best for: existing projects, ongoing maintenance, iterative improvement, batch work sessions.
 
 ```
-/pan:focus-scan            # 1. SCAN — find all work items, prioritize, score
+/pan:focus-auto --step scan            # 1. SCAN — find all work items, prioritize, score
   /clear
-/pan:focus-plan            # 2. PLAN — budget items into a sized batch
+/pan:focus-auto --step plan            # 2. PLAN — budget items into a sized batch
   /clear
-/pan:focus-exec            # 3. EXEC — implement, test, verify, commit
+/pan:focus-auto --step exec            # 3. EXEC — implement, test, verify, commit
   /clear
-/pan:focus-sync            # 4. SYNC — update docs to match changes
+/pan:focus-docs --sync            # 4. SYNC — update docs to match changes
 ```
 
 **focus-design** is a standalone command for deep feature investigation:
 ```
 /pan:focus-design "Add webhook support"  # Research, design, spec, ADR
   /clear
-/pan:focus-scan                          # Re-scan to pick up new tasks
+/pan:focus-auto --step scan                          # Re-scan to pick up new tasks
 ```
 
 **Documentation quality commands:**
 ```
-/pan:focus-drift-walking                 # Walk project tree, detect doc-code drift
-/pan:focus-doc-audit                     # Deep document audit with quality scoring
+/pan:focus-auto --step drift                 # Walk project tree, detect doc-code drift
+/pan:focus-docs                     # Deep document audit with quality scoring
 ```
 
 ---
@@ -68,30 +68,30 @@ Already have a codebase? Here's how to get started:
 |-----------|---------|
 | Quick one-off fix or small feature | `/pan:quick "add logout button"` |
 | Need to design a feature first | `/pan:focus-design "Add webhook support"` |
-| Find and fix bugs, tech debt, gaps | `/pan:focus-scan` → `plan` → `exec` |
+| Find and fix bugs, tech debt, gaps | `/pan:focus-auto --step scan` → `plan` → `exec` |
 | Large feature needing multiple phases | `/pan:milestone-new` |
 | Continuous automated improvement | `/pan:focus-auto` |
 
 **Most common path — iterative improvement:**
 ```
-/pan:focus-scan       # 1. Find work items (bugs, TODOs, gaps, features)
+/pan:focus-auto --step scan       # 1. Find work items (bugs, TODOs, gaps, features)
   /clear
-/pan:focus-plan       # 2. Budget a batch (--mode features for feature work)
+/pan:focus-auto --step plan       # 2. Budget a batch (--mode features for feature work)
   /clear
-/pan:focus-exec       # 3. Implement, test, commit
+/pan:focus-auto --step exec       # 3. Implement, test, commit
   /clear
-/pan:focus-sync       # 4. Update docs to match
+/pan:focus-docs --sync       # 4. Update docs to match
 ```
 
 **Design-first path — new feature on existing codebase:**
 ```
 /pan:focus-design "Add webhook support"   # Research → spec → ADR
   /clear
-/pan:focus-scan                           # Picks up tasks from spec
+/pan:focus-auto --step scan                           # Picks up tasks from spec
   /clear
-/pan:focus-plan --mode features           # Budget toward feature work
+/pan:focus-auto --step plan --mode features           # Budget toward feature work
   /clear
-/pan:focus-exec                           # Build it
+/pan:focus-auto --step exec                           # Build it
 ```
 
 **Large feature path — structured milestone on existing codebase:**
@@ -111,7 +111,7 @@ Already have a codebase? Here's how to get started:
 
 The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step feeds the next.
 
-### Step 1: `/pan:focus-scan`
+### Step 1: `/pan:focus-auto --step scan`
 
 **What it does:** Deep-dives into your entire codebase — reads every module, greps for TODOs/FIXMEs, runs tests, checks coverage gaps, reads your roadmap — then produces a prioritized work list.
 
@@ -119,7 +119,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **Reality Score:** Every P3-P6 item gets scored: `RS = (User Value + Time Criticality + Risk Reduction) / Job Size`. Items below RS 3.0 get deferred, below 1.5 get dropped.
 
-**Output:** the prioritized work list, returned by `pan-tools focus scan` as JSON (`/pan:focus-plan` collects the items again itself).
+**Output:** the prioritized work list, returned by `pan-tools focus scan` as JSON (`/pan:focus-auto --step plan` collects the items again itself).
 
 **Flags:**
 - `--quick` — skip strategic analysis and validation phases
@@ -127,7 +127,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 - `--focus <area>` — weight items toward a specific area
 - `--refresh` — force re-read all files
 
-### Step 2: `/pan:focus-plan`
+### Step 2: `/pan:focus-auto --step plan`
 
 **What it does:** Reads the scan output and selects a right-sized batch of work items that fits within a point budget. Orders items for maximum impact with minimum risk.
 
@@ -143,14 +143,14 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **Point system:** XS=1, S=2, M=4, L=10, XL=20 points.
 
-**Output:** `.planning/focus/batch-<date>.json` — the execution batch that `/pan:focus-exec` reads.
+**Output:** `.planning/focus/batch-<date>.json` — the execution batch that `/pan:focus-auto --step exec` reads.
 
 **Flags:**
 - `--mode <mode>` — select execution mode (default: balanced)
 - `--budget N` — override point budget (5-100)
 - `--lean` — exclude items with RS < 1.5
 
-### Step 3: `/pan:focus-exec`
+### Step 3: `/pan:focus-auto --step exec`
 
 **What it does:** One-command pipeline that implements every item in the batch. Runs 6 stages automatically:
 
@@ -175,7 +175,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 - `--continue` — resume a previously interrupted run
 - `--dry-run` — show stages 1-2 only
 
-### Step 4: `/pan:focus-sync`
+### Step 4: `/pan:focus-docs --sync`
 
 **What it does:** Checks all documentation for staleness and fixes it. Compares actual command counts, module counts, test counts against what docs claim.
 
@@ -221,12 +221,12 @@ Every shipped command, by group. This list is generated from each command's own
 ### Phase Lifecycle
 | Command | Description |
 |---------|-------------|
+| `/pan:autodev` | Run the roadmap unattended — a deterministic loop that plans, executes, verifies and completes phase after phase, each step in a fresh host session, and stops in code |
 | `/pan:design-phase` | Design a roadmap phase before planning — architecture, ADR, threat-lite, machine-checkable criteria — verified by an independent checker |
 | `/pan:discuss-phase` | Gather phase context through adaptive questioning before planning |
 | `/pan:exec-phase` | Execute all plans in a phase with wave-based parallelization |
 | `/pan:plan-phase` | Create detailed phase plan (plan.md) with verification loop |
-| `/pan:research-phase` | Research how to implement a phase (standalone - usually use /pan:plan-phase instead) |
-| `/pan:verify-phase` | Re-run goal-backward verification of a phase with a test-suite gate and list its gaps |
+| `/pan:verify-phase` | Re-run goal-backward verification of a phase with a test-suite gate and list its gaps, or walk its UAT with --uat |
 
 ### Phase Management
 | Command | Description |
@@ -242,7 +242,6 @@ Every shipped command, by group. This list is generated from each command's own
 | Command | Description |
 |---------|-------------|
 | `/pan:pause` | Create context handoff when pausing work mid-phase |
-| `/pan:profile` | Switch model profile for PAN agents (quality/balanced/budget) |
 | `/pan:progress` | Check project progress, show context, and route to next action (execute or plan) |
 | `/pan:quick` | Execute a quick task with PAN guarantees (atomic commits, state tracking) but skip optional agents |
 | `/pan:resume` | Resume work from previous session with full context restoration |
@@ -251,9 +250,7 @@ Every shipped command, by group. This list is generated from each command's own
 | Command | Description |
 |---------|-------------|
 | `/pan:milestone-audit` | Audit milestone completion against original intent before archiving |
-| `/pan:milestone-cleanup` | Archive accumulated phase directories from completed milestones |
 | `/pan:milestone-done` | Archive completed milestone and prepare for next version |
-| `/pan:milestone-gaps` | Create phases to close all gaps identified by milestone audit |
 | `/pan:milestone-new` | Start a new milestone cycle — update project.md and route to requirements |
 
 ### Milestone Lifecycle
@@ -266,12 +263,7 @@ Every shipped command, by group. This list is generated from each command's own
 |---------|-------------|
 | `/pan:focus-auto` | Continuous scan-plan-exec loop with purpose-driven categories and a layered safety harness |
 | `/pan:focus-design` | Strategic 10-phase feature investigation, design, and specification pipeline |
-| `/pan:focus-doc-audit` | Multi-dimensional document audit — accuracy, freshness, links, cross-consistency, and structural quality |
-| `/pan:focus-drift-walking` | Deep documentation-code drift detection, CLAUDE.md alignment, and auto-repair across all project directories |
-| `/pan:focus-exec` | Automated batch execution pipeline with 6 stages, behavioral rules, 3 execution tiers |
-| `/pan:focus-plan` | Create capacity-budgeted work batch with spec coverage verification and 4 execution modes |
-| `/pan:focus-scan` | Deep-dive strategic work scan with prioritized items and Reality Score filtering |
-| `/pan:focus-sync` | Synchronize documentation after changes — check staleness and update counts |
+| `/pan:focus-docs` | Documentation audit and sync — accuracy, freshness, links, cross-consistency and structure; --sync updates stale docs after changes |
 
 ### Foresight
 | Command | Description |
@@ -293,7 +285,6 @@ Every shipped command, by group. This list is generated from each command's own
 | Command | Description |
 |---------|-------------|
 | `/pan:cost` | Show token usage and estimated cost across PAN commands and agents |
-| `/pan:dashboard` | Alias for /pan:hud — generate the single-page HTML dashboard of the bot army and project |
 | `/pan:hud` | Generate a single-page, self-contained HTML dashboard of the bot army and the project's current state |
 | `/pan:report` | Generate a self-contained HTML report for one phase, or a project-level timeline index linking every phase report |
 
@@ -307,7 +298,6 @@ Every shipped command, by group. This list is generated from each command's own
 |---------|-------------|
 | `/pan:experiment` | Manage external experiments — scaffold, run, harvest, promote findings back to PAN |
 | `/pan:learn` | Analyze trace sessions or harvested experiments via pan-optimizer; generate ranked optimization reports |
-| `/pan:optimize` | Manage the circular optimization loop — record a report's suggestions, undo them, view stats, list reports, manage trace sessions |
 
 ### Git Workflow
 | Command | Description |
@@ -319,15 +309,9 @@ Every shipped command, by group. This list is generated from each command's own
 |---------|-------------|
 | `/pan:army` | Bot-army campaign — Mission Control (the reasoning-tier conductor) delegates a whole-project goal to squads (architecture / build / quality / release), each squad working branch-per-agent worktrees under a hard safety harness, gated by CI + a human merge, looping plan→delegate→execute→review→integrate→learn until the goal ships or a stop condition fires. |
 
-### External tools
-| Command | Description |
-|---------|-------------|
-| `/pan:mcp-bridge` | Discover available MCP tools and recommend which ones apply to a phase. Discovery-only; auto-invocation deferred. |
-
 ### System
 | Command | Description |
 |---------|-------------|
-| `/pan:audit-deployment` | Audit a PAN Wizard deployment — verify installation integrity, project health, and draft enhancement specs |
 | `/pan:debug` | Systematic debugging with persistent state across context resets |
 | `/pan:health` | Diagnose planning directory health and optionally repair issues |
 | `/pan:help` | Show available PAN commands and usage guide |
@@ -337,11 +321,6 @@ Every shipped command, by group. This list is generated from each command's own
 | `/pan:todo-add` | Capture idea or task as todo from current conversation context |
 | `/pan:todo-check` | List pending todos and select one to work on |
 | `/pan:update` | Update PAN to latest version with changelog display |
-
-### Community
-| Command | Description |
-|---------|-------------|
-| `/pan:discord` | Join the PAN Discord community |
 <!-- generated:command-index:end -->
 
 ---
@@ -355,12 +334,12 @@ Every shipped command, by group. This list is generated from each command's own
 
 **Existing project, iterative work:**
 ```
-/pan:focus-scan → /clear → /pan:focus-plan → /clear → /pan:focus-exec → /clear → /pan:focus-sync
+/pan:focus-auto --step scan → /clear → /pan:focus-auto --step plan → /clear → /pan:focus-auto --step exec → /clear → /pan:focus-docs --sync
 ```
 
 **Design a feature, then build it:**
 ```
-/pan:focus-design "feature" → /clear → /pan:focus-scan → /clear → /pan:focus-plan → /clear → /pan:focus-exec
+/pan:focus-design "feature" → /clear → /pan:focus-auto --step scan → /clear → /pan:focus-auto --step plan → /clear → /pan:focus-auto --step exec
 ```
 
 **Resume after a break:**
@@ -381,7 +360,7 @@ Every shipped command, by group. This list is generated from each command's own
 
 **Complete a milestone:**
 ```
-/pan:milestone-audit → /pan:milestone-gaps → ... fix gaps ... → /pan:milestone-done 1.0.0
+/pan:milestone-audit → /pan:milestone-audit --gaps → ... fix gaps ... → /pan:milestone-done 1.0.0
 ```
 
 **Debug an issue (survives /clear):**
@@ -399,7 +378,7 @@ Every shipped command, by group. This list is generated from each command's own
 
 **`/pan:discuss-phase <N>`** — Capture your vision for a phase before planning. Creates context.md.
 
-**`/pan:research-phase <N>`** — Deep ecosystem research for specialized domains (3D, ML, audio, etc.). Creates research.md.
+**`/pan:plan-phase --research-only <N>`** — Deep ecosystem research for specialized domains (3D, ML, audio, etc.). Creates research.md.
 
 **`/pan:assumptions <N>`** — See Claude's intended approach before it starts. Conversational only, no files created.
 
@@ -421,9 +400,9 @@ Every shipped command, by group. This list is generated from each command's own
 
 **`/pan:milestone-audit`** — Reads verification.md files, checks requirements coverage, spawns integration checker. Creates milestone-audit.md.
 
-**`/pan:milestone-gaps`** — Reads audit, groups gaps into phases, adds to roadmap.md.
+**`/pan:milestone-audit --gaps`** — Reads audit, groups gaps into phases, adds to roadmap.md.
 
-**`/pan:milestone-cleanup`** — Moves completed phase directories to `milestones/v{X.Y}-phases/`.
+**`/pan:milestone-done --cleanup`** — Moves completed phase directories to `milestones/v{X.Y}-phases/`.
 
 **`/pan:retro`** — Milestone retrospective. Analyzes estimation accuracy, verification patterns, and common gap types. Run after `/pan:milestone-done` to reflect before the next milestone.
 
@@ -449,7 +428,7 @@ Every shipped command, by group. This list is generated from each command's own
 
 **`/pan:settings`** — Toggle researcher, plan checker, verifier agents. Select model profile.
 
-**`/pan:profile <name>`** — Quick profile switch: `quality` and `balanced` (reasoning tier for every agent; `balanced` is the default), `budget` (mid tier for writing, fast tier for research/verification).
+**`/pan:settings --profile <name>`** — Quick profile switch: `quality` and `balanced` (reasoning tier for every agent; `balanced` is the default), `budget` (mid tier for writing, fast tier for research/verification).
 
 **Planning config** (`.planning/config.json`):
 - `commit_docs: true` — commit planning artifacts to git (set `false` + add `.planning/` to `.gitignore` for private planning)
@@ -496,5 +475,4 @@ Run `/pan:update` for version comparison and changelog preview before updating.
 - `/pan:progress` — see where you're at
 - `.planning/state.md` — current project context
 - `.planning/roadmap.md` — phase status
-- `/pan:discord` — community support
 </reference>

package/pan-wizard-core/workflows/insert-phase.md

@@ -64,13 +64,11 @@ Extract from result: `phase_number`, `after_phase`, `name`, `slug`, `directory`.
 <step name="update_project_state">
 Update state.md to reflect the inserted phase:
 
-1. Read `.planning/state.md`
-2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
-   ```
-   - Phase {decimal_phase} inserted after Phase {after_phase}: {description} (URGENT)
-   ```
+Append the entry under "## Accumulated Context" → "### Roadmap Evolution" (the engine creates the section when it is missing):
 
-If "Roadmap Evolution" section doesn't exist, create it.
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state section "Roadmap Evolution" --append "- Phase {decimal_phase} inserted after Phase {after_phase}: {description} (URGENT)"
+```
 </step>
 
 <step name="completion">

package/pan-wizard-core/workflows/learn.md

@@ -7,8 +7,8 @@ Analyze the most recent trace session and generate a circular optimization repor
 - A trace session must exist in `.planning/optimization/traces/`
 - If no session exists, instruct the user to start one first:
   ```
-  /pan:optimize trace init --description "what you're building"
-  [run your build: /pan:exec-phase N or /pan:focus-exec]
+  /pan:learn --optimize trace init --description "what you're building"
+  [run your build: /pan:exec-phase N or /pan:focus-auto --step exec]
   /pan:learn
   ```
 
@@ -65,7 +65,7 @@ Present to the user:
 2. **Top 3 findings** — the most impactful recommendations
 3. **Lessons** — how many, and where each belongs: the project's instructions (CLAUDE.md or AGENTS.md, outside PAN's section), a test, or a comment at the cited code
 4. **Prompt and workflow changes** — how many, for human review
-5. **Next step** — `/pan:optimize apply` records the suggestions in `.planning/optimization/suggestions.md`; a person makes the changes, because nothing in the report reaches an agent until it is written where the agents read
+5. **Next step** — `/pan:learn --optimize apply` records the suggestions in `.planning/optimization/suggestions.md`; a person makes the changes, because nothing in the report reaches an agent until it is written where the agents read
 
 ## Step 5 — Auto-apply (if --apply flag)
 

package/pan-wizard-core/workflows/milestone-audit.md

@@ -274,7 +274,7 @@ All requirements covered. Cross-phase integration verified. E2E flows complete.
 
 **Plan gap closure** — create phases to complete milestone
 
-/pan:milestone-gaps
+/pan:milestone-audit --gaps
 
 <sub>/clear first → fresh context window</sub>
 
@@ -316,7 +316,7 @@ All requirements met. No critical blockers. Accumulated tech debt needs review.
 
 **B. Plan cleanup phase** — address debt before completing
 
-/pan:milestone-gaps
+/pan:milestone-audit --gaps
 
 <sub>/clear first → fresh context window</sub>
 

package/pan-wizard-core/workflows/milestone-new.md

@@ -55,17 +55,13 @@ Update Active requirements section and "Last updated" footer.
 
 ## 5. Update state.md
 
-```markdown
-## Current Position
+Reset the position for the new milestone through the engine, keeping the Accumulated Context of the last one:
 
-**Current Phase:** Not started (defining requirements)
-**Current Plan:** —
-**Status:** Defining requirements
-**Last Activity:** [today]
-**Last Activity Description:** Milestone v[X.Y] started
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state init --core-value "<core value from project.md>" --focus "Milestone v[X.Y] [Name]" --phase "Not started" --phase-name "Defining requirements" --status "Defining requirements" --activity "Milestone v[X.Y] started" --force --keep-context
 ```
 
-Keep Accumulated Context section from previous milestone.
+The old state.md is backed up first. The engine writes every section of the template and keeps the frontmatter in sync; never write state.md with the Write or Edit tool (under `hooks.guard: enforce` the guard denies it).
 
 ## 6. Cleanup and Commit
 
@@ -81,108 +77,63 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: start milestone v
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init new-milestone)
 ```
 
-Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`.
+Extract from init JSON: `researcher_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`.
 
 ## 8. Research Decision
 
-AskUserQuestion: "Research the domain ecosystem for new features before defining requirements?"
-- "Research first (Recommended)" — Discover patterns, features, architecture for NEW capabilities
-- "Skip research" — Go straight to requirements
+Research is **off by default** and answers questions; it never surveys a domain or adds scope (the same contract as `/pan:new-project` step 6).
 
-**Persist choice to config** (so future `/pan:plan-phase` honors it):
+AskUserQuestion: "Research open questions for the new features before defining requirements?"
+- "Skip research (Recommended)" — Go straight to requirements
+- "Research open questions" — Answer up to 5 questions that block building the new features, each with a source
 
-```bash
-# If "Research first": persist true
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.research true
+`/pan:plan-phase` keeps its own setting (`workflow.research`, off by default; `/pan:settings` changes it).
+
+**If "Research open questions":**
 
-# If "Skip research": persist false
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-set workflow.research false
+List at most **5** open questions the milestone's goals leave unanswered and that block building the NEW features (a technology choice, an external API's behaviour, a data format, a limit or rule; never what already exists). Write them as a numbered list to `.planning/research/questions.md` (`mkdir -p .planning/research` first):
+
+```markdown
+# Research questions — milestone v[X.Y]
+
+1. [question] — blocks: [the decision it settles]
 ```
 
-**If "Research first":**
+**No questions → no research.** If nothing blocks building, write no file, say so, and continue to Step 9.
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PAN ► RESEARCHING
+ PAN ► RESEARCHING {N} QUESTIONS
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning 4 researchers in parallel...
-  → Stack, Features, Architecture, Pitfalls
 ```
 
-```bash
-mkdir -p .planning/research
-```
-
-Spawn 4 parallel pan-project-researcher agents. Each uses this template with dimension-specific fields:
-
-**Common structure for all 4 researchers:**
 ```
 Task(prompt="
-<research_type>Project Research — {DIMENSION} for [new features].</research_type>
-
-<milestone_context>
-SUBSEQUENT MILESTONE — Adding [target features] to existing app.
-{EXISTING_CONTEXT}
-Focus ONLY on what's needed for the NEW features.
-</milestone_context>
-
-<question>{QUESTION}</question>
-
 <files_to_read>
-- .planning/project.md (Project context)
+- .planning/research/questions.md (The questions: answer these and nothing else)
+- .planning/project.md (Project context; what exists is not a question)
 </files_to_read>
 
-<downstream_consumer>{CONSUMER}</downstream_consumer>
-
-<quality_gate>{GATES}</quality_gate>
-
 <output>
-Write to: .planning/research/{FILE}
-Use template: ~/.claude/pan-wizard-core/templates/research-project/{FILE}
+Write to: .planning/research/research-summary.md
+One row per question: | # | Question | Answer | Source | Confidence | Decision it settles |, or `unknown — assume: …`. At most 4 searches or fetches per question. Anything that suggests new scope goes under ## Ideas (v2 candidates). Do not commit.
 </output>
-", subagent_type="pan-project-researcher", model="{researcher_model}", description="{DIMENSION} research")
+", subagent_type="pan-project-researcher", model="{researcher_model}", description="Answer research questions")
 ```
 
-**Dimension-specific fields:**
-
-| Field | Stack | Features | Architecture | Pitfalls |
-|-------|-------|----------|-------------|----------|
-| EXISTING_CONTEXT | Existing validated capabilities (DO NOT re-research): [from project.md] | Existing features (already built): [from project.md] | Existing architecture: [from project.md or codebase map] | Focus on common mistakes when ADDING these features to existing system |
-| QUESTION | What stack additions/changes are needed for [new features]? | How do [target features] typically work? Expected behavior? | How do [target features] integrate with existing architecture? | Common mistakes when adding [target features] to [domain]? |
-| CONSUMER | Specific libraries with versions for NEW capabilities, integration points, what NOT to add | Table stakes vs differentiators vs anti-features, complexity noted, dependencies on existing | Integration points, new components, data flow changes, suggested build order | Warning signs, prevention strategy, which phase should address it |
-| GATES | Versions current (verify with Context7), rationale explains WHY, integration considered | Categories clear, complexity noted, dependencies identified | Integration points identified, new vs modified explicit, build order considers deps | Pitfalls specific to adding these features, integration pitfalls covered, prevention actionable |
-| FILE | stack.md | features.md | architecture.md | pitfalls.md |
-
-After all 4 complete, spawn synthesizer:
+Check the answers:
 
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs research check .planning/research/questions.md .planning/research/research-summary.md
 ```
-Task(prompt="
-Synthesize research outputs into summary.md.
-
-<files_to_read>
-- .planning/research/stack.md
-- .planning/research/features.md
-- .planning/research/architecture.md
-- .planning/research/pitfalls.md
-</files_to_read>
 
-Write to: .planning/research/summary.md
-Use template: ~/.claude/pan-wizard-core/templates/research-project/summary.md
-Commit after writing.
-", subagent_type="pan-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
-```
+Exit 1: send its `errors` to the researcher once as a revision. One revision at most; then proceed, with each question still unsourced recorded under `## Unknowns` in research-summary.md with the assumption you will use. Commit:
 
-Display key findings from summary.md:
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: answer milestone research questions" --files .planning/research/questions.md .planning/research/research-summary.md
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PAN ► RESEARCH COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-**Stack additions:** [from summary.md]
-**Feature table stakes:** [from summary.md]
-**Watch Out For:** [from summary.md]
-```
+Display the decisions settled, the unknowns with their assumptions, and the number of ideas (offered in Step 9 as future candidates, never added to this milestone by themselves).
 
 **If "Skip research":** Continue to Step 9.
 
@@ -196,27 +147,19 @@ Display key findings from summary.md:
 
 Read project.md: core value, current milestone goals, validated requirements (what exists).
 
-**If research exists:** Read features.md, extract feature categories.
-
-Present features by category:
-```
-## [Category 1]
-**Table stakes:** Feature A, Feature B
-**Differentiators:** Feature C, Feature D
-**Research notes:** [any relevant notes]
-```
+**If research exists:** Read `.planning/research/research-summary.md`. Its answers settle decisions the requirements use; its `## Ideas (v2 candidates)` are offered as future candidates the user may promote, never added to this milestone by themselves.
 
-**If no research:** Gather requirements through conversation. Ask: "What are the main things users need to do with [new features]?" Clarify, probe for related capabilities, group into categories.
+Gather requirements through conversation. Ask: "What are the main things users need to do with [new features]?" Clarify, probe for related capabilities, group into categories.
 
 **Scope each category** via AskUserQuestion (multiSelect: true, header max 12 chars):
 - "[Feature 1]" — [brief description]
 - "[Feature 2]" — [brief description]
 - "None for this milestone" — Defer entire category
 
-Track: Selected → this milestone. Unselected table stakes → future. Unselected differentiators → out of scope.
+Track: Selected → this milestone. Unselected → future or out of scope (ask which when unclear).
 
 **Identify gaps** via AskUserQuestion:
-- "No, research covered it" — Proceed
+- "No, that covers it" — Proceed
 - "Yes, let me add some" — Capture additions
 
 **Generate requirements.md:**
@@ -275,7 +218,7 @@ Task(prompt="
 <files_to_read>
 - .planning/project.md
 - .planning/requirements.md
-- .planning/research/summary.md (if exists)
+- .planning/research/research-summary.md (if exists; older projects: .planning/research/summary.md)
 - .planning/config.json
 - .planning/milestones.md
 </files_to_read>
@@ -288,7 +231,7 @@ Create roadmap for milestone v[X.Y]:
 3. Map every requirement to exactly one phase
 4. Derive 2-5 success criteria per phase (observable user behaviors)
 5. Validate 100% coverage
-6. Write files immediately (roadmap.md, state.md, update requirements.md traceability)
+6. Write roadmap.md immediately; initialise state.md with `pan-tools state init ... --force --keep-context` (it exists from step 5), never the Write tool; update requirements.md traceability
 7. Return ROADMAP CREATED with summary
 
 Write files first, then return.