prizmkit 1.1.110 → 1.1.112

package/bundled/skills/bug-fix-workflow/SKILL.md

@@ -1,422 +1,277 @@
 ---
 name: "bug-fix-workflow"
-description: "Triage-based bug-fix workflow. Clarifies and diagnoses bug reports, then lets the user choose Fast Path for a simple single-bug fix in the current session/current workspace or Pipeline Path for complex/batch bugs via bug-planner → bugfix-pipeline-launcher. Preserves bug-specific rules: ordinary bug fixes skip retrospective unless structural docs change. Trigger on: 'fix this bug', 'debug this', 'fix B-001', 'help me fix', 'interactive fix', 'manually fix bug', 'batch bug fix'."
+description: "Triage-based bug-fix workflow for interactive single-bug repair or pipeline handoff. Diagnoses enough to choose Fast Path, Pipeline Path, continue diagnosis, or existing-list launch; keeps a thicker Fast Path for one bug with reproduction, fix, review, user verification, commit, and merge choice. Use for 'fix this bug', 'debug this', stack traces, failed tests, bug IDs, manual bug fixes, or batch bugs that may need bug-planner -> bugfix-pipeline-launcher. Ordinary bug fixes skip retrospective unless structural docs or architecture change."
 ---
 
 # Bug Fix Workflow
 
-Triage-based entry point for bug fixing. The workflow clarifies the bug, assesses difficulty, asks the user to choose an approach, then follows one of two paths:
+Triage-based entry point for bug fixing. Unlike feature/refactor workflows, this workflow intentionally keeps a thicker Fast Path because high-quality single-bug repair depends on interactive diagnosis, reproduction, verification, and commit decisions.
 
-- **Fast Path** — a simple single-bug fix is implemented interactively in the **current session** and **current workspace**.
-- **Pipeline Path** — complex or batch bug work is planned with `bug-planner`, launched with `bugfix-pipeline-launcher`, then monitored.
+## Responsibility Boundary
 
-Bug fixes are incomplete features, so ordinary bug fixes do **not** run `/prizmkit-retrospective`. Run `/prizmkit-retrospective` only when the fix intentionally changes architecture or structural `.prizmkit/prizm-docs/` content.
+This workflow owns:
+- Single-bug interactive diagnosis and repair in the current workspace.
+- Lightweight routing between Fast Path, Pipeline Path, existing-list launch, and continued diagnosis.
+- User confirmation before workspace mutation.
+- Reproduction evidence, root-cause fix, code review, user verification, commit, and merge decision for Fast Path.
 
-## When to Use
-
-- User wants to fix **one specific bug** right now, with full visibility
-- User has a stack trace or error and wants interactive debugging
-- User wants the workflow to triage whether the bug is simple enough for current-session Fast Path
-- User has multiple or complex bugs and wants this workflow to hand off to the bug-fix pipeline
-
-**Do NOT use when:**
-- User only wants to plan/collect bugs without fixing → `bug-planner`
-- User only wants to launch an existing `.prizmkit/plans/bug-fix-list.json` → `bugfix-pipeline-launcher`
-- User wants to build features → `feature-workflow`
-- User wants to refactor code → `refactor-workflow`
-
-## Overview
+This workflow does not own:
+- Batch bug list generation, headless execution readiness, severity/priority calibration, schema validation, or plan review gates — those belong to `bug-planner`.
+- Pipeline execution mode, runtime configuration, command assembly, status/log/stop/retry details — those belong to `bugfix-pipeline-launcher`.
 
-The shared contract is:
+Ordinary bug fixes do not run `/prizmkit-retrospective`. Run retrospective only when the fix intentionally changes durable architecture, module boundaries, public interfaces, or `.prizmkit/prizm-docs/` structure.
 
-1. **Diagnose** — understand the bug through evidence, Q&A, reproduction context, and relevant code/docs.
-2. **Assess difficulty** — decide whether it is a simple single-bug Fast Path candidate or complex/batch Pipeline Path candidate.
-3. **AskUserQuestion approach selection** — present selectable options; never silently choose the path.
-4. **Execute selected path**:
-   - **Fast Path**: dedicated fix branch in the current workspace → reproduce → fix → tests → `/prizmkit-code-review` → optional `/prizmkit-retrospective` only for structural docs → `/prizmkit-committer` → merge choice.
-   - **Pipeline Path**: `bug-planner` → `bugfix-pipeline-launcher` → monitoring.
+## When to Use
 
