prizmkit 1.1.106 → 1.1.108

package/bundled/skills/_metadata.json

@@ -1,7 +1,7 @@
 {
-  "version": "1.1.106",
+  "version": "1.1.108",
   "skills": {
-    "prizm-kit": {
+    "prizmkit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",
       "tier": "foundation",
       "category": "prizmkit-skill",
@@ -164,7 +164,7 @@
     "core": {
       "description": "All skills: full spec-driven cycle + orchestration + planning + recovery",
       "skills": [
-        "prizm-kit",
+        "prizmkit",
         "prizmkit-init",
         "prizmkit-prizm-docs",
         "prizmkit-plan",
@@ -190,7 +190,7 @@
     "minimal": {
       "description": "Minimal closed-loop workflow: full spec-driven cycle with .prizmkit/prizm-docs/ architecture sync and code review",
       "skills": [
-        "prizm-kit",
+        "prizmkit",
         "prizmkit-init",
         "prizmkit-prizm-docs",
         "prizmkit-plan",

package/bundled/skills/app-planner/SKILL.md

@@ -46,7 +46,7 @@ If you believe the task is better suited for a different workflow, you MUST:
 - Claude Code → `CLAUDE.md`
 - CodeBuddy → `CODEBUDDY.md`
 - `all` → all three files.
-- Only when the manifest is missing, fall back to installed PrizmKit-owned platform files such as `.codex/agents/*.toml`, `.claude/commands/prizm-kit.md`, or `.codebuddy/skills/prizm-kit/SKILL.md`. Do not treat a generic `.agents/` directory as Codex.
+- Only when the manifest is missing, fall back to installed PrizmKit-owned platform files such as `.codex/agents/*.toml`, `.claude/commands/prizmkit.md`, or `.codebuddy/skills/prizmkit/SKILL.md`. Do not treat a generic `.agents/` directory as Codex.
 
 **After planning is complete**, you MUST:
 1. Present the summary of captured project-level context (vision, conventions, architecture decisions, project brief)

package/bundled/skills/app-planner/references/architecture-decisions.md

@@ -30,7 +30,7 @@ After Phase 2 (Confirm constraints and tech assumptions), before Phase 3 (Captur
    - `claude` → append to `CLAUDE.md`
    - `codebuddy` → append to `CODEBUDDY.md`
    - `all` → append to all three files. Legacy manifests may contain `both`; treat it as read-only compatibility and append to `CLAUDE.md` and `CODEBUDDY.md` only when encountered.
-   - Only when the manifest is missing, fall back to PrizmKit-owned install artifacts: `.codex/agents/*.toml`, `.claude/commands/prizm-kit.md`, `.codebuddy/skills/prizm-kit/SKILL.md`.
+   - Only when the manifest is missing, fall back to PrizmKit-owned install artifacts: `.codex/agents/*.toml`, `.claude/commands/prizmkit.md`, `.codebuddy/skills/prizmkit/SKILL.md`.
    - Do not treat a generic `.agents/` directory as Codex; it may contain unrelated third-party skills.
    - If no platform can be determined, skip (no project instruction file).
 

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

@@ -1,23 +1,50 @@
 ---
 name: "bug-fix-workflow"
-description: "Interactive single-bug fix in current session. Guides through deep diagnosis Q&A → triage → reproduce → fix → review → commit without the background pipeline. Use this skill when the user wants to fix one specific bug right now, interactively. Trigger on: 'fix this bug', 'debug this', 'fix B-001', 'help me fix', 'let me fix this bug myself', 'interactive fix', 'manually fix bug'."
+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'."
 ---
 
 # Bug Fix Workflow
 
-Fix a single bug interactively within the current AI CLI session. This is the in-session counterpart to `bugfix-pipeline-launcher` (which runs multiple bugs in the background).
+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:
+
+- **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.
+
+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.
 
 ## 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 prefers hands-on fixing over background pipeline
+- 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 has multiple bugs to fix in batch → `bug-planner` + `bugfix-pipeline-launcher`
-- User wants to plan/collect bugs without fixing → `bug-planner`
-- User wants background autonomous fixing → `bugfix-pipeline-launcher`
+- 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
+
+The shared contract is:
+
+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.
+
+### Terminology
+
+| 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. |
 
 ## Input
 
@@ -29,38 +56,70 @@ Fix a single bug interactively within the current AI CLI session. This is the in
 | 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
 
-For trivial bugs with clear root cause and minimal scope:
+Fast Path is for a simple single bug fixed interactively in the current session/current workspace.
 
 ### Eligibility Criteria (ALL must be true)
-- Root cause is immediately obvious (typo, missing null check, wrong variable name, off-by-one)
-- Fix is ≤10 lines of code in a single file
+
+- 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
-- Existing tests cover the affected path (or bug is in untested utility)
-- No data model or API changes
+- 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 → `fix/<BUG_ID>-<short-desc>`
-2. Write reproduction test → confirm failing
-3. Apply fix → confirm test passes + full suite green
+
+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. Ask user: "Quick fix applied. Verify before commit? (Y/skip)"
-6. Commit with `fix(<scope>):` prefix
+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, reproduction test, full test suite pass, code review, user merge decision.
+**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
 
-### Phase 0: Branch Setup
+### Phase 0: Branch Setup — Fast Path Only
 
-**Goal**: Create an isolated working branch to keep main clean.
+**Goal**: Create an isolated working branch while staying in the current workspace.
 
 1. **Check current branch**:
    ```bash
@@ -74,7 +133,7 @@ For trivial bugs with clear root cause and minimal scope:
 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.
 
-**CHECKPOINT CP-BFW-0**: On a dedicated fix branch, not main/shared branch.
+**CHECKPOINT CP-BFW-0**: On a dedicated fix branch in the current workspace, not main/shared branch.
 
 ---
 
@@ -82,8 +141,6 @@ For trivial bugs with clear root cause and minimal scope:
 
 **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.
 
-**Fast Path Decision Point**: After initial information gathering (Step 1.1), evaluate the Fast Path Eligibility Criteria in Step 1.4. If ALL simple bug criteria are met, use `AskUserQuestion` to let the user choose the execution approach. Only proceed with fast path implementation if the user explicitly selects "Fix now". Never guess the user's intent from text — always present the interactive selection.
-
 **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.
 
 #### Step 1.1: Initial Bug Information Gathering
@@ -91,6 +148,7 @@ For trivial bugs with clear root cause and minimal scope:
 - 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 1.2: Systematic Bug Clarification
 
@@ -116,64 +174,38 @@ Ask the user: "Is this summary accurate? Any details to add?"
 
 ---
 
-#### Step 1.4: Complexity Assessment
+#### Step 1.4: Complexity Assessment & Approach Selection
 
-After confirming bug understanding, assess whether this bug needs structured planning:
+After confirming bug understanding, assess whether this belongs on Fast Path or Pipeline Path.
 
-**Simple bug → Fast Path candidate**: meets ALL of the Fast Path §Eligibility Criteria (obvious root cause, ≤10 lines, single file, no cross-module impact, no data/API changes).
+**Simple single bug → Fast Path candidate**: meets ALL Fast Path eligibility criteria above.
 
-**User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
+**Complex or batch bug work → Pipeline Path candidate**: meets ANY Pipeline Path criteria above.
 
-```
-AskUserQuestion:
-  question: "This bug appears straightforward. How would you like to proceed?"
-  header: "Approach"
-  options:
-    - label: "Fix now (fast path)"
-      description: "Implement the fix directly in this session — branch → test → fix → review → commit"
-    - label: "Add to bug-fix-list.json (pipeline)"
-      description: "Add this bug to .prizmkit/plans/bug-fix-list.json via bug-planner, then use bugfix-pipeline-launcher to launch autonomous pipeline execution"
-    - label: "Full diagnosis"
-      description: "Continue with in-depth analysis before deciding"
-```
-
-- **Fix now** → Proceed with Fast Path Workflow (Phase 0 branch already set up)
-- **Add to bug-fix-list.json** → Invoke `bug-planner` to add this bug to `.prizmkit/plans/bug-fix-list.json`, then suggest user run `bugfix-pipeline-launcher` to start the pipeline. End this workflow.
-- **Full diagnosis** → Continue with full diagnosis (Phase 2 Triage)
-
-**Complex bug → Planning Path** (ANY is true):
-- Cross-module impact (>2 files affected)
-- Data model or API changes required
-- Root cause is uncertain or multi-layered
-- Fix requires structural changes
-- Multiple interrelated symptoms
-
-**User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
+**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: "This bug appears complex and will need structured planning. How would you like to proceed?"
+  question: "How would you like to proceed?"
   header: "Approach"
   options:
-    - label: "Plan and fix now"
-      description: "Create a plan and fix it in this session using /prizmkit-plan + /prizmkit-implement"
-    - label: "Add to bug-fix-list.json (pipeline)"
-      description: "Add this bug to .prizmkit/plans/bug-fix-list.json via bug-planner, then use bugfix-pipeline-launcher to launch autonomous pipeline execution"
+    - 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"
 ```
 
-- **Plan and fix now** → Invoke `/prizmkit-plan` with `artifact_dir=.prizmkit/bugfix/<BUG_ID>/`:
-  1. `/prizmkit-plan` generates `spec.md` (bug description + acceptance criteria) + `plan.md` (fix strategy + test specifications) under `.prizmkit/bugfix/<BUG_ID>/`
-  2. Invoke `/prizmkit-implement` to execute the plan (TDD: write failing reproduction test → implement fix → tests pass)
-  3. Run `/prizmkit-code-review` for quality check
-  4. Commit via `/prizmkit-committer` with `fix(<scope>):` prefix
-  5. **End workflow** — skip Phase 2-7. No `/prizmkit-retrospective` (bug fixes are incomplete features, not new architecture)
-- **Add to bug-fix-list.json** → Invoke `bug-planner` to add this bug to `.prizmkit/plans/bug-fix-list.json`, then suggest user run `bugfix-pipeline-launcher` to start the pipeline. End this workflow.
+- **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.
 
 **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
+### Phase 2: Triage — Fast Path Only
 
 **Goal**: Locate affected code, identify root cause, classify severity.
 
@@ -198,26 +230,24 @@ AskUserQuestion:
 
 **CHECKPOINT CP-BFW-2**: Root cause identified and diagnosis confirmed by user.
 
-### Phase 3: Reproduce
+### Phase 3: Reproduce — Fast Path Only
 
-**Goal**: Create a failing test that proves the bug exists.
+**Goal**: Create a failing test or reproduction check that proves the bug exists.
 
-> **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 — making it a regression guard.
+> **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.
 
-1. **Write a reproduction test** that demonstrates the bug:
-   - Name: `<module>.test.ts` → add a test case named `should handle <bug scenario>`
-   - The test captures the exact failure condition
-2. **Run the test** → confirm it **fails** (red)
+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."
 
-If the bug is hard to reproduce automatically (e.g. environment-specific):
+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
 
-**CHECKPOINT CP-BFW-3**: Bug reproduction test written and confirmed failing.
+**CHECKPOINT CP-BFW-3**: Bug reproduction test/check written and confirmed failing, or manual checklist recorded.
 
-### Phase 4: Fix
+### Phase 4: Fix — Fast Path Only
 
 **Goal**: Implement the minimal fix. Red test → green.
 
@@ -226,64 +256,65 @@ If the bug is hard to reproduce automatically (e.g. environment-specific):
    - 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** → must **pass** (green)
-3. **Run the full module test suite** → must pass (no regressions)
+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?"
 
-**CHECKPOINT CP-BFW-4**: Fix implemented and all tests passing (reproduction + regression).
+**CHECKPOINT CP-BFW-4**: Fix implemented and relevant tests passing.
 
 If the fix causes test regressions:
 - Show which tests broke and why
 - Revise the fix (max 3 attempts)
-- If still failing after 3 attempts, escalate to user with analysis
+- If still failing after 3 attempts, ask whether to switch to Pipeline Path for structured autonomous fixing
 
-### Phase 5: Review
+### Phase 5: Review — Fast Path Only
 
 **Goal**: Verify fix quality before committing.
 
 1. **Run `/prizmkit-code-review`** to review the fix:
    - Reviews git diff against the bug context (root cause, fix approach, affected areas)
-   - Iterative Reviewer Agent + Dev Agent loop (max 3 rounds)
    - 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 or revise
+3. **If NEEDS_FIXES after max rounds**: Present unresolved findings to user, ask whether to proceed, revise, or switch to Pipeline Path
 
 **CHECKPOINT CP-BFW-5**: Code review completed and quality verified.
 
-### Phase 6: User Verification
+### Phase 6: User Verification — Fast Path Only
 
 **Goal**: Let the user verify the fix works as expected before committing.
 
-1. **Ask user**: "Fix passes all tests. Would you like to verify before committing?"
+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 (e.g. `npm run dev`, `python manage.py runserver`), start it, wait for user confirmation: "Fix verified? (yes/no)"
+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 user reports the fix is NOT working:
 - Return to Phase 4 (max 2 more attempts)
-- If still failing: escalate with analysis
+- If still failing: ask whether to switch to Pipeline Path
 
-**CHECKPOINT CP-BFW-6**: Fix manually verified by user and working as expected.
+**CHECKPOINT CP-BFW-6**: Fix manually verified by user or verification explicitly skipped.
 
 ---
 
-### Phase 7: Commit & Merge
+### Phase 7: Retrospective, Commit & Merge — Fast Path Only
 
 **Goal**: Commit the fix and offer to merge back to the original branch.
 
-1. **Run `/prizmkit-committer`**:
+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
+   - 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
-   - No `/prizmkit-retrospective` — bug fixes are incomplete features, not new architecture worth documenting
-2. **Ask merge preference**:
+3. **Ask merge preference**:
    ```
    Fix committed on branch `fix/<BUG_ID>-<short-desc>`.
    What would you like to do?
@@ -291,72 +322,84 @@ If user reports the fix is NOT working:
    (b) Keep fix branch (for PR review workflow)
    (c) Decide later
    ```
-3. **If (a)**:
+4. **If (a)**:
    ```bash
    git checkout <original-branch>
    git merge fix/<BUG_ID>-<short-description>
    git branch -d fix/<BUG_ID>-<short-description>
    ```
-4. **If (b)**: Inform user: "Branch `fix/<BUG_ID>-<short-desc>` retained. Create a PR when ready."
-5. **If bug came from .prizmkit/plans/bug-fix-list.json**: inform user to update bug status
-   ```
-   Bug B-001 fixed and committed.
-   To update the bug list: manually set B-001 status to "fixed" in .prizmkit/plans/bug-fix-list.json
-   Or retry the pipeline to pick up remaining bugs.
-   ```
+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.
 
+---
+
+## Monitor — Pipeline Path Only
+
+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.
+
+| 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 |
+
+Use the Python runtime command surface exposed by `bugfix-pipeline-launcher`; do not use retired platform-specific wrappers.
+
+---
+
 ## Resume — Interruption Recovery
 
 The workflow supports resuming from the last completed phase by detecting existing artifacts.
 
-**Detection logic**: Resume from git branch state plus, for the complex "Plan and fix now" path, the planning docs under `.prizmkit/bugfix/<BUG_ID>/`:
-
 | State Found | Resume From |
-|---------------|------------|
-| Not on a `fix/<BUG_ID>-*` branch | Phase 0: Branch Setup |
+|-------------|-------------|
+| 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 |
-| `spec.md` + `plan.md` exist, no code changes | Phase 4: Fix (complex path) |
-| Reproduction test written, fix not yet green | Phase 4: Fix |
+| 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 |
 
-**Resume**: If a `fix/<BUG_ID>-*` branch already exists (and, for the complex path, a matching `.prizmkit/bugfix/<BUG_ID>/` directory), resume from the detected state instead of starting fresh.
+**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.
 
 ---
 
 ## Artifacts
 
-This workflow favors code + tests over documents — a bug fix is an incomplete feature, not new architecture worth heavy documentation. What gets produced depends on the path taken:
+This workflow favors code + tests over documents. What gets produced depends on the selected path:
 
-- **Fast path / interactive path** (Phase 2–7): no markdown artifacts. Output is the fix code, a reproduction test, and a git commit on the fix branch. Diagnosis and triage are presented inline to the user, not written to disk.
-- **Complex "Plan and fix now" path**: `/prizmkit-plan` writes `spec.md` (bug description + acceptance criteria) and `plan.md` (fix strategy + test specs) under `.prizmkit/bugfix/<BUG_ID>/`. These are the only persisted documents, and they double as resume anchors.
+- **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.
 
 ## Comparison with Pipeline Bug Fix
 
-| Dimension | bug-fix-workflow (this skill) | bugfix-pipeline-launcher |
-|-----------|-------------------------------|-----------------------------|
-| Scope | One bug at a time | All bugs in batch |
-| Execution | Interactive, in-session | Foreground or background daemon |
-| Diagnosis | Deep interactive Q&A with user | Automated from bug description |
-| Branch | Creates `fix/<BUG_ID>-*` branch | Pipeline manages branches |
+| 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 (Phase 6) | No (automated) |
-| Best for | Complex bugs needing user input | Batch of well-defined bugs |
-| Artifacts | Code + test (+ spec/plan on complex path) | Pipeline-managed |
+| 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>):` |
 
 ## Error Handling
 
 | Scenario | Action |
 |----------|--------|
-| Bug ID not found in .prizmkit/plans/bug-fix-list.json | Ask user to provide bug details directly |
+| 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) |
-| Root cause unclear after investigation | Present findings, ask user for guidance |
+| 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 |
 
@@ -364,13 +407,16 @@ This workflow favors code + tests over documents — a bug fix is an incomplete
 
 | From | To | Condition |
 |------|----|-----------|
-| `bug-planner` | **this skill** | User picks one bug to fix interactively |
-| `bugfix-pipeline-launcher` | **this skill** | User wants to fix a stuck/complex bug manually |
-| **this skill** | `bugfix-pipeline-launcher` | After fixing, user wants to continue with remaining bugs |
-| **this skill** | `prizmkit-committer` | Built into Phase 7 (pure commit, no doc sync) |
+| `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 |
 
 ## Output
 
-- Fixed code with reproduction test
-- On the complex path only: `.prizmkit/bugfix/<BUG_ID>/spec.md` + `plan.md`
-- Git commit with `fix(<scope>):` prefix on dedicated fix branch
+- **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.