pan-wizard 2.9.0 → 2.9.1

package/README.md

@@ -149,7 +149,7 @@ node bin/install.js --claude --local
 Installs to `./.claude/` for testing modifications before contributing.
 
 ```bash
-npm test                # 1736 unit tests
+npm test                # 1747 unit tests
 npm run test:scenarios  # Scenario tests (install + integration)
 npm run test:all        # All tests (unit + scenario)
 ```

package/commands/pan/assumptions.md

@@ -27,15 +27,50 @@ Phase number: $ARGUMENTS (required)
 Project state and roadmap are loaded in-workflow using targeted reads.
 </context>
 
+<investigate_before_claiming>
+Before surfacing any assumption, read the actual codebase first.
+- Read existing source files related to the phase's domain
+- Grep for relevant function names, imports, patterns
+- Base assumptions on what the code actually shows, not speculation
+Do not claim "the project uses X" without verifying it in the files.
+</investigate_before_claiming>
+
+<citation_requirement>
+Every assumption MUST cite the evidence that supports it.
+
+**Before presenting assumptions to the user, scan your draft for unsourced claims.** Any assumption without file:line evidence is speculation, not a grounded assumption.
+
+**Format:** "Assumption: [claim] — Evidence: [file:line or grep result]"
+
+**Grounding rules:**
+- Technical approach assumptions require: file:line showing the current pattern/framework in use
+- Dependency assumptions require: import/require evidence from the relevant module
+- Scope boundary assumptions require: file paths showing what exists vs what doesn't
+- Risk assumptions require: file:line showing the fragile pattern or grep showing the coupling
+
+**Anti-pattern:**
+```
+BAD:  "Assumption: The project uses Express for routing"
+      → Did you check? Maybe it uses Fastify, or has no server at all.
+GOOD: "Assumption: The project uses Express for routing — Evidence: require('express')
+       at src/server.ts:3, route definitions at src/routes/index.ts:12-45"
+```
+</citation_requirement>
+
 <process>
 1. Validate phase number argument (error if missing or invalid)
 2. Check if phase exists in roadmap
-3. Follow assumptions.md workflow:
+3. Read relevant source files to ground assumptions in evidence
+4. For each assumption, follow observe-think-conclude:
+   - OBSERVE: What does the code show?
+   - THINK: What does this imply for the phase approach?
+   - CONCLUDE: State the assumption with file:line evidence
+5. Follow assumptions.md workflow:
    - Analyze roadmap description
    - Surface assumptions about: technical approach, implementation order, scope, risks, dependencies
-   - Present assumptions clearly
+   - Present assumptions clearly with file:line references where applicable
    - Prompt "What do you think?"
-4. Gather feedback and offer next steps
+5. Gather feedback and offer next steps
 </process>
 
 <success_criteria>

package/commands/pan/audit-deployment.md

@@ -38,6 +38,12 @@ If no target directory is provided, ask the user:
 Validate the directory exists before proceeding.
 </step>
 
+<investigate_before_judging>
+Never report a file as missing, broken, or misconfigured without reading it first.
+For every audit check: read the actual file, verify its contents, then state the finding with evidence.
+Do not speculate about file contents based on filenames alone.
+</investigate_before_judging>
+
 <step name="installation_audit">
 **Phase 1 — Installation Integrity Audit**
 

package/commands/pan/debug.md

@@ -49,6 +49,30 @@ If active sessions exist AND no $ARGUMENTS:
 If $ARGUMENTS provided OR user describes new issue:
 - Continue to symptom gathering
 