-### Terminology
+Use this workflow when:
+- The user wants to fix one specific bug interactively.
+- The user provides a stack trace, error message, failing test, or bug ID and wants diagnosis.
+- The user wants to decide whether a bug is simple enough for current-session repair.
+- The user provides multiple or complex bugs and wants routing to the bug-fix pipeline.
 
-| Term | Meaning |
-|------|---------|
-| **Fast Path** | Current-session/current-workspace fix for a simple single bug. It does not start the bugfix pipeline. |
-| **Pipeline Path** | Complex or batch bug execution. Planner handoff goes to `bug-planner`; launcher handoff goes to `bugfix-pipeline-launcher`; monitoring follows only after launch. |
-| **Current session** | The interactive AI CLI session that is already diagnosing the bug with the user. |
-| **Current workspace** | The current git checkout and working tree. For bug fixes, this still includes creating/using the dedicated `fix/<BUG_ID>-*` branch in that same workspace. |
-| **Monitoring** | Status/log follow-up for a launched bugfix pipeline; it is not part of the Fast Path. |
+Do not use this workflow when:
+- The user only wants to collect or plan bugs -> use `bug-planner`.
+- The user only wants launch/status/logs/retry for an existing bug list -> use `bugfix-pipeline-launcher`.
+- The user wants feature development -> use `feature-workflow`.
+- The user wants behavior-preserving restructuring -> use `refactor-workflow`.
 
-## Input
+## Input Sources
 
-**PRECONDITION:**
+Accept any of these sources:
 
-| Input Source | Detection | Example |
+| Source | Example | Route implication |
 |---|---|---|
-| Bug-fix-list.json entry | User says "fix B-001" → read entry from `.prizmkit/plans/bug-fix-list.json` | `fix B-001` |
-| Stack trace / error message | User pastes error directly | `TypeError: Cannot read property...` |
-| Natural language description | User describes the problem | "login page crashes on submit" |
-| Failed test | User references a failing test file | `src/auth/__tests__/login.test.ts` |
-| Batch or complex bug set | User provides many bugs, failing logs, or interrelated symptoms | "These 7 tests fail after the upgrade" |
-
-At least one input source must be provided. If none is clear, ask the user to describe the bug.
-
----
-
-## Fast Path
-
-Fast Path is for a simple single bug fixed interactively in the current session/current workspace.
-
-### Eligibility Criteria (ALL must be true)
-
-- Exactly one bug is in scope
-- Root cause is immediately obvious or quickly confirmed (typo, missing null check, wrong variable name, off-by-one, narrow logic bug)
-- Fix is small and localized (normally one file, minimal code)
-- No cross-module impact
-- No data model or public API changes
-- Existing tests cover the affected path, or a focused reproduction test can be added quickly
-
-### Fast Path Workflow
-
-1. Branch Setup → use/create `fix/<BUG_ID>-<short-desc>` in the current workspace
-2. Write or confirm reproduction test/check → confirm failing when practical
-3. Choose the current-session implementation depth:
-   - **Obvious tiny fix**: apply the minimal fix directly, then confirm reproduction passes + relevant regression tests pass
-   - **Planned current-session fix**: run `/prizmkit-plan` to create bug-focused `spec.md` + `plan.md`, then run `/prizmkit-implement` to execute that plan in the current workspace
-4. Run `/prizmkit-code-review` for quality check
-5. Run `/prizmkit-retrospective` only if the fix intentionally changes architecture or structural `.prizmkit/prizm-docs/`
-6. Commit via `/prizmkit-committer` with `fix(<scope>):` prefix
-7. Ask merge preference
-
-**Fast Path still requires**: fix branch, root-cause-based fix, regression evidence, code review, commit through `/prizmkit-committer`, and user merge decision. When the current-session fix needs a written plan, Fast Path uses `/prizmkit-plan` and `/prizmkit-implement` instead of switching to the background pipeline.
-
----
-
-## Pipeline Path
-
-Pipeline Path is for complex or batch bug work.
-
-### Pipeline Path Criteria (ANY is true)
-
-- Multiple bugs need coordinated or batch execution
-- Cross-module impact (>2 files or >1 module affected)
-- Data model or public API changes required
-- Root cause is uncertain or multi-layered
-- Fix requires structural changes
-- Multiple interrelated symptoms need dependency ordering
-- User wants background autonomous fixing
-
-### Pipeline Path Workflow
-
-1. Planner handoff — invoke `bug-planner` with the bug evidence, diagnosis summary, and batch context
-2. `bug-planner` writes/updates `.prizmkit/plans/bug-fix-list.json`
-3. Launcher handoff — invoke `bugfix-pipeline-launcher` with the validated bug list
-4. `bugfix-pipeline-launcher` handles execution mode and starts foreground/background pipeline execution
-5. Monitor status/logs only after the launcher has started the pipeline
-
----
-
-## Execution
+| Bug ID from `.prizmkit/plans/bug-fix-list.json` | `fix B-001` | Can use Fast Path for one bug or launcher for pipeline |
+| Stack trace / error message | `TypeError: ...` | Diagnose before route selection |
+| Natural-language report | `login crashes on submit` | Diagnose before route selection |
+| Failed test | `src/auth/login.test.ts fails` | Use test as reproduction evidence |
+| Multiple bugs/logs | `these 7 tests fail` | Usually Pipeline Path through `bug-planner` |
 
