prizmkit 1.1.7 → 1.1.9

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

@@ -1,7 +1,6 @@
 ---
 name: "bug-fix-workflow"
-tier: companion
-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', 'fix this bug', 'interactive fix', 'manually fix bug'. (project)"
+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', 'fix this bug', 'interactive fix', 'manually fix bug'."
 ---
 
 # Bug Fix Workflow
@@ -27,7 +26,7 @@ Fix a single bug interactively within the current AI CLI session. This is the in
 
 | Input Source | Detection | Example |
 |---|---|---|
-| Bug-fix-list.json entry | User says "fix B-001" → read entry from `bug-fix-list.json` | `fix B-001` |
+| 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` |
@@ -83,13 +82,13 @@ 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 above. If ALL criteria are met, ask the user: "This looks like a straightforward fix. Use fast path? (Y/n)". If yes, skip directly to the Fast Path Workflow (branch setup already done in Phase 0). If no or uncertain, continue with full diagnosis.
+**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, ask the user: "This looks like a straightforward fix. Use fast path? (Y/n)". If yes, skip directly to the Fast Path Workflow (branch setup already done in Phase 0). If no or uncertain, continue with full diagnosis.
 
 **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
 
-- If bug ID given (e.g. B-001): read entry from `bug-fix-list.json` — but DO NOT assume the description is complete
+- 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
 
@@ -146,6 +145,35 @@ Ask the user: "Is this summary accurate? Any details to add?"
 
 ---
 
+#### Step 1.4: Complexity Assessment
+
+After confirming bug understanding, assess whether this bug needs structured planning:
+
+**Simple bug → Fast Path** (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
+- No cross-module impact
+- Existing tests cover the affected path (or bug is in untested utility)
+- No data model or API changes
+
+→ Proceed with Fast Path Workflow (Phase 0 branch already set up)
+
+**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
+
+→ Invoke `/prizmkit-plan` with `artifact_dir=.prizmkit/bugfix/<BUG_ID>/`:
+  1. prizmkit-plan generates `spec.md` + `plan.md` under `.prizmkit/bugfix/<BUG_ID>/`
+  2. Invoke `/prizmkit-implement` to execute the plan
+  3. After implementation, resume this workflow at Phase 5 (Review)
+
+Ask the user: "This bug appears [simple/complex]. Use [fast path/structured planning]? (Y/n)"
+
+---
+
 ### Phase 2: Triage
 
 **Goal**: Locate affected code, identify root cause, classify severity.
@@ -169,6 +197,8 @@ Ask the user: "Is this summary accurate? Any details to add?"
    ```
    Ask: "Does this diagnosis look right? Should I proceed with the fix?"
 
+**CHECKPOINT CP-BFW-2**: Root cause identified and diagnosis confirmed by user.
+
 ### Phase 3: Reproduce
 
 **Goal**: Create a failing test that proves the bug exists.
@@ -186,6 +216,8 @@ If the bug is hard to reproduce automatically (e.g. environment-specific):
 - 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.
+
 ### Phase 4: Fix
 
 **Goal**: Implement the minimal fix. Red test → green.
@@ -202,6 +234,8 @@ If the bug is hard to reproduce automatically (e.g. environment-specific):
    - Test results (reproduction + regression)
    - Ask: "Fix looks good? Any concerns?"
 
+**CHECKPOINT CP-BFW-4**: Fix implemented and all tests passing (reproduction + regression).
+
 If the fix causes test regressions:
 - Show which tests broke and why
 - Revise the fix (max 3 attempts)
@@ -228,6 +262,8 @@ If the fix causes test regressions:
    Ready to commit.
    ```
 
+**CHECKPOINT CP-BFW-5**: Code review completed and quality verified.
+
 ### Phase 6: User Verification
 
 **Goal**: Let the user verify the fix works as expected before committing.
@@ -244,6 +280,8 @@ If user reports the fix is NOT working:
 - Return to Phase 4 (max 2 more attempts)
 - If still failing: escalate with analysis
 
+**CHECKPOINT CP-BFW-6**: Fix manually verified by user and working as expected.
+
 ---
 
 ### Phase 7: Commit & Merge
@@ -254,7 +292,10 @@ If user reports the fix is NOT working:
    - Commit message: `fix(<scope>): <description>`
    - Include both fix code and reproduction test
    - Do NOT push (user decides when to push)
-   - Do NOT run `/prizmkit-retrospective` — bug fixes do not update `.prizm-docs/`
+   - **Bug Fix Documentation Policy**:
+     - DEFAULT: Run `/prizmkit-retrospective` with structural sync only (update file counts, interfaces, dependencies). Skip knowledge injection.
+     - UPDATE DOCS when bug fix causes: interface signature changes, dependency additions/removals, observable behavior changes to existing features, or newly discovered TRAPs (gotchas/pitfalls)
+     - When any of the above apply, run full `/prizmkit-retrospective` (Job 1 + Job 2)
    - `/prizmkit-committer` is a pure commit tool — it does NOT modify `.prizm-docs/` or any project files
 2. **Ask merge preference**:
    ```
