pan-wizard 2.8.1 → 2.9.1

package/README.md

@@ -47,7 +47,7 @@ PAN is the context engineering layer that makes Claude Code reliable. It breaks
 └─────────────────────┬───────────────────────────────────────┘
                       │ invokes
 ┌─────────────────────▼───────────────────────────────────────┐
-│  COMMANDS (40 .md files + 4 CLI operations)                 │
+│  COMMANDS (42 .md files + 4 CLI operations)                 │
 │  Thin orchestrators that spawn agents and route results     │
 └─────────────────────┬───────────────────────────────────────┘
                       │ spawns
@@ -149,7 +149,7 @@ node bin/install.js --claude --local
 Installs to `./.claude/` for testing modifications before contributing.
 
 ```bash
-npm test                # 1649 unit tests
+npm test                # 1747 unit tests
 npm run test:scenarios  # Scenario tests (install + integration)
 npm run test:all        # All tests (unit + scenario)
 ```
@@ -580,6 +580,8 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/pan:focus-auto` | Continuous scan→plan→exec loop with purpose-driven categories and 5-layer safety harness |
 | `/pan:focus-sync` | Detect and report stale documentation counts |
 | `/pan:focus-design` | 10-phase strategic feature investigation pipeline |
+| `/pan:focus-drift-walking` | Walk project tree, detect doc-code drift, score severity, auto-repair |
+| `/pan:focus-doc-audit` | Multi-dimensional document audit with 8-dimension quality scoring |
 
 <sup>¹ Contributed by reddit user OracleGreyBeard</sup>
 

package/bin/install.js

@@ -1501,8 +1501,11 @@ function install(isGlobal, runtime = 'claude') {
       console.error(`  ${yellow}✗${reset} package.json write failed: ${e.message}`);
       failures.push('package.json');
     }
+  }
 
+  if (!isCodex && !isOpencode) {
     // Copy hooks from dist/ (bundled with dependencies)
+    // Hooks are only supported by Claude Code, Gemini, and Copilot CLI
     // Template paths for the target runtime (replaces '.claude' with correct config dir)
     try {
       const hooksSrc = path.join(src, 'hooks', 'dist');
@@ -1549,6 +1552,26 @@ function install(isGlobal, runtime = 'claude') {
   // Report any backed-up local patches
   reportLocalPatches(targetDir, runtime);
 
+  // Post-install self-check: verify critical files exist before declaring success
+  const selfCheckIssues = [];
+  const panToolsPath = path.join(targetDir, 'pan-wizard-core', 'bin', 'pan-tools.cjs');
+  if (!fs.existsSync(panToolsPath)) selfCheckIssues.push('pan-tools.cjs missing');
+  const manifestFullPath = path.join(targetDir, MANIFEST_NAME);
+  if (fs.existsSync(manifestFullPath)) {
+    try {
+      const mfst = JSON.parse(fs.readFileSync(manifestFullPath, 'utf8'));
+      const fileCount = Object.keys(mfst.files || {}).length;
+      if (fileCount < 50) selfCheckIssues.push(`manifest has only ${fileCount} files (expected 150+)`);
+    } catch { selfCheckIssues.push('manifest unreadable'); }
+  } else {
+    selfCheckIssues.push('manifest missing');
+  }
+  if (selfCheckIssues.length > 0) {
+    console.error(`\n  ${yellow}⚠ Post-install check found issues:${reset}`);
+    for (const issue of selfCheckIssues) console.error(`    - ${issue}`);
+    console.error(`  Run ${cyan}pan-tools validate deployment${reset} for full diagnostics.\n`);
+  }
+
   if (isCodex) {
     return { settingsPath: null, settings: null, statuslineCommand: null, runtime };
   }

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