-### Phase 0: Branch Setup — Fast Path Only
+If no input source is clear, ask the user to describe the bug before proceeding.
 
-**Goal**: Create an isolated working branch while staying in the current workspace.
+## Route Selection
 
-1. **Check current branch**:
-   ```bash
-   git branch --show-current
-   ```
-2. **If on `main` or a shared branch**: Create and switch to fix branch:
-   ```bash
-   git checkout -b fix/<BUG_ID>-<short-description>
-   ```
-   Example: `git checkout -b fix/B-001-login-null-crash`
-3. **If already on a fix branch**: Confirm with user: "Continue on current branch `<branch-name>`, or create a new one?"
-4. **Record the original branch name** for later merge.
+### Step 1: Diagnose enough to choose a path
 
-**CHECKPOINT CP-BFW-0**: On a dedicated fix branch in the current workspace, not main/shared branch.
+Do not create a branch or modify files before path selection.
 
----
-
-### Phase 1: Deep Bug Diagnosis — Interactive Q&A
-
-**Goal**: Fully understand the bug before touching any code. Vague bug reports lead to incorrect fixes that mask the real issue or introduce new bugs.
-
-**CRITICAL RULE**: Ask as many questions as needed until the bug is fully understood. Do NOT rush into code. A misdiagnosed bug leads to a wrong fix, which is worse than no fix.
+Gather enough information to decide whether this is:
+- One bug suitable for interactive Fast Path.
+- A complex single bug or batch bug set better suited for `bug-planner`.
+- An existing bug list operation better suited for `bugfix-pipeline-launcher`.
+- Still too unclear and needs continued diagnosis.
 
-#### Step 1.1: Initial Bug Information Gathering
+For systematic clarification, read `${SKILL_DIR}/references/bug-diagnosis.md` when the report lacks reproduction, expected vs actual behavior, affected scope, data/state trigger, or error details.
 
-- If bug ID given (e.g. B-001): read entry from `.prizmkit/plans/bug-fix-list.json` — but DO NOT assume the description is complete
-- If raw error/stack trace: extract error message, affected files, line numbers
-- If natural language description: start the deep-dive Q&A below
-- If multiple bugs/logs are provided: keep batch context intact for possible Pipeline Path
+### Step 2: Confirm bug understanding
 
-#### Step 1.2: Systematic Bug Clarification
+Before asking for an execution path, summarize:
 
-Read `${SKILL_DIR}/references/bug-diagnosis.md` for the full question framework — reproduction conditions, expected vs actual behavior, scope/impact, data/state, and error details. Adapt to what the user has already provided; skip answered questions.
+```markdown
+## Bug Understanding
 
-#### Step 1.3: Confirmation Before Triage
-
-Summarize the bug understanding:
-
-```
-Bug Summary:
-- Symptom: [what happens]
-- Reproduction: [exact steps]
-- Environment: [where it occurs]
-- Expected: [correct behavior]
-- Impact: [who/what is affected]
-- Data trigger: [what data/state causes it]
+- Symptom:
+- Reproduction:
+- Environment:
+- Expected behavior:
+- Actual behavior:
+- Impact:
+- Suspected affected area:
+- Unknowns:
 ```
 
-Ask the user: "Is this summary accurate? Any details to add?"
+Ask whether the summary is accurate. If key fields are still unknown, include `Continue diagnosis` as an approach option.
 
-**CHECKPOINT CP-BFW-1**: Bug fully understood and confirmed by user.
+### Step 3: Ask for approach selection
 
----
-
-#### Step 1.4: Complexity Assessment & Approach Selection
-
-After confirming bug understanding, assess whether this belongs on Fast Path or Pipeline Path.
-
-**Simple single bug → Fast Path candidate**: meets ALL Fast Path eligibility criteria above.
+Use `AskUserQuestion`; do not render path options as plain text.
 
-**Complex or batch bug work → Pipeline Path candidate**: meets ANY Pipeline Path criteria above.
-
-**User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options. Tailor the question text to the assessment, but keep the path names and handoffs explicit.
-
-```
-AskUserQuestion:
-  question: "How would you like to proceed?"
-  header: "Approach"
-  options:
-    - label: "Fix now (Fast Path — current session/current workspace)"
-      description: "Use the dedicated fix branch in this workspace, reproduce, fix, review, optionally sync docs if structural, and commit"
-    - label: "Use Pipeline Path (bug-planner → bugfix-pipeline-launcher)"
-      description: "Generate .prizmkit/plans/bug-fix-list.json with bug-planner, then launch autonomous execution with bugfix-pipeline-launcher"
-    - label: "Continue diagnosis"
-      description: "Ask more questions and inspect more context before choosing an approach"
+```text
+Question: How would you like to proceed?
+Header: Approach
+Options:
+- Fix now (Fast Path) — create/use a fix branch in this workspace, reproduce, fix, review, verify, commit, and choose merge behavior
+- Use Pipeline Path — bug-planner creates/reviews bug-fix-list.json, then bugfix-pipeline-launcher configures execution
+- Continue diagnosis — inspect or ask more before choosing a path
 ```
 