@@ -271,13 +312,15 @@ If user reports the fix is NOT working:
    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 bug-fix-list.json**: inform user to update bug status
+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 bug-fix-list.json
+   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.
    ```
 
+**CHECKPOINT CP-BFW-7**: Fix committed and merge decision made.
+
 ## Resume — Interruption Recovery
 
 The workflow supports resuming from the last completed phase by detecting existing artifacts.
@@ -323,7 +366,7 @@ Only 2 artifact files per bug, consistent with the pipeline convention.
 
 | Scenario | Action |
 |----------|--------|
-| Bug ID not found in 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) |
 | Cannot reproduce the bug | Ask for more context, try alternative reproduction |
 | Fix causes regressions | Revert, analyze, retry (max 3 rounds) |

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

@@ -1,12 +1,43 @@
 ---
 name: "bug-planner"
-tier: companion
-description: "Interactive bug planning that produces bug-fix-list.json for the Bug Fix Pipeline. Supports multiple input formats: error logs, stack traces, user reports, failed tests, monitoring alerts. Use this skill whenever the user has bugs to report, errors to parse, or test failures to organize. Trigger on: 'plan bug fixes', 'report bugs', 'I have some bugs', 'these tests are failing', 'here is an error log', 'parse these errors', 'generate bug list'. (project)"
+description: "Interactive bug planning that produces .prizmkit/plans/bug-fix-list.json for the Bug Fix Pipeline. Supports multiple input formats: error logs, stack traces, user reports, failed tests, monitoring alerts. Use this skill whenever the user has bugs to report, errors to parse, or test failures to organize. Trigger on: 'plan bug fixes', 'report bugs', 'I have some bugs', 'these tests are failing', 'here is an error log', 'parse these errors', 'generate bug list'."
 ---
 
 # Bug Planner
 
-Interactive skill that collects bug information from various input formats and generates a standardized `bug-fix-list.json` for the Bug Fix Pipeline. This is the bug-fix counterpart to `feature-planner` (which generates `feature-list.json`).
+Interactive skill that collects bug information from various input formats and generates a standardized `.prizmkit/plans/bug-fix-list.json` for the Bug Fix Pipeline.
+
+## Invocation Commitment (Hard Rule)
+
+When the user invokes `/bug-planner`, you MUST execute the bug-planner workflow. You must NEVER:
+- Decide on the user's behalf that the task "doesn't need bug-planner"
+- Skip bug-planner to jump directly to implementation or any other skill
+- Bypass the interactive phases because you judge the task to be "simple"
+
+If you believe the task is better suited for a different workflow, you MUST:
+1. Explain why you think a different path is more appropriate
+2. Ask the user explicitly whether they want to switch or continue with bug-planner
+3. Only switch if the user confirms
+
+The user chose this skill intentionally. Respect that choice.
+
+## Scope Boundary (Hard Rule)
+
+This skill is PLANNING ONLY. You must NEVER:
+- Create, modify, or delete source code files (*.js, *.ts, *.py, *.go, *.html, *.css, etc.)
+- Run build/install/test commands
+- Execute any bug fix action
+- Execute any implementation action beyond writing `.prizmkit/plans/bug-fix-list.json`
+
+Your ONLY writable outputs are:
+1. `.prizmkit/plans/bug-fix-list.json`
+2. Draft backups in `.prizmkit/plans/` (e.g., `bug-fix-list.draft.json`)
+
+After planning is complete, you MUST:
+1. Present the summary and recommended next step (invoking `bugfix-pipeline-launcher`)
+2. Ask the user explicitly whether they want to proceed to execution
+3. If the user wants to adjust → continue refining the bug list
+4. NEVER auto-execute the pipeline, launcher, or any fix step
 
 ## When to Use
 
@@ -17,9 +48,9 @@ User says:
 - After receiving bug reports, error logs, or failed test output
 
 **Do NOT use when:**
-- User wants to start fixing bugs now (use `bugfix-pipeline-launcher`)
-- User wants to fix a single bug interactively (use `bug-fix-workflow`)
-- User wants to plan features (use `feature-planner`)
+- User wants to start fixing bugs now → use `bugfix-pipeline-launcher`
+- User wants to fix a single bug interactively → use `bug-fix-workflow`
+- User wants to plan features → use `feature-planner`
 
 ## Intent Routing
 
@@ -30,9 +61,31 @@ This skill handles multiple operations. Determine the user's intent and execute
 | Plan bugs interactively | **Interactive Planning** | "plan bug fixes", "report bugs" |
 | Parse error logs into bugs | **From Log** | "parse this error log", "here's a stack trace", "parse these errors" |
 | Parse test failures into bugs | **From Tests** | "these tests are failing", "parse test output" |
-| Validate existing bug list | **Validate** | "validate bug list", "check bug-fix-list.json" |
+| Validate existing bug list | **Validate** | "validate bug list", "check .prizmkit/plans/bug-fix-list.json" |
 | Summarize bug list | **Summary** | "bug summary", "show bug list", "list bugs" |
 
+## Scenario Routing
+
+Classify user intent first:
+
+### Route A: New Bug List (No Existing Plan)
+
+Use when no `.prizmkit/plans/bug-fix-list.json` exists.
+
+Actions:
+1. Run full Interactive Planning (Phase 1-5)
+2. Generate initial `.prizmkit/plans/bug-fix-list.json`
+
+### Route B: Append to Existing Bug List
+
+Use when `.prizmkit/plans/bug-fix-list.json` already exists and user wants to add more bugs.
+
+Actions:
+1. Read existing `.prizmkit/plans/bug-fix-list.json` first (if missing, ask whether to start new plan)
+2. Continue with next sequential `B-NNN` IDs
+3. Preserve existing entries, append new bugs
+4. Re-run validation on the merged list
+
 ---
 
 ## Operation: Interactive Planning
@@ -41,78 +94,40 @@ Launch the interactive bug planning process through 5 phases.
 
 ### Phase 1: Project Context
 
-1. **Identify project**: Read project name and description from existing `feature-list.json` or ask user
-2. **Identify tech stack**: Read from `.prizmkit/config.json` `tech_stack` (preferred), then `feature-list.json` global_context, then `.prizm-docs/root.prizm`. Only ask user if none of these sources provide tech stack info.
+Gather project metadata from the project's own configuration and documentation — bug-planner is independent of feature-planner, so it reads project-level sources directly rather than depending on feature-list.json.
+
+1. **Identify project**: Read project name and description from these sources (first match wins):
+   - `.prizmkit/config.json` (`project_name`, `description` fields)
+   - `.prizm-docs/root.prizm` (project overview section)
+   - `CLAUDE.md` or `CODEBUDDY.md` (project instructions)
+   - `package.json` / `pyproject.toml` / `Cargo.toml` (name + description fields)
+   - If none found, ask the user
+2. **Identify tech stack**: Read from these sources (first match wins):
+   - `.prizmkit/config.json` `tech_stack` (preferred — contains language, frameworks, DB, etc.)
+   - `.prizm-docs/root.prizm` (architecture section)
+   - Auto-detect from project files (`package.json`, `requirements.txt`, `go.mod`, etc.)
+   - If none found, ask the user
 3. **Identify testing framework**: Read from `.prizmkit/config.json` `tech_stack.testing`, or auto-detect from package.json/requirements.txt/etc., or ask user
 4. **Clarify context** — if the project context, affected systems, or bug scope is unclear, ask questions one at a time (cite the unclear point, give a recommended answer with rationale) until you fully understand the environment. No limit on rounds or number of questions.
 
 Output: `project_name`, `project_description`, `global_context` fields populated.
 
+**Gate → CP-BP-1**: Tech stack and project info confirmed before proceeding.
+
 ### Phase 2: Bug Collection
 
 Accept bug information in ANY of these formats (auto-detect):
 
-#### Severity Auto-Classification Rules
-
-When extracting bugs, apply these rules to auto-suggest severity:
+#### Severity & Input Format References
 
-| Severity | Indicators | Examples |
-|----------|------------|----------|
-| **critical** | System crash, data loss, security breach, OOM, unrecoverable error | `Segmentation fault`, `OutOfMemoryError`, `SQL injection vulnerability`, `Database corrupted` |
-| **high** | Core feature broken, authentication failure, data integrity issue, timeout | `Auth token invalid`, `Payment failed`, `Connection timeout`, `500 Internal Server Error` |
-| **medium** | Feature partially broken, workaround exists, incorrect output | `CSV encoding issue`, `Pagination not working`, `Wrong date format`, `Missing validation` |
-| **low** | Cosmetic issue, minor inconvenience, edge case | `UI misalignment`, `Typo in error message`, `Slow loading (non-critical page)`, `Non-breaking warning` |
+When classifying severity, read `${SKILL_DIR}/references/severity-rules.md` for the auto-classification table (critical/high/medium/low indicators and special cases).
 
-**Special cases:**
-- Failed test → medium (unless test covers critical path, then high)
-- User report with "cannot use app" → high
-- User report with "annoying but works" → low
-
-#### Format A: Stack Trace / Error Log
-```
-TypeError: Cannot read property 'token' of null
-    at AuthService.handleLogin (src/services/auth.ts:42)
-    at LoginPage.onSubmit (src/pages/login.tsx:28)
-```
-→ Auto-extract: `error_source.type="stack_trace"`, `error_message`, `stack_trace`, `affected_modules`
-
-#### Format B: Natural Language User Report
-```
-When I click the login button with correct credentials, the page turns white.
-Expected: redirect to home page.
-Actual: white screen with no error message visible.
-```
-→ Auto-extract: `error_source.type="user_report"`, `reproduction_steps`, `description` (expected vs actual)
-
-#### Format C: Failed Test Output
-```
-FAIL src/services/__tests__/auth.test.ts
-  ● AuthService > handleLogin > should return token on success
-    Expected: "abc123"
-    Received: null
-```
-→ Auto-extract: `error_source.type="failed_test"`, `failed_test_path`, `error_message`
-
-#### Format D: Log Pattern
-```
-[2026-03-07 10:23:45] ERROR [auth-service] Connection timeout after 30000ms
-[2026-03-07 10:23:45] ERROR [auth-service] Failed to authenticate user: ETIMEDOUT
-[2026-03-07 10:23:46] ERROR [auth-service] Connection timeout after 30000ms
-```
-→ Auto-extract: `error_source.type="log_pattern"`, `log_snippet`, `affected_modules`
-
-#### Format E: Monitoring Alert
-```
-ALERT: CPU usage > 95% for auth-service pod (5min avg)
-ALERT: Error rate spike: 500 errors/min on /api/login endpoint
-```
-→ Auto-extract: `error_source.type="monitoring_alert"`, `error_message`, `affected_modules`
+When parsing user input, auto-detect the format and read `${SKILL_DIR}/references/input-formats.md` for extraction patterns. Supported formats: stack traces, user reports, failed tests, log patterns, monitoring alerts.
 
 **For each bug collected**, interactively confirm or fill in:
 - Title (auto-suggest from error message, user can edit)
 - Description (auto-generate expected vs actual, user can edit)
 - Severity (auto-suggest based on error type, user can override)
-- Affected feature (ask if known, map to existing F-NNN IDs)
 - Environment (ask or auto-detect from logs)
 - Verification type (suggest `automated` by default, ask user)
 - Acceptance criteria (auto-suggest based on description, user can edit)
@@ -120,30 +135,7 @@ ALERT: Error rate spike: 500 errors/min on /api/login endpoint
 
 **Per-bug clarification** — if the bug's root cause, reproduction steps, expected behavior, or scope is unclear from the provided information, ask focused questions one at a time (cite the unclear point, give a recommended answer with rationale) until the bug is fully understood. Do not finalize a bug entry with ambiguous details. No limit on the number of questions per bug.
 
-**Per-bug confirmation (mandatory)** — after extracting and clarifying each bug, present a structured summary for user review using this template:
-
-```
-┌─ Bug Confirmation: B-NNN ─────────────────────────────
-│ Title:       <auto-suggested title>
-│ Description: <expected vs actual behavior>
-│ Severity:    <auto-classified> | Verification: <type>
-│
-│ Reproduction: <steps if available, or "not provided">
-│ Affected:     <module/feature or "unknown">
-│
-│ ✅ Acceptance Criteria (fix verified when):
-│   1. <criterion — specific enough for automated pipeline to verify>
-│   2. <criterion>
-│
-│ ⚠️ Open Questions:
-│   - <any unclear points, or "None">
-└────────────────────────────────────────────────────────
-```
-
-Then ask three confirmation questions:
-1. "描述是否准确？是否需要修改？" / "Is the description accurate? Any corrections?"
-2. "是否需要补充更多细节？（复现步骤、环境信息、相关代码位置等）" / "Need to add more details? (reproduction steps, environment, related code locations, etc.)"
-3. "验证条件是否具体到 pipeline 可以自主判断修复成功？" / "Are the acceptance criteria specific enough that the pipeline can autonomously verify the fix?"
+**Per-bug confirmation (mandatory)** — after extracting and clarifying each bug, present a structured summary using the template in `${SKILL_DIR}/assets/bug-confirmation-template.md`, then ask the three confirmation questions defined there.
 
 The acceptance criteria are critical — they directly determine how the bugfix pipeline judges success or failure. Vague criteria like "login works" lead to shallow fixes; prefer specific, verifiable conditions like "POST /api/login with valid credentials returns 200 and a JWT token in the response body."
 
@@ -151,16 +143,18 @@ Only finalize the bug entry after user confirms all three points.
 
 **Multiple bugs per session**: After each bug, ask "Any more bugs to add? (yes/no)"
 
+**Gate → CP-BP-2**: All bugs extracted and confirmed by user.
+
 ### Phase 3: Prioritization & Review
 
-1. **Auto-assign priorities**: Based on severity (critical → high, high → high, medium → medium, low → low), adjustable by user
-   
+1. **Auto-assign priorities**: Based on severity, adjustable by user
+
    **Severity → Priority Mapping**:
    - `critical` severity → `high` priority (treated with highest urgency)
    - `high` severity → `high` priority
    - `medium` severity → `medium` priority
    - `low` severity → `low` priority
-   
+
    Note: Severity has 4 levels (critical, high, medium, low) but Priority has 3 levels (high, medium, low). Both critical and high severity bugs map to high priority.
 2. **Display summary table**:
    ```
