prizmkit 1.1.8 → 1.1.10

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

@@ -1,12 +1,43 @@
 ---
 name: "bug-planner"
-tier: companion
-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'. (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 `.prizmkit/plans/bug-fix-list.json` for the Bug Fix Pipeline. This is the bug-fix counterpart to `feature-planner` (which generates `.prizmkit/plans/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
 
@@ -33,6 +64,28 @@ This skill handles multiple operations. Determine the user's intent and execute
 | 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 `.prizmkit/plans/feature-list.json` or ask user
-2. **Identify tech stack**: Read from `.prizmkit/config.json` `tech_stack` (preferred), then `.prizmkit/plans/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 `.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 `.prizmkit/plans/bug-fix-list.json`, perform a holistic scan a
 - **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 `.prizmkit/plans/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 .prizmkit/plans/bug-fix-list.json --feature-list .prizmkit/plans/feature-list.json
-   ```
-   If the script is not available, perform the validation checks manually (see checklist below).
+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 `.prizmkit/plans/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
 
 ```
-✅ .prizmkit/plans/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 .prizmkit/plans/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 .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,7 +243,7 @@ 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]"
@@ -293,7 +271,6 @@ Validate existing `.prizmkit/plans/bug-fix-list.json`:
    - Missing required fields
    - Invalid status values
    - Invalid priority values (must be 'high', 'medium', or 'low')
-   - Invalid `affected_feature` references (if .prizmkit/plans/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 `.prizmkit/plans/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 .prizmkit/plans/bug-fix-list.json`
-3. **Foreground run**: `./dev-pipeline/run-bugfix.sh run .prizmkit/plans/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 |
 |-------|--------|

package/bundled/skills/bug-planner/assets/bug-confirmation-template.md

@@ -0,0 +1,43 @@
+# Bug Confirmation Templates
+
+## Per-Bug Confirmation Template
+
+Present this after extracting and clarifying each bug:
+
+```
+┌─ 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?"
+
+Only finalize the bug entry after user confirms all three points.
+
+## Completeness Review Template
+
+Display during Phase 4 pre-generation review:
+
+```
+┌─ 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
+└────────────────────────────────────────────────────────────────────────
+```

package/bundled/skills/bug-planner/references/critic-and-verification.md

@@ -0,0 +1,44 @@
+# Adversarial Critic Review & Browser Verification
+
+## 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.
+
+### Default Critic Behavior
+
+| 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.
+
+## Browser Verification
+
+**Browser verification is a feature-pipeline capability only.** Bug fixes use the `verification_type` field instead:
+
+- `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
+
+For UI-related bugs that require visual verification (e.g., "Button doesn't show error message"), describe the verification steps in 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.

package/bundled/skills/bug-planner/references/error-recovery.md

@@ -0,0 +1,73 @@
+# Error Recovery & Resume Support
+
+Reference document for bug-planner error handling and session recovery. Load this when validation fails, a session is interrupted, or existing artifacts are detected.
+
+## Validation Failure Handling
+
+### Warnings Only
+
+If `validate-bug-list.py` returns warnings but no errors:
+1. Present warnings to user
+2. Ask: "Proceed with these warnings, or fix them first?"
+3. If user approves → write file and continue
+4. If user wants fixes → address each warning, re-validate
+
+### Errors Found
+
+If validation returns errors:
+1. Group errors by type (missing fields, invalid values, duplicate IDs, broken references)
+2. Auto-fix where possible:
+   - Missing `status` → set to `pending`
+   - Duplicate IDs → re-number with next sequential B-NNN
+   - Invalid `priority` → re-derive from severity using the mapping table
+3. Present fixes to user for confirmation
+4. Re-validate after fixes
+5. Maximum 3 total validation attempts — if still failing after 3 rounds, present the raw errors and ask user for guidance
+
+### JSON Parse Failure
+
+If the generated JSON is malformed:
+1. Do not write the file
+2. Regenerate from the collected bug data (Phase 2-3 state)
+3. Re-validate before writing
+
+## Resume Support
+
+### Checkpoint-Based Resumption
+
+When bug-planner detects existing artifacts, determine the last completed checkpoint and offer to resume:
+
+| Existing Artifact | Last Checkpoint | Resume From |
+|---|---|---|
+| `.prizmkit/plans/bug-fix-list.json` (valid) | CP-BP-5 | Offer: "Valid bug list exists. Append new bugs (Route B) or regenerate?" |
+| `.prizmkit/plans/bug-fix-list.json` (invalid) | CP-BP-4 | Re-run Phase 5 validation and fix |
+| `.prizmkit/plans/bug-fix-list.draft.json` | CP-BP-2 or CP-BP-3 | Load draft, determine phase from content completeness, resume |
+| `.prizmkit/config.json` with tech_stack | CP-BP-1 (partial) | Skip project context questions, start at Phase 2 |
+| No artifacts | — | Start from Phase 1 |
+
+### Resume Detection Flow
+
+1. Check for `.prizmkit/plans/bug-fix-list.json`
+   - If exists and valid → offer Route B (append) or full regeneration
+   - If exists but invalid → offer to fix and re-validate (resume from CP-BP-4)
+2. Check for `.prizmkit/plans/bug-fix-list.draft.json`
+   - If exists → load draft, count bugs with/without confirmation, resume from appropriate phase
+3. Check for `.prizmkit/config.json`
+   - If exists with tech_stack → skip Phase 1 context gathering
+4. If no artifacts → start fresh (Route A)
+
+### Session Interruption Recovery
+
+If a bug-planner session is interrupted mid-planning:
+
+1. On next invocation, run the Resume Detection Flow above
+2. If a draft exists, present: "Found a draft with N bugs from a previous session. Resume from where you left off, or start fresh?"
+3. If user resumes → load draft state, skip completed phases
+4. If user starts fresh → archive draft as `bug-fix-list.draft.TIMESTAMP.json`, begin Phase 1
+
+## Draft Management
+
+- Save drafts to `.prizmkit/plans/bug-fix-list.draft.json` after each completed phase (CP-BP-1 through CP-BP-4)
+- Drafts use the same schema as the final file but may have incomplete fields
+- Delete draft after successful generation of the final `bug-fix-list.json`
+- Keep at most 1 draft — overwrite on each phase completion