-- **Fix now (Fast Path)** → Continue to Phase 2 Triage, then Phase 3-7.
-- **Use Pipeline Path** → Invoke `bug-planner` to create/update `.prizmkit/plans/bug-fix-list.json`, then invoke `bugfix-pipeline-launcher` to launch pipeline execution. After launch, monitor status/logs. End Fast Path phases.
-- **Continue diagnosis** → Continue investigation before asking for approach selection again.
+For an auto-discovered existing bug list:
 
-**NEVER proceed with direct code changes without explicit user confirmation via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
-
----
-
-### Phase 2: Triage — Fast Path Only
+```text
+Question: Existing bug-fix-list.json found. What should we do with it?
+Header: Bug list
+Options:
+- Launch existing list — hand off to bugfix-pipeline-launcher
+- Inspect summary first — show bug count/status, then ask again
+- Update/re-plan — hand off to bug-planner in append/update mode
+- Fix one bug interactively — choose a single bug for Fast Path
+```
 
-**Goal**: Locate affected code, identify root cause, classify severity.
+If the user explicitly asked to run an existing list, that explicit request counts as path selection; hand off directly to `bugfix-pipeline-launcher`.
 
-> **Triage**: Classify error into: Runtime / Network / Auth / Data / Resource / Logic / Config / External. Check `.prizmkit/prizm-docs/` TRAPS for known patterns first. If a TRAPS match is found, use documented solution and reference the specific `.prizmkit/prizm-docs/` entry. If no match, trace the call chain from the stack frame to identify root cause from first principles.
+## Workflow Handoff Brief
 
-1. **Read project context**: `.prizmkit/prizm-docs/root.prizm` → relevant L1/L2 docs for affected modules
-2. **Locate affected code**: read the files mentioned in the error/stack trace or identified during diagnosis
-3. **Check known issues**: search `.prizmkit/prizm-docs/` TRAPS sections for matching patterns
-4. **If database-related**: read existing schema/model files to understand the data layer
-   ```bash
-   find . -maxdepth 4 -type f \( -name "*.prisma" -o -name "*.sql" -o -path "*/migrations/*" -o -path "*/models/*" -o -name "schema.*" -o -name "*.entity.*" \) -not -path '*/node_modules/*' -not -path '*/.git/*' | head -20
-   ```
-5. **Classify**: root cause (confirmed/suspected), blast radius, fix complexity
-6. **Present diagnosis to user**:
-   ```
-   Bug: Login page crash on submit
-   Root Cause: AuthService.handleLogin() receives null token when API returns 401
-   Affected Files: src/services/auth.ts (L42), src/pages/login.tsx (L28)
-   Fix Complexity: Low (null check + error handling)
-   ```
-   Ask: "Does this diagnosis look right? Should I proceed with the fix?"
+When handing off to `bug-planner`, `bugfix-pipeline-launcher`, or Fast Path L1 skills, include this prompt brief. Do not write the brief to disk.
 