@@ -172,14 +166,20 @@ Only finalize the bug entry after user confirms all three points.
 3. **Ask for adjustments**: "Want to reorder priorities, change severity, or remove any bugs?"
 4. **Detect potential duplicates**: If two bugs have similar error messages or affected modules, warn user
 
+**Gate → CP-BP-3**: Severity/priority assigned, duplicates resolved.
+
 ### Phase 4: Pre-Generation Completeness Review
 
-Before generating `bug-fix-list.json`, perform a holistic scan across all collected bugs. The bugfix pipeline runs autonomously — any ambiguity left here becomes a wrong assumption later.
+Before generating `.prizmkit/plans/bug-fix-list.json`, perform a holistic scan across all collected bugs. The bugfix pipeline runs autonomously — any ambiguity left here becomes a wrong assumption later.
 
-**Step 1 — Description adequacy scan**: For each bug, check:
+**Step 1 — Description adequacy scan (Headless Execution Readiness)**: The bugfix pipeline runs each bug through an autonomous AI session with NO human interaction. Every description must be unambiguous enough for headless execution. For each bug, check:
 - Description clearly states **expected** vs **actual** behavior (not just "X doesn't work")
 - Reproduction path is specific enough for the pipeline AI to locate the relevant code
 - If the bug involves user interaction, the trigger action is described (not just the symptom)