+## Reasoning Protocol
+
+For each debugging step, follow the observe-think-act pattern:
+1. **OBSERVE** — State what you see (error message, unexpected output, file contents)
+2. **THINK** — Reason about what this means and what to investigate next
+3. **ACT** — Execute one targeted tool call based on the reasoning
+This prevents random exploration and keeps investigation systematic.
+
+## Meta-Prompting: Self-Generated Debug Strategy
+
+After gathering symptoms (step 2), generate your own investigation plan before spawning the debugger:
+
+```
+Given symptoms: "{summary}"
+My debug strategy:
+1. Most likely cause: {hypothesis} → Test by: {specific check}
+2. Second most likely: {hypothesis} → Test by: {specific check}
+3. Long shot: {hypothesis} → Test by: {specific check}
+4. Files to read first: {ordered list, most relevant first}
+5. What would DISPROVE each hypothesis: {falsification criteria}
+```
+
+This self-generated strategy is passed to the pan-debugger agent as part of the prompt, giving it a targeted investigation plan rather than open-ended exploration. The falsification criteria are critical — they prevent the agent from confirming a hypothesis by only looking for supporting evidence.
+
 ## 2. Gather Symptoms (if new issue)
 
 Use AskUserQuestion for each:
@@ -123,9 +147,47 @@ Task(
   - "Manual investigation" - done
   - "Add more context" - gather more symptoms, spawn again
 
+<debug_handoff_schema>
+Debug session files (`.planning/debug/{slug}.md`) MUST contain structured state for cross-agent handoff:
+
+```yaml
+# Required sections in debug session file
+session: "{slug}"
+status: "investigating | root-cause-found | fix-applied | resolved"
+created: "{ISO-8601}"
+updated: "{ISO-8601}"
+
+symptoms:
+  expected: "{what should happen}"
+  actual: "{what happens instead}"
+  errors: "{error messages}"
+  reproduction: "{steps to reproduce}"
+
+investigation:
+  hypotheses_tested:
+    - hypothesis: "{what we thought}"
+      result: "confirmed | eliminated"
+      evidence: "{file:line or command output}"
+  hypotheses_remaining:
+    - "{what still needs checking}"
+
+root_cause:                          # Populated when found
+  description: "{what's actually wrong}"
+  evidence: "{file:line proof}"
+  confidence: "high | medium | low"
+
+fix:                                 # Populated when applied
+  files_changed: ["{paths}"]
+  approach: "{what was done}"
+  tests_added: ["{test paths}"]
+```
+
+**Why structured:** Each continuation agent starts with 0 context. Without structured state, it re-reads the entire investigation log and may re-test eliminated hypotheses. With structured state, it reads `hypotheses_tested` (skip these), checks `hypotheses_remaining` (do these next), and picks up exactly where the previous agent stopped.
+</debug_handoff_schema>
+
 ## 5. Spawn Continuation Agent (After Checkpoint)
 
-When user responds to checkpoint, spawn fresh agent:
+When user responds to checkpoint, spawn fresh agent with the structured debug state:
 
 ```markdown
 <objective>
@@ -134,7 +196,7 @@ Continue debugging {slug}. Evidence is in the debug file.
 
 <prior_state>
 <files_to_read>
-- .planning/debug/{slug}.md (Debug session state)
+- .planning/debug/{slug}.md (Debug session state — parse structured sections)
 </files_to_read>
 </prior_state>
 
@@ -146,6 +208,13 @@ Continue debugging {slug}. Evidence is in the debug file.
 <mode>
 goal: find_and_fix
 </mode>
+
+<handoff_instructions>
+1. Parse the debug file's structured sections (symptoms, investigation, root_cause, fix)
+2. Do NOT re-test hypotheses marked "eliminated" — they are dead ends
+3. Start from hypotheses_remaining or the checkpoint's next action
+4. Update the debug file's structured sections as you progress
+</handoff_instructions>
 ```
 
 ```

package/commands/pan/exec-phase.md

@@ -27,6 +27,32 @@ Context budget: ~15% orchestrator, 100% fresh per subagent.
 @~/.claude/pan-wizard-core/references/ui-brand.md
 </execution_context>
 
+<completion_contract>
+Execution is complete when ALL conditions are met:
+1. Every plan in the phase has been dispatched to a subagent
+2. All subagents have returned (success or failure)
+3. Full test suite passes with count >= pre-execution baseline
+4. All verified tasks committed with accurate commit messages
+5. state.md updated with phase progress
+6. Failed tasks (if any) logged with error classification and root cause
+
+Execution FAILS if: test count drops below baseline after all retries, or state corruption is detected.
+</completion_contract>
+
+<wave_dependencies>
+Discovery → Baseline: Test baseline MUST be captured before any wave executes (regression detection requires it)
+Baseline → Wave N: Each wave MUST wait for the previous wave to complete and pass verification
+Wave N → Commit N: Wave changes MUST pass tests before committing (don't commit broken code)
+All Waves → Final Verify: Full test suite MUST pass after all waves complete
+Final Verify → State Update: state.md MUST only be updated after verification passes
+
+HARD STOP conditions (do not proceed to next wave):
+- Baseline capture fails (test suite broken before we start) → STOP, report to user
+- Wave N test count drops below baseline after 3 retries → revert wave, mark all wave tasks FAILED, continue to next wave
+- State corruption detected (malformed state.md or plan files) → STOP execution entirely, report to user
+- All waves complete but final test count < baseline → revert last wave, re-verify
+</wave_dependencies>
+
 <context>
 Phase: $ARGUMENTS
 
@@ -39,7 +65,71 @@ Phase: $ARGUMENTS
 Context files are resolved inside the workflow via `pan-tools init execute-phase` and per-subagent `<files_to_read>` blocks.
 </context>
 
+<action_gating>
+Each execution stage has a restricted set of appropriate actions. Using the wrong tool at the wrong stage causes regressions.
+
+| Stage | Read | Grep/Glob | Edit/Write | Bash (tests) | Bash (git) | Agent |
+|-------|------|-----------|------------|--------------|------------|-------|
+| Discovery (find plans) | YES | YES | NO | NO | NO | NO |
+| Baseline capture | YES | NO | NO | YES | YES | NO |
+| Wave execution | YES | YES | YES | YES | NO | YES |
+| Wave verification | YES | YES | NO | YES | NO | NO |
+| Wave commit | NO | NO | NO | NO | YES | NO |
+| Final verification | YES | YES | NO | YES | NO | NO |
+| State update | YES | NO | YES | NO | YES | NO |
+
+**Key constraints:**
+- Discovery: read-only — do not modify files while figuring out what to execute
+- Baseline: run tests + git status only — no code changes before baseline is captured
+- Wave verification: NO Edit/Write — you are checking work, not doing more work
+- Wave commit: git operations only — all code changes must be done before committing
+</action_gating>
+
 <process>
 Execute the execute-phase workflow from @~/.claude/pan-wizard-core/workflows/exec-phase.md end-to-end.
 Preserve all workflow gates (wave execution, checkpoint handling, verification, state updates, routing).
+
+**Context Management Across Waves:**
+- KEEP: Phase goals, test baseline, current wave tasks, file paths being modified
+- SUMMARIZE: Completed wave results to one-line summaries
+- DISCARD: Raw tool output from previous waves
+
+**Attention Anchor — emit after each wave completes:**
+```
+Wave {N}/{total} complete | Tasks: {done}/{total} | Tests: {baseline} → {current}
+Remaining waves: {list of wave numbers with task counts}
+Next: Wave {N+1} — {task count} tasks [{task IDs}]
+```
+This prevents drift in multi-wave phases where the agent loses track of which waves remain and what the test baseline was.
+
+**State Intent Before Implementing (M+ tasks):**
+For each STANDARD or FULL task, state before coding: "I will modify [files], adding [what], to achieve [goal]. Risk: [what could break]."
+
+**Pre-Commit Verification Checklist — apply before each wave commit:**
+1. Every modified file was read before editing
+2. `git diff --stat` contains only files related to the current wave's tasks
+3. Test suite passes and count meets or exceeds pre-wave baseline
+4. Commit message lists only tasks that are verified (tests ran, tests passed)
+5. No secrets or credentials staged
+
+If any check fails: fix and re-verify before committing.
+
+**Error Recovery Classification — apply when any task fails:**
+- RECOVERABLE (retry up to 3 times): test failure after code change, build syntax error, file not found (search for moved path)
+- UNRECOVERABLE (mark task FAILED, continue to next): same failure after 3 retries, permission errors, state corruption, unrelated test regression
+Never let a failed task block the rest of the wave.
+
+**Anti-Overengineering:**
+Implement exactly what the plan says. Do not add features, refactor surrounding code, add comments to unchanged files, or create abstractions for one-time operations.
+
+**Common Anti-Patterns (avoid these):**
+```
+BAD:  Task says "add input validation" → you also refactor the error handler, add logging, and rename variables
+      → 3 unrelated changes pollute the diff, risk regressions in untested paths
+GOOD: Add validation only → commit → let the next task handle error handling if planned
+
+BAD:  Test fails → change the test's expected output to match the broken code
+      → Bug is now hidden, passes CI, breaks in production
+GOOD: Test fails → read the test intent → fix the code to match the expected behavior
+```
 </process>

package/commands/pan/focus-auto.md

@@ -18,11 +18,11 @@ Run purpose-driven improvement campaigns with a single command. The auto-runner
 
 **ADR:** ADR-0015 | **Heritage:** execplan budget + PanMonty categories + focus-exec pipeline
 
-## CRITICAL: Project Scope Boundary
+## Project Scope Boundary
 
-This command runs improvement campaigns on the **host project's source code** — NOT on PAN Wizard's own infrastructure.
+This command runs improvement campaigns on the **host project's source code** — not on PAN Wizard's own infrastructure.
 
-**ALWAYS EXCLUDE these directories from scanning and execution:**
+**Exclude these directories from scanning and execution:**
 - `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/` — PAN runtime directories
 - Any `pan-wizard-core/`, `pan-tools`, agent `.md`, or command `.md` files within PAN runtime directories
 
@@ -30,6 +30,18 @@ This command runs improvement campaigns on the **host project's source code**
 
 ---
 
+<completion_contract>
+A campaign is complete when ANY stop condition is met:
+1. Max cycles reached (--max-cycles, default 10)
+2. Total budget exhausted (--total-budget, default 200)
+3. Scan returns zero items for the selected category
+4. Context window drops below 25% (CRITICAL threshold)
+5. User sends /pan:focus-auto --stop
+6. Category-specific completion (e.g., prompts_remaining === 0)
+
+Each cycle is complete when: scan → plan → exec → commit succeeds, OR a safety harness triggers and the cycle is cleanly aborted with state preserved.
+</completion_contract>
+
 ## FIRST ACTION — Category Selection (if no --category argument)
 
 If `$ARGUMENTS` does NOT contain `--category`, you MUST ask the user before doing anything else.
@@ -45,8 +57,9 @@ Which category should this auto campaign focus on?
 4. **features** — Roadmap items, new capabilities (P3-P5)
 5. **docs** — Stale documentation, missing command descriptions (P5-P6)
 6. **optimize** — Performance bottlenecks, redundant computation, robustness hardening (P1-P4)
+7. **prompts** — Execute micro-prompt documents sequentially, or generate them from specs (P0-P6)
 
-Reply with a number (1-6) or category name.
+Reply with a number (1-7) or category name.
 ```
 
 **After the user replies, map their response to a category name:**
@@ -56,8 +69,9 @@ Reply with a number (1-6) or category name.
 - "4" or "features" → SELECTED_CATEGORY = features
 - "5" or "docs" → SELECTED_CATEGORY = docs
 - "6" or "optimize" → SELECTED_CATEGORY = optimize
+- "7" or "prompts" → SELECTED_CATEGORY = prompts
 
-**Do NOT proceed past this point without a category. Do NOT guess. Do NOT pick a default. STOP and wait for the user's reply.**
+Wait for the user's reply before proceeding. Do not guess or pick a default category.
 
 ## AUTONOMY RULES (apply AFTER category is selected)
 
@@ -75,7 +89,7 @@ Reply with a number (1-6) or category name.
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--category` | null (all) | cleanup, tests, stability, features, docs |
+| `--category` | null (all) | cleanup, tests, stability, features, docs, optimize, prompts |
 | `--mode` | category-dependent | bugfix, balanced, features, full |
 | `--budget` | category-dependent | Points per cycle (5-100) |
 | `--max-cycles` | 10 | Maximum iterations (1-50) |
@@ -95,6 +109,7 @@ Reply with a number (1-6) or category name.
 | features | P3-P5 | features | 50 |
 | docs | P5-P6 | balanced | 30 |
 | optimize | P1-P4 | balanced | 50 |
+| prompts | P0-P6 | balanced | 100 |
 
 ## Pipeline
 
@@ -122,6 +137,20 @@ Reply with a number (1-6) or category name.
 4. Run `git status` to verify clean working tree (warn if dirty, don't block)
 5. Create safety tag: `git tag -f focus-auto-baseline`
 
+<phase_dependencies>
+Phase 0 → Phase 1: Init MUST succeed before baseline (state tracking requires valid run)
+Phase 1 → Phase 2: Baseline MUST be captured before main loop (regression circuit breaker needs it)
+Phase 2 (each cycle): Scan → Plan → Exec → Commit is strictly sequential within a cycle
+  - Scan MUST complete before plan (plan needs scan items)
+  - Plan MUST complete before exec (exec needs batch file)
+  - Exec MUST complete and tests pass before commit (never commit broken code)
+
+HARD STOP conditions:
+- Phase 1 fails (tests broken): Do not enter main loop — report and exit
+- Any cycle: test count drops below baseline after revert → stop campaign, preserve state
+- Context drops below 25%: stop campaign cleanly (safety harness 3)
+</phase_dependencies>
+
 ### Phase 2: Main Loop
 
 **For each cycle (1 to max_cycles), execute Steps 2.1 through 2.5 without stopping:**
@@ -144,6 +173,9 @@ Perform a deep codebase scan to find actionable work items with evidence.
   - **features:** roadmap items not yet implemented, README promises without backing code
   - **docs:** stale documentation, missing command descriptions
   - **optimize:** N+1 operations (file I/O / network calls inside loops), redundant re-computation (`JSON.parse`/`stringify` of same data), synchronous blocking in async modules (`readFileSync`/`execSync` alongside async exports), algorithmic complexity (nested `.find()`/`.filter()` in loops creating O(n²)+), unnecessary allocations in hot paths (spread in loops, string concat vs `join()`), regex construction inside loops (should be hoisted), unbounded collection growth (`.push()` without size limits), swallowed errors (`catch {}` / `catch { /* */ }`), suboptimal data structures (array `.includes()` where Set is better), dead assignments, unguarded property access on nullable values (`.length`/`.split()`/`.match()[0]` without null check)
+  - **prompts:** Two operational modes — detect which applies:
+    - **Execute mode:** Find micro-prompt documents (`.md` files containing ordered prompt blocks, e.g., `## Prompt 1`, `## Prompt 2`, or numbered checklist items `- [ ] Prompt: ...`). Look in `.planning/`, project root, and `docs/` for files matching patterns: `*prompts*`, `*micro-prompt*`, `*prompt-plan*`, `*prompt-sequence*`. Each unchecked/incomplete prompt block is one work item.
+    - **Generate mode:** Find specification documents (files matching `*spec*`, `*prd*`, `*requirements*`, `*feature*` in `.planning/`, `docs/specs/`, project root) that do NOT already have a corresponding micro-prompt document. Each spec needing decomposition is one work item.
 
 **Optimize category: convergent re-scan.** On cycles 2+, cross-reference scan findings against previous cycle completions (`cycles[].items` in auto-run state). Only pick genuinely new items — skip IDs already completed or failed. If the count of new findings drops AND cycle efficiency drops below 30% of the prior cycle's, this signals convergence and the `diminishing_returns` stop condition fires.
 - Use the Agent tool with Explore subagent for thorough analysis if needed
@@ -226,6 +258,11 @@ Implement each item from the batch created in Step 2.2. Record `tests_before` by
 6. Run the project's test suite
 7. Pass = DONE | Fail = investigate (15 min max), then revert, mark FAILED
 
+**Error Recovery Classification:**
+- RECOVERABLE (retry up to 3 times): test failure after code change, build syntax error, file not found (search for moved path)
+- UNRECOVERABLE (mark FAILED, move to next item): same failure after 3 retries, permission errors, state corruption, unrelated test regression
+A failed item never blocks subsequent items.
+
 **After all items in the batch:**
 1. Run full test suite — ALL tests must pass
 2. Record `tests_after` from the summary line
@@ -244,12 +281,25 @@ Check the response for stop conditions:
 - `max_cycles`: Maximum iterations reached — go to Phase 3
 - `zero_completed`: No items completed in this cycle — go to Phase 3
 - `diminishing_returns`: Optimize only — cycle efficiency < 30% of previous cycle — go to Phase 3
+- `prompts_complete`: Prompts only — all prompts in document executed — go to Phase 3
 - `null`: Continue to next cycle
 
-#### Step 2.5: Inter-Cycle Check
+#### Step 2.5: Inter-Cycle Context Management
+
+Between cycles, manage context to prevent quality degradation over long campaigns:
+- **KEEP:** Current cycle goals, test baseline, error states, active file paths
+- **SUMMARIZE:** Previous cycle results to a one-line summary each
+- **DISCARD:** Raw tool output from previous cycles, superseded scan results
 
 Display one-line cycle summary: `Cycle N/M | X/Y pts | Z items done | Tests: A -> B`
 
+**Attention anchor — emit after every cycle summary:**
+```
+Remaining: {cycles_left} cycles | {budget_remaining}/{total_budget} pts | Safety: {active_harness_warnings}
+Next: Cycle {N+1} — Scan → Plan → Exec → Commit
+```
+This prevents lost-in-the-middle drift in 10+ cycle campaigns where the agent forgets budget limits or stop conditions.
+
 Then continue immediately to the next cycle (back to Step 2.1).
 
 ### Phase 3: Campaign End
@@ -294,20 +344,133 @@ Then continue immediately to the next cycle (back to Step 2.1).
 7. **Verify Understanding** — State understanding for M+ items before coding.
 8. **Preserve Tests** — Never change test expectations to match broken code.
 9. **Accurate Commits** — Only claim verified items in commit messages. Include actual test counts.
+10. **Vary Similar Fixes** — When 3+ items in a cycle share the same fix pattern (e.g., "add null check"), re-read each module's conventions before applying. The same pattern may need different implementations in different modules. Check after the 3rd fix whether a shared helper would be better than scattered copies.
+
+## Prompts Category — Execution Details
+
+The prompts category operates in two distinct modes. Detect which mode applies during the scan phase based on what the scan finds.
+
+### Execute Mode (micro-prompt document found)
+
+A micro-prompt document contains an ordered sequence of self-contained implementation prompts. Each prompt describes a single, testable change.
+
+**Document format recognized:**
+
+```markdown
+# Micro-Prompts: <Feature Name>
+
+Source: <spec file or description>
+Generated: <date>
+
+## Prompt 1: <title>
+- [ ] Complete
+
+<implementation instructions>
+
+### Expected outcome
+<what should work after this prompt>
+
+### Test
+<how to verify>
+
+---
+
+## Prompt 2: <title>
+- [ ] Complete
+...
+```
+
+Alternative format — checklist style:
+```markdown
+- [ ] Prompt 1: <title> — <instructions>
+- [ ] Prompt 2: <title> — <instructions>
+```
+
+**Execution strategy:**
+
+1. Read the micro-prompt document, identify all prompt blocks
+2. Find the first uncompleted prompt (unchecked `- [ ]`)
+3. Execute that prompt's instructions — implement the code changes described
+4. Run the project's test suite (or the prompt-specific test if given)
+5. If tests pass: mark the prompt as complete (`- [x]`), commit, move to next prompt
+6. If tests fail: one fix attempt, then revert and mark prompt as FAILED, move to next prompt
+7. Each prompt = one batch item. Budget: 1 prompt per cycle unless prompt is trivial (XS)
+8. Record `prompts_remaining` count in cycle update — when 0, `prompts_complete` stop fires
+
+**Key rules:**
+- Execute prompts in document order — NEVER skip ahead or reorder
+- Each prompt is atomic — commit after each successful prompt
+- A failed prompt does NOT block subsequent prompts (mark failed, continue)
+- The prompt document is the plan — do not re-plan or expand scope beyond what each prompt says
+
+### Generate Mode (spec found without corresponding prompt document)
+
+When a specification document is found that doesn't have a matching micro-prompt document, decompose it into ordered prompts.
+
+**Generation strategy:**
+
+1. Read the spec document thoroughly
+2. Identify all discrete implementation steps
+3. Order steps by dependency — foundation first, features that depend on earlier steps later
+4. For each step, write a prompt block containing:
+   - Clear title describing the change
+   - Implementation instructions (files to create/modify, logic to implement)
+   - Expected outcome (what should work after this prompt)
+   - Test instruction (how to verify the prompt succeeded)
+5. Write the micro-prompt document to `.planning/prompts/<spec-slug>-prompts.md`
+6. Each generated document = one batch item (typically M or L size)
+
+**Decomposition heuristics:**
+- One prompt per logical unit of work (one function, one API endpoint, one component)
+- Each prompt should be independently testable
+- Prompts should be 5-30 minutes of implementation work each
+- Aim for 5-20 prompts per spec (split large specs, combine trivial items)
+- Include a "Prompt 0: Project setup" if the spec requires new dependencies or scaffolding
+- Include a final "Prompt N: Integration test" that verifies the full feature end-to-end
+
+**After generation:** The document is written and committed. The next cycle will detect it in execute mode and begin executing prompts sequentially.
+
+<failure_pattern_capture>
+When the same failure pattern appears in 2+ items within a campaign, capture it for future runs.
+
+**Detection:** After marking an item FAILED, check if the error classification matches any previous failure in this campaign:
+- Same error type (e.g., "test regression in unrelated module")
+- Same file or module involved
+- Same root cause category (e.g., "missing null check pattern", "import path mismatch")
+
+**Capture (when pattern repeats):**
+Append to `.planning/focus/failure-patterns.md`:
+```markdown
+## Pattern: {short description}
+- **First seen:** Cycle {N}, Item {ID}
+- **Recurrence:** Cycle {M}, Item {ID2}
+- **Error type:** {classification}
+- **Root cause:** {what actually went wrong}
+- **Avoidance rule:** {what to check before attempting similar items}
+- **Files involved:** {paths}
+```
+
+**Use (on subsequent cycles):**
+Before executing an item, check if its target files or error category match a known failure pattern. If so:
+- Apply the avoidance rule BEFORE implementing
+- If the pattern suggests the item will fail (e.g., "all items touching module X regress"), skip with reason "matches known failure pattern — defer to manual investigation"
+
+This prevents the campaign from burning budget on items that will predictably fail.
+</failure_pattern_capture>
 
 ## NEVER DO
 
-- Invoke the Skill tool (no `/pan:focus-scan`, `/pan:focus-plan`, `/pan:focus-exec`)
-- Stop or pause between phases (unless a safety harness triggers)
-- Ask the user questions after category selection (Phases 1-3 are fully autonomous)
-- Skip the baseline test capture (Phase 1)
-- Continue after a test regression (circuit breaker is mandatory)
-- Expand scope beyond what the scan found
-- Run more cycles than --max-cycles
-- Spend more points than --total-budget
-- Skip recording cycle results via --update
-- Change test expectations to match broken code
-- Use `git add -A` or `git add .` — stage specific files only
+- Invoke the Skill tool — scan/plan/exec must run inline so state stays coherent across cycles
+- Stop or pause between phases — interruptions break the autonomous loop and lose cycle momentum
+- Ask the user questions after category selection — the whole point is autonomous execution; questions defeat that
+- Skip the baseline test capture — without a baseline, the regression circuit breaker has nothing to compare against
+- Continue after a test regression — a test count decrease means code was broken; continuing compounds the damage
+- Expand scope beyond what the scan found — scope creep in an autonomous loop compounds unpredictably across cycles
+- Run more cycles than --max-cycles — the limit exists to cap total cost and prevent runaway loops
+- Spend more points than --total-budget — the budget cap is the user's cost control mechanism
+- Skip recording cycle results via --update — unrecorded cycles break resume, status, and stop-condition checks
+- Change test expectations to match broken code — this hides bugs instead of fixing them
+- Use `git add -A` or `git add .` — bulk staging can accidentally commit secrets, build artifacts, or unrelated changes
 
 ## ALWAYS DO
 

package/commands/pan/focus-design.md

@@ -41,9 +41,74 @@ If you find yourself analyzing PAN command files, agent definitions, or `pan-too
 
 ---
 
-## MANDATORY: Complete All Phases For Selected Mode
+## Tool Selection Priority
 
-When `/pan:focus-design` is invoked, execute ALL phases for the selected mode automatically. Do NOT stop to ask questions between phases. Do NOT skip phases beyond what the mode specifies. Complete the FULL investigation and produce all output artifacts. The only permitted pause is the Strategy Gate in Phase 3 (if the user passed `--gate`).
+Use the simplest sufficient tool for each research operation:
+1. **Grep/Glob** — for finding patterns and files in the local codebase
+2. **Read** — for examining specific files identified by Grep/Glob
+3. **Bash** — for git history, test runs, build commands
+4. **Agent (subagent)** — for broad exploration spanning many files (>5 reads)
+5. **WebSearch/WebFetch** — for external research after local sources are exhausted
+6. **mcp__context7__*** — for library documentation lookups
+
+Prefer local evidence over web research. Start with the codebase, then broaden.
+
+## Context Management Across Phases
+
+This pipeline spans 10+ phases. Manage context to maintain quality:
+- **KEEP:** Problem statement, success criteria, key architectural decisions, file paths being designed for
+- **SUMMARIZE:** Research findings (compress to key takeaways after each research phase), competitive analysis results
+- **DISCARD:** Raw web fetch content after extracting relevant data, superseded design drafts
+- After Phase 3 (Strategic Analysis), summarize all findings from Phases 0-3 into a compact brief before entering design phases
+
+**Progressive context loading — load only what the current phase needs:**
+
+| Phase | What to Load | What NOT to Load Yet |
+|-------|-------------|---------------------|
+| 0. Problem | User's feature description, project README | Implementation details, test files |
+| 1. Landscape | Web search results, competitor docs | Project internals |
+| 2. Codebase | Relevant source files (Glob→Grep→Read) | Unrelated modules, full test suite |
+| 3. Strategic | Findings from 0-2 (summarized) | Raw web content (discard after summary) |
+| 4-6. Design | Architecture files, key modules, API surface | Test implementation details |
+| 7-8. Spec | Design decisions from 4-6, test patterns | Research raw data (long gone) |
+| 9. Output | Spec template, ADR template | Everything else (already in spec) |
+
+**Why:** A 10-phase pipeline that loads everything in Phase 0 exhausts context by Phase 5. Each phase loads only its inputs, summarizes its outputs, and discards its raw data.
+
+---
+
+## Reasoning Protocol
+
+For research and analysis phases (0, 1, 2, 3), follow observe-think-act:
+1. **OBSERVE** — State what you found (code patterns, competitive data, user needs)
+2. **THINK** — Reason about what this means for the design
+3. **ACT** — Record the finding and move to the next investigation step
+This keeps research structured and prevents rabbit holes.
+
+## Meta-Prompting: Self-Generated Investigation Strategy
+
+Before starting Phase 0, generate your own investigation plan based on the feature description:
+
+```
+Given: "{feature description}"
+My investigation strategy:
+1. What is the core problem? → {how I'll validate it}
+2. Who are the competitors? → {what to search for}
+3. What codebase areas are affected? → {what to Glob/Grep for}
+4. What are the likely architectural constraints? → {what to read}
+5. What risks should I watch for? → {security, performance, compatibility}
+6. What is the ideal output format? → {spec structure for this feature type}
+```
+
+This self-generated strategy adapts to the specific feature rather than following a generic checklist. A "add caching layer" feature needs different investigation than "add OAuth provider" — the meta-prompt captures that difference upfront.
+
+**After Phase 3, regenerate:** The strategy may need revision based on what you've learned. Update it before entering design phases.
+
+---
+
+## Complete All Phases For Selected Mode
+
+When `/pan:focus-design` is invoked, execute all phases for the selected mode automatically. Do not stop to ask questions between phases or skip phases beyond what the mode specifies. Complete the full investigation and produce all output artifacts. The only permitted pause is the Strategy Gate in Phase 3 (if the user passed `--gate`).
 
 **Modes (mutually exclusive — pick one, default `--full`):**