-**CHECKPOINT CP-BFW-2**: Root cause identified and diagnosis confirmed by user.
+```markdown
+## Workflow Handoff Brief
 
-### Phase 3: Reproduce — Fast Path Only
+### Source
+- workflow: bug-fix-workflow
+- selected_path: fast_path | pipeline_path | existing_list_launch | continue_diagnosis
 
-**Goal**: Create a failing test or reproduction check that proves the bug exists.
+### Bug Goal
+- original_request: <preserve the user's wording>
+- normalized_bug_summary: <symptom, expected/actual, impact>
 
-> **Reproduce**: For API bugs: generate curl/HTTP request sequence with assertions. For UI bugs: generate step-by-step interaction guide. For logic bugs: generate unit test (arrange/act/assert). For data bugs: generate seed data + query sequence. The reproduction must FAIL with current behavior and be designed to PASS after the fix is applied.
+### Evidence
+- reproduction: <known steps or failing test>
+- error_output: <stack trace, logs, console output, or omitted>
+- affected_paths: <files/modules/tests mentioned by user or discovered during diagnosis>
+- environment: <runtime/browser/OS/data state if known>
 
-1. **Write a reproduction test/check** that demonstrates the bug.
-2. **Run the test/check** → confirm it **fails** when practical.
-3. **Show result to user**: "Reproduction test written and confirmed failing."
+### Scope
+- included: <bug behavior to fix>
+- excluded: <unrelated cleanup, refactor, feature work>
 
-If the bug is hard to reproduce automatically:
-- Ask the user for reproduction steps
-- Write a manual reproduction checklist instead
-- Proceed to Phase 4 with the manual checklist
+### Decision
+- route_reason: <why this path was selected>
+- user_confirmed: yes
 
-**CHECKPOINT CP-BFW-3**: Bug reproduction test/check written and confirmed failing, or manual checklist recorded.
+### Next Skill Instruction
+- For bug-planner: Use this brief as input; perform your own required clarification, validation, generation, and review gate.
+- For Fast Path: Fix only the root cause for this bug and preserve unrelated behavior.
+```
 
-### Phase 4: Fix — Fast Path Only
+## Fast Path — Single Bug Interactive Repair
 
-**Goal**: Implement the minimal fix. Red test → green.
+Fast Path starts only after the user selects `Fix now`.
 
-1. **Implement the fix**:
-   - Change the minimum amount of code to fix the root cause
-   - Do NOT refactor or add unrelated improvements — fix the bug only
-   - Follow existing code conventions (read from `.prizmkit/prizm-docs/` RULES/PATTERNS)
-   - If the fix involves database changes: read existing schema first, follow existing naming/constraint conventions
-2. **Run the reproduction test/check** → must **pass** (green)
-3. **Run the relevant module test suite** → must pass (no regressions)
-4. **Show the fix to user**:
-   - Summary of changes made
-   - Test results (reproduction + regression)
-   - Ask: "Fix looks good? Any concerns?"
+### Phase 1: Branch setup
 
-**CHECKPOINT CP-BFW-4**: Fix implemented and relevant tests passing.
+1. Check current branch.
+2. If on `main` or a shared branch, create a dedicated `fix/<BUG_ID-or-short-desc>` branch.
+3. If already on a fix branch, ask whether to continue on it or create a new one.
+4. Record the original branch for the merge decision.
 
-If the fix causes test regressions:
-- Show which tests broke and why
-- Revise the fix (max 3 attempts)
-- If still failing after 3 attempts, ask whether to switch to Pipeline Path for structured autonomous fixing
+This phase occurs after path selection so Pipeline Path users do not receive unnecessary workspace mutations.
 
-### Phase 5: Review — Fast Path Only
+### Phase 2: Root-cause triage
 
-**Goal**: Verify fix quality before committing.
+1. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs for affected modules.
+2. Read files from the error, stack trace, failing test, or bug summary.
+3. Check relevant TRAPS in `.prizmkit/prizm-docs/`.
+4. Identify root cause, blast radius, and fix complexity.
+5. Present diagnosis and ask whether to proceed.
 
-1. **Run `/prizmkit-code-review`** to review the fix:
-   - Reviews git diff against the bug context (root cause, fix approach, affected areas)
-   - Checks: root cause addressed (not just symptom), edge cases covered, reproduction test thoroughness, project conventions
-2. **If PASS**: Proceed to Phase 6
-3. **If NEEDS_FIXES after max rounds**: Present unresolved findings to user, ask whether to proceed, revise, or switch to Pipeline Path
+### Phase 3: Reproduce
 
-**CHECKPOINT CP-BFW-5**: Code review completed and quality verified.
+1. Write or identify a focused reproduction test/check when practical.
+2. Confirm the reproduction fails before the fix when practical.
+3. If automatic reproduction is impractical, record a manual checklist and explain the limitation.
 