+- **Code location hints**: Where in the codebase should the AI look? (file paths, module names, function names)
+- **Verification method**: How should the AI verify the fix? (run specific test, check specific behavior)
+- Bad: "Login is broken" — too vague, AI will search the entire codebase
+- Good: "Login form at /login returns 500 when password field is empty. Expected: validation error 400. Root cause likely in src/api/auth.ts POST /api/auth/login handler — missing null check on password field."
 
 **Step 2 — Acceptance criteria specificity check**: For each bug, verify each acceptance criterion passes the "pipeline autonomy test" — could an AI session, without asking a human, determine whether this criterion is met? Flag criteria that are subjective ("works correctly"), lack measurable conditions ("performs better"), or don't specify the verification method.
 
@@ -188,72 +188,50 @@ Before generating `bug-fix-list.json`, perform a holistic scan across all collec
 - **Missing dependencies**: If fixing B-002 requires B-001 to be fixed first, flag the dependency
 - **Scope gaps**: If bugs describe symptoms but the underlying cause likely affects more areas, suggest additional bugs
 
-**Step 4 — Present review table**: Display the completeness assessment using this template:
-
-```
-┌─ Completeness Review ─────────────────────────────────────────────────
-│ Bug    │ Description │ Criteria   │ Reproducible │ Notes
-│ B-001  │ ✓ Clear     │ ✓ Specific │ ✓ Yes        │ —
-│ B-002  │ ⚠ Vague     │ ⚠ Subjective│ ✓ Yes       │ "encoding works" → needs specific test case
-│ B-003  │ ✓ Clear     │ ⚠ No metric│ ⚠ No steps  │ needs perf threshold + reproduction steps
-└────────────────────────────────────────────────────────────────────────
-```
+**Step 4 — Present review table**: Display the completeness assessment using the template in `${SKILL_DIR}/assets/bug-confirmation-template.md` (§Completeness Review Template).
 
-For any ⚠ items, ask targeted questions to fill gaps. Iterate until the user confirms all bugs are adequately described. Present bilingual prompt:
+For any items that need attention, ask targeted questions to fill gaps. Iterate until the user confirms all bugs are adequately described. Present bilingual prompt:
 
-> "以上是完整性审查结果。标记 ⚠ 的项目需要补充，是否逐一补充？还是先跳过，之后再完善？"
-> "Above is the completeness review. Items marked ⚠ need more detail. Address them now, or proceed and refine later?"
+> "以上是完整性审查结果。需要补充的项目是否逐一补充？还是先跳过，之后再完善？"
+> "Above is the completeness review. Items needing more detail — address them now, or proceed and refine later?"
 
 Only proceed to Phase 5 after user confirms.
 
+**Gate → CP-BP-4**: All bugs pass headless execution readiness check.
+
 ### Phase 5: Generate & Validate
 
-1. **Generate `bug-fix-list.json`**: Conform to `dev-pipeline/templates/bug-fix-list-schema.json`
-2. **Validate against schema**: Run the validation script:
-   ```bash
-   python3 ${SKILL_DIR}/scripts/validate-bug-list.py bug-fix-list.json --feature-list feature-list.json
-   ```
-   If the script is not available, perform the validation checks manually (see checklist below).
-3. **Write file** to project root (or user-specified path)
+1. **Generate `.prizmkit/plans/bug-fix-list.json`**: Conform to `dev-pipeline/templates/bug-fix-list-schema.json`
+2. **Validate against schema**: Run `python3 ${SKILL_DIR}/scripts/validate-bug-list.py .prizmkit/plans/bug-fix-list.json --feature-list .prizmkit/plans/feature-list.json`. If the script is unavailable, use the checklist in `${SKILL_DIR}/references/schema-validation.md`.
+3. **Write file** to `.prizmkit/plans/` (or user-specified path)
 4. **Output**: File path, summary, and next steps
 