-### Phase 6: User Verification — Fast Path Only
+### Phase 4: Fix
 
-**Goal**: Let the user verify the fix works as expected before committing.
+1. Make the smallest root-cause fix.
+2. Avoid unrelated refactoring or feature work.
+3. Run the reproduction test/check.
+4. Run the relevant regression tests.
+5. If regressions appear, revise up to three attempts, then ask whether to continue, switch to Pipeline Path, or stop.
 
-1. **Ask user**: "Fix passes tests. Would you like to verify before committing?"
-   - **(a) Run the app** — Start the dev server so you can manually test the fix scenario
-   - **(b) Run a specific command** — Specify a test or script to run
-   - **(c) Skip verification** — Proceed directly to commit (automated tests already pass)
-2. **If (a)**: Detect and suggest dev server command, start it, wait for user confirmation: "Fix verified? (yes/no)"
-3. **If (b)**: Run the specified command, show results, ask confirmation
-4. **If (c)**: Proceed to Phase 7
+If the fix requires a written implementation plan, invoke `/prizmkit-plan` with the handoff brief, then `/prizmkit-implement`. Do not switch to Pipeline Path solely because a current-session plan is useful.
 
-If user reports the fix is NOT working:
-- Return to Phase 4 (max 2 more attempts)
-- If still failing: ask whether to switch to Pipeline Path
+### Phase 5: Review
 
-**CHECKPOINT CP-BFW-6**: Fix manually verified by user or verification explicitly skipped.
+Run `/prizmkit-code-review` against the bug context and current diff. The review should check root-cause coverage, reproduction strength, edge cases, regressions, and project conventions.
 
----
+If review needs fixes, apply accepted fixes directly in the current workspace and rerun the review loop according to `/prizmkit-code-review` rules.
 
-### Phase 7: Retrospective, Commit & Merge — Fast Path Only
-
-**Goal**: Commit the fix and offer to merge back to the original branch.
-
-1. **Run `/prizmkit-retrospective` only when structurally needed**:
-   - Skip for ordinary bug fixes with no architecture/doc structure change
-   - Run only if the fix changes durable architecture, module boundaries, public interfaces that should be reflected in `.prizmkit/prizm-docs/`, or the docs themselves
-2. **Run `/prizmkit-committer`**:
-   - Commit message: `fix(<scope>): <description>`
-   - Include both fix code and reproduction test/check artifacts
-   - Do NOT push (user decides when to push)
-   - `/prizmkit-committer` is a pure commit tool — it does NOT modify `.prizmkit/prizm-docs/` or any project files
-3. **Ask merge preference**:
-   ```
-   Fix committed on branch `fix/<BUG_ID>-<short-desc>`.
-   What would you like to do?
-   (a) Merge to <original-branch> and delete fix branch
-   (b) Keep fix branch (for PR review workflow)
-   (c) Decide later
-   ```
-4. **If (a)**:
-   ```bash
-   git checkout <original-branch>
-   git merge fix/<BUG_ID>-<short-description>
-   git branch -d fix/<BUG_ID>-<short-description>
-   ```
-5. **If (b)**: Inform user: "Branch `fix/<BUG_ID>-<short-desc>` retained. Create a PR when ready."
-6. **If bug came from `.prizmkit/plans/bug-fix-list.json`**: inform user to update bug status or rerun the pipeline for remaining bugs.
-
-**CHECKPOINT CP-BFW-7**: Fix committed and merge decision made.
+### Phase 6: User verification
 
----
+Use `AskUserQuestion` for the verification decision:
 
-## Monitor — Pipeline Path Only
+```text
+Question: Fix passes the available checks. Would you like to verify before committing?
+Header: Verify
+Options:
+- Run the app — start the relevant dev command and manually check the scenario
+- Run a command — user provides a test/check command
+- Skip verification — automated checks are enough for now
+```
 
-After `bugfix-pipeline-launcher` starts the pipeline, monitor status/logs when the user asks. Monitoring applies only after `bugfix-pipeline-launcher` has started a pipeline.
+If the user reports the fix still fails, return to Phase 4. After two additional failed attempts, ask whether to continue or switch to Pipeline Path.
 
-| User says | Action |
-|-----------|--------|
-| "status" / "progress" | Show bugfix pipeline progress |
-| "logs" | Show recent bugfix log activity |
-| "stop" | Stop the bugfix pipeline (state preserved) |
-| "show B-002 logs" | Show specific bug item's session log |
+### Phase 7: Retrospective, commit, and merge decision
 
-Use the Python runtime command surface exposed by `bugfix-pipeline-launcher`; do not use retired platform-specific wrappers.
+1. Run `/prizmkit-retrospective` only if the fix changed durable architecture/docs or structural interfaces.
+2. Run `/prizmkit-committer` with a `fix(<scope>):` message.
+3. Use `AskUserQuestion` for merge behavior:
 
----
+```text
+Question: Fix committed on the fix branch. What would you like to do next?
+Header: Merge
+Options:
+- Merge back — merge to the original branch and delete the fix branch
+- Keep branch — retain it for PR/review workflow
+- Decide later — leave the branch as-is
+```
 
-## Resume — Interruption Recovery
+Do not push unless the user explicitly asks.
 
-The workflow supports resuming from the last completed phase by detecting existing artifacts.
+## Pipeline Path
 
-| State Found | Resume From |
-|-------------|-------------|
-| Not on a `fix/<BUG_ID>-*` branch and Fast Path selected | Phase 0: Branch Setup |
-| On `fix/<BUG_ID>-*` branch, no diagnosis done | Phase 1: Deep Bug Diagnosis |
-| Reproduction test/check written, fix not yet green | Phase 4: Fix |
-| Fix code + passing tests, not yet reviewed | Phase 5: Review |
-| Review passed, not committed | Phase 6: User Verification |
-| Committed on fix branch | Phase 7: Merge decision |
-| `.prizmkit/plans/bug-fix-list.json` exists and Pipeline Path selected | `bugfix-pipeline-launcher` or pipeline monitoring |
+Use Pipeline Path for multiple bugs, uncertain/broad root cause, structural fix planning, or background autonomous execution.
 
-**Resume**: If both Fast Path branch state and pipeline list state exist, ask whether to continue the current-workspace Fast Path or resume Pipeline Path monitoring.
+1. Invoke `bug-planner` with the handoff brief.
+2. `bug-planner` performs bug collection, severity/priority calibration, headless readiness checks, validation, and plan review.
+3. After `bug-planner` reports a validated `.prizmkit/plans/bug-fix-list.json`, show a concise summary: bug count, severity distribution, and review/validation outcome.
+4. Ask whether to proceed to launch.
+5. If yes, invoke `bugfix-pipeline-launcher`.
 
----
+Do not duplicate launcher execution-mode or configuration questions in this workflow; the launcher owns them.
 
-## Artifacts
+## Existing List Operations
 
-This workflow favors code + tests over documents. What gets produced depends on the selected path:
+If the user explicitly requests launch/status/logs/retry/stop for an existing bug list, invoke `bugfix-pipeline-launcher` with the user's intent and list path.
 
-- **Fast Path**: fix code, reproduction test/check, optional structural `.prizmkit/prizm-docs/` update only when needed, and one `fix(<scope>):` commit from `/prizmkit-committer` on the dedicated fix branch.
-- **Pipeline Path**: `.prizmkit/plans/bug-fix-list.json` from `bug-planner`, pipeline execution via `bugfix-pipeline-launcher`, monitoring updates, and pipeline-managed commits.
+If the user wants to add, edit, deduplicate, or validate bugs, invoke `bug-planner`.
 
-## Comparison with Pipeline Bug Fix
+## Resume Guidance
 
-| Dimension | Fast Path in this skill | Pipeline Path (`bug-planner` → `bugfix-pipeline-launcher`) |
-|-----------|-------------------------|-------------------------------------------------------------|
-| Scope | One simple bug | Complex single bug or many bugs in batch |
-| Execution | Interactive, current session/current workspace | Foreground or background pipeline |
-| Diagnosis | Deep interactive Q&A with user | Automated from bug descriptions and planner output |
-| Branch | Dedicated `fix/<BUG_ID>-*` branch in current workspace | Pipeline manages per-item branches/worktrees |
-| Visibility | Full user interaction at each phase | Async, check status periodically |
-| User verification | Yes before commit | No by default; automated checks per item |
-| Best for | Simple bug needing immediate focused fix | Complex/batch bugs needing planner + launcher execution |
-| Artifacts | Code + reproduction test/check + commit | `.prizmkit/plans/bug-fix-list.json` + pipeline-managed outputs |
-| Retrospective | Skip unless structural docs/architecture changed | Pipeline items handle their own lifecycle rules |
-| Commit prefix | `fix(<scope>):` | `fix(<scope>):` |
+| State found | Action |
+|---|---|
+| On fix branch with uncommitted code changes | Resume Fast Path at review or verification depending on test/review status |
+| Fast Path `spec.md` / `plan.md` exists | Ask whether to continue implementation, review, or re-plan |
+| Fix committed on fix branch | Ask merge preference |
+| Valid `.prizmkit/plans/bug-fix-list.json` exists and user wants execution | Invoke `bugfix-pipeline-launcher` |
+| Bug list exists but intent is unclear | Ask launch / inspect / update / fix one bug interactively |
+| Recovery is ambiguous after interruption | Use `recovery-workflow` |
 
 ## Error Handling
 