-#### Schema Validation Checklist
-
-Before writing the file, verify all items pass:
-
-**Required fields:**
-- [ ] `$schema`: must be `"dev-pipeline-bug-fix-list-v1"`
-- [ ] `project_name`: non-empty string
-- [ ] `bugs`: non-empty array
-
-**Per-bug required fields:**
-- [ ] `id`: matches pattern `B-NNN` (e.g., `B-001`)
-- [ ] `title`: non-empty string
-- [ ] `description`: non-empty string
-- [ ] `severity`: one of `critical`, `high`, `medium`, `low`
-- [ ] `error_source.type`: one of `stack_trace`, `user_report`, `failed_test`, `log_pattern`, `monitoring_alert`
-- [ ] `verification_type`: one of `automated`, `manual`, `hybrid`
-- [ ] `acceptance_criteria`: non-empty array of strings
-- [ ] `status`: must be `pending` for new bugs
-
-**Consistency checks:**
-- [ ] No duplicate bug IDs
-- [ ] If `priority` is set, must be one of `high`, `medium`, `low`
-- [ ] If `affected_feature` is set, verify it exists in `feature-list.json` (if available)
-
-If any check fails, fix before writing the file.
+**Gate → CP-BP-5**: `bug-fix-list.json` passes validation script with zero errors.
 
 #### Success Output
 
 ```
-✅ bug-fix-list.json generated with 3 bugs (1 critical, 1 medium, 1 low)
+.prizmkit/plans/bug-fix-list.json generated with 3 bugs (1 critical, 1 medium, 1 low)
 
 Next steps:
-- Review: cat bug-fix-list.json
-- Start fixing: say "start fixing" or "start fixing bugs" to launch the bugfix pipeline
-- Or run directly: ./dev-pipeline/launch-bugfix-daemon.sh start bug-fix-list.json
+- Review: cat .prizmkit/plans/bug-fix-list.json
+- Start fixing: say "start fixing" to launch the bugfix pipeline via bugfix-pipeline-launcher
 ```
 
+### Checkpoints (Mandatory Gates)
+
+Checkpoints catch cascading errors early — skipping one means the next phase builds on unvalidated assumptions.
+
+| Checkpoint | Artifact/State | Criteria | Phase |
+|-----------|----------------|----------|-------|
+| **CP-BP-1** | Project Context | Tech stack and project info confirmed | 1 |
+| **CP-BP-2** | Bugs Collected | All bugs extracted and confirmed by user | 2 |
+| **CP-BP-3** | Priorities Set | Severity/priority assigned, duplicates resolved | 3 |
+| **CP-BP-4** | Completeness Passed | All bugs pass headless execution readiness check | 4 |
+| **CP-BP-5** | File Generated | `bug-fix-list.json` passes validation script | 5 |
+
+**Resume Detection**: If existing `.prizmkit/plans/bug-fix-list.json` or draft found, read `${SKILL_DIR}/references/error-recovery.md` §Resume Support for checkpoint-based resumption.
+
 ---
 
 ## Operation: From Log
@@ -265,11 +243,11 @@ Batch-parse error logs to generate bug entries without interactive prompts:
 3. Auto-generate bug entries with:
    - Title: first line of error message
    - Description: full error context
-   - Severity: use the **Severity Auto-Classification Rules** (see Phase 2)
+   - Severity: use `${SKILL_DIR}/references/severity-rules.md`
    - error_source: populated from log content
    - verification_type: default to `automated`
    - acceptance_criteria: auto-generate "Error no longer occurs in [scenario]"
-4. Output draft `bug-fix-list.json` for user review
+4. Output draft `.prizmkit/plans/bug-fix-list.json` for user review
 5. Ask: "Review and confirm? You can edit individual entries."
 
 ## Operation: From Tests
@@ -280,11 +258,11 @@ Batch-parse failed test output:
 2. Parse each failed test case as a separate bug entry
 3. Auto-populate `failed_test_path`, `error_message`
 4. Set verification_type to `automated` (test already exists)
-5. Output draft `bug-fix-list.json`
+5. Output draft `.prizmkit/plans/bug-fix-list.json`
 
 ## Operation: Validate
 
-Validate existing `bug-fix-list.json`:
+Validate existing `.prizmkit/plans/bug-fix-list.json`:
 
 1. Check JSON syntax
 2. Validate against `dev-pipeline/templates/bug-fix-list-schema.json`
@@ -293,7 +271,6 @@ Validate existing `bug-fix-list.json`:
    - Missing required fields
    - Invalid status values
    - Invalid priority values (must be 'high', 'medium', or 'low')
-   - Invalid `affected_feature` references (if feature-list.json exists)
 4. Output: validation result with specific errors/warnings
 
 ## Operation: Summary
@@ -302,7 +279,6 @@ Print human-readable summary:
 
 ```
 Bug Fix List Summary: my-web-app
-═══════════════════════════════
 
 Total: 3 bugs
 By Severity: critical=1, high=0, medium=1, low=1
@@ -312,69 +288,35 @@ Bug List (by priority):
   1. [B-001] Login null reference crash (CRITICAL) — automated
   2. [B-002] CSV export Chinese encoding (MEDIUM) — hybrid
   3. [B-003] Slow dashboard loading (LOW) — manual
-
-Affected Features: F-003 (1 bug), F-012 (1 bug), none (1 bug)
 ```
 
 ---
 