-| Scenario | Action |
-|----------|--------|
-| Bug ID not found in `.prizmkit/plans/bug-fix-list.json` | Ask user to provide bug details directly |
-| User's bug description is too vague | Ask systematic clarification questions (Phase 1) |
-| Many bugs provided to Fast Path | Recommend Pipeline Path and hand off to `bug-planner` → `bugfix-pipeline-launcher` after AskUserQuestion |
-| Cannot reproduce the bug | Ask for more context, try alternative reproduction |
-| Fix causes regressions | Revert, analyze, retry (max 3 rounds), then consider Pipeline Path |
-| Root cause unclear after investigation | Present findings and ask whether to continue diagnosis or use Pipeline Path |
-| Affected files are in unfamiliar module | Read `.prizmkit/prizm-docs/` L1/L2 for that module first |
-| Branch conflict during merge | Show conflict, ask user to resolve or keep branch |
+| Situation | Action |
+|---|---|
+| Bug report is too vague | Ask systematic clarification questions from `references/bug-diagnosis.md` |
+| Bug ID missing from bug list | Ask user for details or route to `bug-planner` to update the list |
+| Many bugs provided to Fast Path | Recommend Pipeline Path and ask via `AskUserQuestion` |
+| Cannot reproduce automatically | Record manual reproduction and proceed only with user awareness |
+| Fix causes regressions | Revise up to three attempts, then ask whether to continue or switch paths |
+| Root cause remains unclear | Continue diagnosis or switch to Pipeline Path based on user choice |
+| Merge conflict occurs | Stop and report the conflict; ask whether user wants manual resolution or to keep the branch |
 
-## HANDOFF
+## Handoff Map
 
 | From | To | Condition |
-|------|----|-----------|
-| `bug-planner` | **this skill** | User picks one planned bug to inspect or fix interactively |
-| `bugfix-pipeline-launcher` | **this skill** | User wants to manually diagnose a stuck pipeline bug |
-| **this skill** | `/prizmkit-code-review` | Fast Path fix is implemented in the current workspace |
-| **this skill** | `/prizmkit-retrospective` | Fast Path bug fix changed durable architecture/docs and structural sync is needed |
-| **this skill** | `/prizmkit-committer` | Fast Path fix is reviewed and ready to commit |
-| **this skill** | `bug-planner` | User selects Pipeline Path for complex or batch bug work |
-| `bug-planner` | `bugfix-pipeline-launcher` | Planner handoff produced validated `.prizmkit/plans/bug-fix-list.json` |
-| `bugfix-pipeline-launcher` | **this skill** | Launcher handoff completed and monitoring/status follow-up is needed |
+|---|---|---|
+| `bug-fix-workflow` | `/prizmkit-plan` / `/prizmkit-implement` | Fast Path needs a written current-session plan |
+| `bug-fix-workflow` | `/prizmkit-code-review` | Fast Path fix is implemented |
+| `bug-fix-workflow` | `/prizmkit-retrospective` | Structural docs/architecture changed |
+| `bug-fix-workflow` | `/prizmkit-committer` | Fast Path fix is reviewed and ready |
+| `bug-fix-workflow` | `bug-planner` | User selects Pipeline Path or wants bug-list planning |
+| `bug-planner` | `bug-fix-workflow` | Planner completed from workflow-origin Pipeline Path |
+| `bug-fix-workflow` | `bugfix-pipeline-launcher` | User confirms launch after planner completion or explicitly requests existing-list execution |
 
 ## Output
 
-- **Fast Path**: fixed code with reproduction test/check, optional structural doc sync only when warranted, and a git commit with `fix(<scope>):` prefix on a dedicated fix branch.
-- **Pipeline Path**: `.prizmkit/plans/bug-fix-list.json`, bugfix pipeline execution, monitoring updates, and pipeline-managed fix commits.
+- Fast Path: root-cause fix, reproduction evidence, relevant tests/checks, review result, optional structural doc sync, one fix commit, and merge decision.
+- Pipeline Path: handoff brief, validated `.prizmkit/plans/bug-fix-list.json` from `bug-planner`, and pipeline launch/status handled by `bugfix-pipeline-launcher`.