-## Adversarial Critic Review (Testing Defaults)
-
-All bug fixes support optional critic review for additional quality assurance. The critic mechanism is disabled by default but can be enabled per-bug based on severity and complexity.
+## Adversarial Critic & Browser Verification
 
-### Default Critic Behavior
+When configuring critic settings or browser verification for bugs, read `${SKILL_DIR}/references/critic-and-verification.md` for default behavior tables and verification type guidance.
 
-| Severity | `critic` | `critic_count` | Rationale |
-|----------|----------|----------------|-----------|
-| critical | `true` | `1` | Single critic review for critical bugs |
-| high | `true` | `1` | Single critic review for high-severity bugs |
-| medium | `false` | (omitted) | Skip critic for medium-severity bugs |
-| low | `false` | (omitted) | Skip critic for low-severity bugs |
-
-- `critic: true` — Enable adversarial review after fix implementation
-- `critic_count: 1` — Single critic agent reviews the fix
-- Critic verifies: fix addresses root cause, no regressions introduced, acceptance criteria met
-
-**User Override**: During Phase 2 or Phase 3, users can opt to enable/disable critic on a per-bug basis.
+Key points:
+- Critic is enabled by default for critical/high severity, disabled for medium/low
+- Users can override critic settings per-bug during Phase 2 or Phase 3
+- Browser verification is feature-pipeline only — bug fixes use `verification_type` field (automated/manual/hybrid)
 
 ---
 
-## Browser Verification
+## Next-Step Execution Policy
 
-**Browser verification is a feature-pipeline capability only.** Bug fixes use the `verification_type` field instead:
+Recommend invoking `bugfix-pipeline-launcher` to configure and launch the pipeline. Do NOT recommend running shell scripts directly — that is the launcher's responsibility.
 
-- `verification_type: automated` — Use unit/integration tests to verify the fix
-- `verification_type: manual` — Describe manual testing steps in acceptance criteria (including any browser verification steps)
-- `verification_type: hybrid` — Combine automated tests with manual browser verification steps
+After `.prizmkit/plans/bug-fix-list.json` is generated, present:
+1. Summary of generated bugs (count, severity breakdown)
+2. Recommend: "Say 'start fixing' to launch the bugfix pipeline via `bugfix-pipeline-launcher`"
+3. Alternative: fix a single bug interactively via `bug-fix-workflow`
 
-For UI-related bugs that require visual verification (e.g., "Button doesn't show error message"), describe the verification steps in your acceptance criteria:
-
-Example:
-```
-Bug Title: Login error message not displaying
-Verification Type: manual
-Acceptance Criteria:
-  1. Navigate to /login with invalid credentials
-  2. Verify error message "Invalid email or password" appears below the email field
-  3. Verify error message is red (#FF0000)
-  4. Verify form fields are still enabled and can be re-submitted
-```
-
-The bugfix pipeline AI will use these criteria during manual verification.
-
----
-
-## Integration with Bug Fix Pipeline
-
-After `bug-fix-list.json` is generated, the user can:
+## Error Handling
 
-1. **Say "start fixing" or "start fixing bugs"** — triggers `bugfix-pipeline-launcher` skill to auto-launch pipeline in background (recommended)
-2. **Background daemon**: `./dev-pipeline/launch-bugfix-daemon.sh start bug-fix-list.json`
-3. **Foreground run**: `./dev-pipeline/run-bugfix.sh run bug-fix-list.json`
-4. **Fix single bug interactively**: invoke `bug-fix-workflow` in current session
-5. **Retry a failed bug**: `./dev-pipeline/retry-bugfix.sh B-001`
+If validation fails or a session is interrupted, read `${SKILL_DIR}/references/error-recovery.md` for the full error type table, retry logic, and checkpoint-based resume support.
 
-## Error Handling
+Common errors handled inline:
 
 | Error | Action |
 |-------|--------|
@@ -387,6 +329,6 @@ After `bug-fix-list.json` is generated, the user can:
 
 ## Output
 
-- `bug-fix-list.json` conforming to `dev-pipeline/templates/bug-fix-list-schema.json`
+- `.prizmkit/plans/bug-fix-list.json` conforming to `dev-pipeline/templates/bug-fix-list-schema.json`
 - Validation report (if validation run)
 - Summary report (if summary run)