prizmkit 1.1.190 → 1.1.192

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (189) hide show
  1. package/bin/create-prizmkit.js +4 -4
  2. package/bundled/VERSION.json +3 -3
  3. package/bundled/adapters/antigravity/assets/prizmkit-hook.cjs +150 -0
  4. package/bundled/adapters/antigravity/hooks-adapter.js +195 -0
  5. package/bundled/adapters/antigravity/paths.js +14 -0
  6. package/bundled/adapters/antigravity/rules-adapter.js +54 -0
  7. package/bundled/adapters/antigravity/skill-adapter.js +38 -0
  8. package/bundled/adapters/codex/skill-adapter.js +28 -8
  9. package/bundled/adapters/cursor/skill-adapter.js +13 -4
  10. package/bundled/adapters/pi/skill-adapter.js +28 -7
  11. package/bundled/dev-pipeline/.env.example +4 -12
  12. package/bundled/dev-pipeline/README.md +21 -15
  13. package/bundled/dev-pipeline/assets/skill-subagent-integration.md +3 -6
  14. package/bundled/dev-pipeline/prizmkit_runtime/atomic_io.py +48 -0
  15. package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py +66 -23
  16. package/bundled/dev-pipeline/prizmkit_runtime/cli.py +10 -7
  17. package/bundled/dev-pipeline/prizmkit_runtime/commands.py +2 -21
  18. package/bundled/dev-pipeline/prizmkit_runtime/config.py +29 -70
  19. package/bundled/dev-pipeline/prizmkit_runtime/daemon.py +125 -67
  20. package/bundled/dev-pipeline/prizmkit_runtime/gitops.py +89 -442
  21. package/bundled/dev-pipeline/prizmkit_runtime/heartbeat.py +93 -49
  22. package/bundled/dev-pipeline/prizmkit_runtime/interoperability.py +1 -3
  23. package/bundled/dev-pipeline/prizmkit_runtime/paths.py +0 -6
  24. package/bundled/dev-pipeline/prizmkit_runtime/platform_detection.py +49 -18
  25. package/bundled/dev-pipeline/prizmkit_runtime/processes.py +206 -151
  26. package/bundled/dev-pipeline/prizmkit_runtime/reset.py +2 -23
  27. package/bundled/dev-pipeline/prizmkit_runtime/reset_preserve.py +15 -134
  28. package/bundled/dev-pipeline/prizmkit_runtime/results.py +25 -0
  29. package/bundled/dev-pipeline/prizmkit_runtime/runner_bookkeeping.py +68 -83
  30. package/bundled/dev-pipeline/prizmkit_runtime/runner_classification.py +15 -5
  31. package/bundled/dev-pipeline/prizmkit_runtime/runner_models.py +1 -29
  32. package/bundled/dev-pipeline/prizmkit_runtime/runner_prompts.py +0 -2
  33. package/bundled/dev-pipeline/prizmkit_runtime/runner_status.py +7 -2
  34. package/bundled/dev-pipeline/prizmkit_runtime/runners.py +282 -217
  35. package/bundled/dev-pipeline/prizmkit_runtime/runtime_commit.py +124 -122
  36. package/bundled/dev-pipeline/prizmkit_runtime/runtime_helper.py +90 -9
  37. package/bundled/dev-pipeline/prizmkit_runtime/sessions.py +369 -154
  38. package/bundled/dev-pipeline/prizmkit_runtime/status.py +3 -3
  39. package/bundled/dev-pipeline/prizmkit_runtime/stream_progress.py +2780 -0
  40. package/bundled/dev-pipeline/prizmkit_runtime/task_checkout.py +27 -101
  41. package/bundled/dev-pipeline/prizmkit_runtime/test_result.py +58 -4
  42. package/bundled/dev-pipeline/scripts/check-session-status.py +43 -19
  43. package/bundled/dev-pipeline/scripts/continuation.py +6 -4
  44. package/bundled/dev-pipeline/scripts/detect-stuck.py +28 -28
  45. package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py +7 -2
  46. package/bundled/dev-pipeline/scripts/generate-bugfix-prompt.py +7 -2
  47. package/bundled/dev-pipeline/scripts/init-bugfix-pipeline.py +10 -7
  48. package/bundled/dev-pipeline/scripts/init-change-artifact.py +8 -2
  49. package/bundled/dev-pipeline/scripts/init-pipeline.py +14 -69
  50. package/bundled/dev-pipeline/scripts/parse-stream-progress.py +31 -2328
  51. package/bundled/dev-pipeline/scripts/patch-completion-notes.py +4 -24
  52. package/bundled/dev-pipeline/scripts/prompt_framework.py +56 -9
  53. package/bundled/dev-pipeline/scripts/status_common.py +591 -0
  54. package/bundled/dev-pipeline/scripts/update-bug-status.py +85 -463
  55. package/bundled/dev-pipeline/scripts/update-checkpoint.py +227 -65
  56. package/bundled/dev-pipeline/scripts/update-feature-status.py +76 -509
  57. package/bundled/dev-pipeline/scripts/utils.py +10 -15
  58. package/bundled/dev-pipeline/templates/bootstrap-tier3.md +4 -4
  59. package/bundled/dev-pipeline/templates/bug-fix-list-schema.json +7 -0
  60. package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md +1 -1
  61. package/bundled/dev-pipeline/templates/sections/artifact-manifest.md +1 -1
  62. package/bundled/dev-pipeline/templates/sections/bugfix-phase-manual-verification.md +1 -1
  63. package/bundled/dev-pipeline/templates/sections/bugfix-phase-review.md +1 -1
  64. package/bundled/dev-pipeline/templates/sections/bugfix-phase-test.md +2 -1
  65. package/bundled/dev-pipeline/templates/sections/checkpoint-system.md +1 -1
  66. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-auto.md +1 -1
  67. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-opencli.md +2 -2
  68. package/bundled/dev-pipeline/templates/sections/phase-browser-verification.md +2 -2
  69. package/bundled/dev-pipeline/templates/sections/phase-prizmkit-test.md +2 -1
  70. package/bundled/dev-pipeline/templates/sections/phase-review-full.md +1 -1
  71. package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md +3 -6
  72. package/bundled/dev-pipeline/templates/session-status-schema.json +2 -5
  73. package/bundled/dev-pipeline/tests/_helpers.py +418 -0
  74. package/bundled/dev-pipeline/tests/conftest.py +45 -1
  75. package/bundled/dev-pipeline/tests/live_ai_cli_log_smoke.py +1 -0
  76. package/bundled/dev-pipeline/tests/test_auto_skip.py +4 -69
  77. package/bundled/dev-pipeline/tests/test_checkpoint_state.py +126 -1
  78. package/bundled/dev-pipeline/tests/test_daemon_and_scripts.py +257 -0
  79. package/bundled/dev-pipeline/tests/test_e2e_pipeline_run.py +500 -0
  80. package/bundled/dev-pipeline/tests/test_generate_bootstrap_prompt.py +59 -117
  81. package/bundled/dev-pipeline/tests/test_generate_bugfix_prompt.py +12 -10
  82. package/bundled/dev-pipeline/tests/test_python_runner_parity.py +561 -3094
  83. package/bundled/dev-pipeline/tests/test_recovery_workflow.py +7 -8
  84. package/bundled/dev-pipeline/tests/test_repository_bootstrap.py +0 -1
  85. package/bundled/dev-pipeline/tests/test_reset_modes.py +15 -27
  86. package/bundled/dev-pipeline/tests/test_reset_preserve.py +54 -139
  87. package/bundled/dev-pipeline/tests/test_runner_bookkeeping.py +766 -0
  88. package/bundled/dev-pipeline/tests/test_runner_lifecycle.py +1257 -0
  89. package/bundled/dev-pipeline/tests/test_runtime_helper.py +97 -20
  90. package/bundled/dev-pipeline/tests/test_session_launch.py +1101 -0
  91. package/bundled/dev-pipeline/tests/test_stream_progress.py +585 -0
  92. package/bundled/dev-pipeline/tests/test_unified_cli.py +490 -2006
  93. package/bundled/dev-pipeline/tests/test_utils.py +3 -3
  94. package/bundled/rules/USAGE.md +1 -0
  95. package/bundled/skills/_metadata.json +9 -63
  96. package/bundled/skills/app-planner/SKILL.md +32 -303
  97. package/bundled/skills/app-planner/references/app-design-guide.md +0 -4
  98. package/bundled/skills/app-planner/references/generated-plan-review.md +2 -1
  99. package/bundled/skills/app-planner/references/project-brief-guide.md +14 -0
  100. package/bundled/skills/app-planner/references/project-conventions-discovery.md +4 -6
  101. package/bundled/skills/app-planner/references/project-state-detection.md +2 -3
  102. package/bundled/skills/bug-fix-workflow/SKILL.md +1 -2
  103. package/bundled/skills/bug-fix-workflow/references/bug-diagnosis.md +4 -7
  104. package/bundled/skills/bug-planner/SKILL.md +54 -435
  105. package/bundled/skills/bug-planner/references/generated-plan-review.md +3 -2
  106. package/bundled/skills/bug-planner/references/input-formats.md +32 -0
  107. package/bundled/skills/bugfix-pipeline-launcher/SKILL.md +4 -6
  108. package/bundled/skills/bugfix-pipeline-launcher/references/configuration.md +4 -28
  109. package/bundled/skills/feature-pipeline-launcher/SKILL.md +4 -6
  110. package/bundled/skills/feature-pipeline-launcher/references/configuration.md +4 -28
  111. package/bundled/skills/feature-planner/SKILL.md +60 -439
  112. package/bundled/skills/feature-planner/assets/planning-guide.md +1 -1
  113. package/bundled/skills/feature-planner/references/completeness-review.md +34 -0
  114. package/bundled/skills/feature-planner/references/decomposition-patterns.md +2 -2
  115. package/bundled/skills/feature-planner/references/error-recovery.md +1 -1
  116. package/bundled/skills/feature-planner/references/generated-plan-review.md +3 -2
  117. package/bundled/skills/feature-planner/references/incremental-feature-planning.md +3 -1
  118. package/bundled/skills/feature-workflow/SKILL.md +1 -2
  119. package/bundled/skills/prizmkit/SKILL.md +7 -1
  120. package/bundled/skills/prizmkit-code-review/SKILL.md +14 -6
  121. package/bundled/skills/prizmkit-code-review/references/independent-code-review.md +7 -4
  122. package/bundled/skills/prizmkit-code-review/references/review-report-template.md +16 -0
  123. package/bundled/skills/prizmkit-code-review/scripts/render_review_report.py +58 -20
  124. package/bundled/skills/prizmkit-implement/SKILL.md +1 -1
  125. package/bundled/skills/prizmkit-init/SKILL.md +25 -128
  126. package/bundled/skills/prizmkit-init/assets/project-brief-template.md +3 -3
  127. package/bundled/skills/prizmkit-init/references/config-schema.md +2 -2
  128. package/bundled/skills/prizmkit-plan/SKILL.md +6 -8
  129. package/bundled/skills/prizmkit-plan/references/clarify-guide.md +1 -1
  130. package/bundled/skills/prizmkit-plan/references/independent-plan-review.md +5 -2
  131. package/bundled/skills/prizmkit-plan/references/review-plan-spec-loop.md +6 -5
  132. package/bundled/skills/prizmkit-prizm-docs/SKILL.md +1 -13
  133. package/bundled/skills/prizmkit-prizm-docs/assets/prizm-docs-format.md +1 -1
  134. package/bundled/skills/prizmkit-prizm-docs/references/op-init.md +1 -1
  135. package/bundled/skills/prizmkit-prizm-docs/references/op-update.md +1 -1
  136. package/bundled/skills/prizmkit-retrospective/SKILL.md +6 -4
  137. package/bundled/skills/prizmkit-test/SKILL.md +25 -133
  138. package/bundled/skills/prizmkit-test/references/independent-test-review.md +5 -2
  139. package/bundled/skills/prizmkit-test/references/test-coverage-model.md +6 -0
  140. package/bundled/skills/prizmkit-workflow/SKILL.md +2 -3
  141. package/bundled/skills/prizmkit-workflow/references/workflow-state-protocol.md +4 -3
  142. package/bundled/skills/recovery-workflow/SKILL.md +7 -7
  143. package/bundled/skills/recovery-workflow/evals/evals.json +1 -1
  144. package/bundled/skills/recovery-workflow/references/detection.md +1 -3
  145. package/bundled/skills/recovery-workflow/scripts/detect-recovery-state.py +0 -6
  146. package/bundled/templates/project-memory-template.md +1 -2
  147. package/package.json +1 -1
  148. package/src/ai-cli-launch.js +1 -1
  149. package/src/clean.js +40 -4
  150. package/src/config.js +64 -4
  151. package/src/detect-platform.js +10 -6
  152. package/src/external-skills.js +2 -2
  153. package/src/index.js +1 -0
  154. package/src/manifest.js +1 -1
  155. package/src/platforms.js +6 -2
  156. package/src/prompts.js +11 -3
  157. package/src/scaffold.js +87 -11
  158. package/src/upgrade.js +9 -3
  159. package/bundled/dev-pipeline/SCHEMA_ANALYSIS.md +0 -53
  160. package/bundled/dev-pipeline/scripts/generate-refactor-prompt.py +0 -649
  161. package/bundled/dev-pipeline/scripts/init-refactor-pipeline.py +0 -463
  162. package/bundled/dev-pipeline/scripts/update-refactor-status.py +0 -1512
  163. package/bundled/dev-pipeline/templates/refactor-bootstrap-prompt.md +0 -240
  164. package/bundled/dev-pipeline/templates/refactor-list-schema.json +0 -266
  165. package/bundled/dev-pipeline/templates/sections/refactor-critical-paths.md +0 -15
  166. package/bundled/dev-pipeline/templates/sections/refactor-mission.md +0 -9
  167. package/bundled/dev-pipeline/templates/sections/refactor-phase-commit-report.md +0 -24
  168. package/bundled/dev-pipeline/templates/sections/refactor-phase-implement.md +0 -16
  169. package/bundled/dev-pipeline/templates/sections/refactor-phase-init.md +0 -9
  170. package/bundled/dev-pipeline/templates/sections/refactor-phase-plan.md +0 -22
  171. package/bundled/dev-pipeline/templates/sections/refactor-phase-review.md +0 -19
  172. package/bundled/dev-pipeline/templates/sections/refactor-phase-test.md +0 -24
  173. package/bundled/dev-pipeline/templates/sections/refactor-reminders.md +0 -12
  174. package/bundled/dev-pipeline/templates/sections/refactor-session-context.md +0 -6
  175. package/bundled/dev-pipeline/templates/sections/refactor-task-contract.md +0 -52
  176. package/bundled/dev-pipeline/tests/test_generate_refactor_prompt.py +0 -478
  177. package/bundled/skills/feature-planner/assets/evaluation-guide.md +0 -44
  178. package/bundled/skills/refactor-pipeline-launcher/SKILL.md +0 -219
  179. package/bundled/skills/refactor-pipeline-launcher/references/configuration.md +0 -78
  180. package/bundled/skills/refactor-planner/SKILL.md +0 -467
  181. package/bundled/skills/refactor-planner/assets/planning-guide.md +0 -291
  182. package/bundled/skills/refactor-planner/references/behavior-preservation.md +0 -187
  183. package/bundled/skills/refactor-planner/references/error-recovery.md +0 -45
  184. package/bundled/skills/refactor-planner/references/fast-path.md +0 -59
  185. package/bundled/skills/refactor-planner/references/generated-plan-review.md +0 -107
  186. package/bundled/skills/refactor-planner/references/planning-phases.md +0 -172
  187. package/bundled/skills/refactor-planner/references/refactor-scoping-guide.md +0 -230
  188. package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py +0 -1120
  189. package/bundled/skills/refactor-workflow/SKILL.md +0 -205
@@ -5,7 +5,7 @@ description: "Interactive bug planning that produces, validates, appends, and su
5
5
 
6
6
  # Bug Planner
7
7
 
8
- Interactive planning skill that creates, updates, validates, and summarizes the standardized `.prizmkit/plans/bug-fix-list.json` for later autonomous bug-fix execution. It never fixes source code.
8
+ Interactive planning skill that creates, updates, validates, and summarizes `.prizmkit/plans/bug-fix-list.json` for autonomous bug-fix execution. It never fixes source code.
9
9
 
10
10
  ## Intent-Aligned Planning Policy
11
11
 
@@ -16,284 +16,47 @@ Before proposing or finalizing bug contracts:
16
16
  4. Explore alternatives only when **materially different viable paths** affect the behavioral contract. Compare meaningful trade-offs without manufacturing an option count or prescribing an unverified fix.
17
17
  5. Produce a **minimum-sufficient** bug contract: every requirement maps to confirmed behavior, a constraint, existing contract, or evidenced risk, and every expected outcome maps to observable completion evidence. Defer speculative cleanup and unsupported future work.
18
18
 
19
- ## Invocation Commitment (Hard Rule)
19
+ ## Invocation & Scope Boundary (Hard Rules)
20
20
 
21
- When the user invokes `/bug-planner`, you MUST execute the bug-planner workflow. You must NEVER:
22
- - Decide on the user's behalf that the task "doesn't need bug-planner"
23
- - Skip bug-planner to jump directly to implementation or any other skill
24
- - Bypass the interactive phases because you judge the task to be "simple"
25
-
26
- If you believe the task is better suited for a different workflow, you MUST:
27
- 1. Explain why you think a different path is more appropriate
28
- 2. Ask the user explicitly whether they want to switch or continue with bug-planner
29
- 3. Only switch if the user confirms
30
-
31
- The user chose this skill intentionally. Respect that choice.
32
-
33
- ## Scope Boundary (Hard Rule)
34
-
35
- This skill is PLANNING ONLY. It may create, append, validate, and review bug planning artifacts, but it must never implement a fix or start execution. You must NEVER:
36
- - Create, modify, or delete source code files (*.js, *.ts, *.py, *.go, *.html, *.css, etc.)
37
- - Run build/install/test commands
38
- - Execute any bug fix action
39
- - Execute any implementation action beyond writing `.prizmkit/plans/bug-fix-list.json`
40
-
41
- Your ONLY writable outputs are:
42
- 1. `.prizmkit/plans/bug-fix-list.json`
43
- 2. Planner-owned draft state in `.prizmkit/plans/` (e.g., `bug-fix-list.draft.json`) while it is required for deterministic writing, review repair, or explicit recovery
44
-
45
- After planning is complete, you MUST:
46
- 1. Present the summary and recommended next step (invoking `bugfix-pipeline-launcher`)
47
- 2. Ask the user explicitly whether they want to proceed to execution
48
- 3. If the user wants to adjust → continue refining the bug list
49
- 4. NEVER auto-execute the pipeline, launcher, composite workflow, or any fix step
50
- 5. Return the validated bug list to the caller; only `bugfix-pipeline-launcher` prepares the runtime command
21
+ - **When invoked via `/bug-planner`, execute this workflow.** Do not skip phases or jump directly to implementation. If another workflow (`bugfix-pipeline-launcher`, `bug-fix-workflow`, `feature-planner`) fits better, explain why and switch only if the user explicitly confirms.
22
+ - **This skill is PLANNING ONLY.** Never create/modify/delete source files, run build/install/test commands, or execute any bug fix. **Writable outputs only:** `.prizmkit/plans/bug-fix-list.json` and transient draft state `.prizmkit/plans/bug-fix-list.draft.json`.
23
+ - **After planning:** present summary, recommend `bugfix-pipeline-launcher`, and ask before proceeding; if user adjusts, refine the list. **NEVER auto-execute** pipelines/launchers/fixes; only `bugfix-pipeline-launcher` prepares runtime commands.
51
24
 
52
25
  ## Draft Lifecycle (Hard Rule)
53
26
 
54
- In an ordinary successful flow, `.prizmkit/plans/bug-fix-list.draft.json` is a private reasoning workspace: never presented as a deliverable, never given its own approval round, never retained after the batch lands. Build the batch there, validate it there, and run the entire Local Generated-Plan Review against it; the final list is written exactly once, after that review returns `PASS`, by a single `append` (existing list) or `generate` (new list). Then delete the draft immediately and report `Draft cleanup: removed`. A batch lost before it lands is regenerated from the confirmed decisions rather than recovered. Conditions that must keep a draft — explicit draft-save, interruption, a writer-rejected insert, cleanup failure — are defined in `${SKILL_DIR}/references/error-recovery.md`, and any retained path is named in the terminal report. For later adjustments, recreate only the minimum source draft from confirmed in-memory entries or exact-ID `show`; modifying entries this session did not create is the one case that still uses `append --replace-tail` for the exact current suffix.
55
-
56
- ## Fresh-Session Task Contract (Hard Rule)
57
-
58
- Every new or changed bug is an executable contract for a fresh AI session that has never seen the planning conversation. Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Use the existing fields correctly:
59
-
60
- 1. **Self-contained contract**: The bug's `description` and `acceptance_criteria`, read together, MUST define the objective, current state and actual behavior, desired state and expected behavior, selected scope and decisions, severity rationale, constraints, non-goals, relevant integrations, edge cases, reproduction conditions, verification decisions, and completion evidence. Because no separate rationale field is added, include the durable severity rationale in `description`. AI rewrite is allowed; dropping a confirmed item is not. There is no word-count upper limit and no acceptance-criteria count upper limit.
61
- 2. **Supplementary evidence only**: `user_context` is supplementary evidence only. Logs, stack traces, screenshots, and source excerpts may support diagnosis, but they MUST NOT expand, replace, or contradict the contract. If `user_context` were removed, a fresh bug-fix session must still know what fails, where and when it fails, what correct behavior means, which scope was selected, and how to verify the fix.
62
- 3. **Severity and verification are durable decisions**: Write the complete severity rationale, selected scope, environment, reproduction path, verification type, and verification decisions by meaning. Never store only an option label or conversational answer.
63
- 4. **Clarify by impact, do not guess**: Expected behavior, selected behavioral scope, material applicability, and relative references require clarification when multiple meanings would materially change the contract. Root cause, code location, and fix approach may remain explicitly labeled as evidence-backed hypotheses or unknowns when the confirmed behavior and bounded investigation path are sufficient for execution.
64
- 5. **Bug isolation**: Keep one bug per task unless bugs share the same root cause or the same failing contract and the user confirms a merge. Do not domain-merge unrelated bugs merely because they sit in the same module. Each bug contract and its supplementary evidence contain only material relevant to that bug. Repeat shared environment or constraints only when explicitly global.
65
-
66
- ### Artifact-Wide AI Readability
67
-
68
- - Every generated natural-language value must be a standalone domain statement. This applies to all AI-visible fields and sections, including `project_description`, `global_context`, titles, descriptions, acceptance criteria, severity/priority rationale, `error_source`, affected-module and environment text, `user_context`, verification goals, comments, appendices, and parentheticals.
69
- - Machine metadata such as schema markers, stable IDs, statuses, enums, and timestamps is exempt. Natural-language metadata is not exempt.
70
- - Never emit dialogue-role or chronology labels such as `user said`, `user answered`, `original request`, `this round`, `previous discussion`, `as discussed earlier`, `用户本轮回答`, or `如前面讨论`. Never emit planning question IDs, answer tokens, planning-option recommendation markers, checkpoint provenance, or raw internal answer-map entries as domain content.
71
- - `user_context` and `error_source` may hold independently intelligible evidence, not transcript fragments. Rewrite every confirmed turn into direct actual/expected behavior, scope, rationale, reproduction, or verification evidence before generation.
72
-
73
- ### Conversational Context Normalization
74
-
75
- - Never persist standalone option labels such as `A`, `B`, `C`, `方案A`, or `方案B` as execution context.
76
- - Expand a selected option into complete meaning and preserve substantive user rationale and constraints in durable prose at matching detail.
77
- - Do not emit transcript annotations such as `(original response: "...")` in final bug artifacts. Bare option labels and relative shorthand are not independently intelligible and materially useful exact wording.
78
- - Resolve `上面`, `这个`, `按推荐走`, `同前`, `继续这样`, `用刚才的方案`, `same as above`, or `go with your recommendation` only when there is one provable antecedent. Otherwise ask the user for clarification; never guess.
79
- - Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization. Apply the concrete accepted recommendations, then omit the raw approval; never repeat it once per accepted recommendation.
80
- - Do not present rejected root-cause or fix alternatives as active instructions; preserve one only when it defines a necessary non-goal. Retain exact user wording only when it is independently intelligible and materially useful.
81
-
82
- ### Reference Material Handling
83
-
84
- - Every retained stable code, configuration, machine-consumed interface, or URL reference must be purpose-tagged: state why it is relevant and what the execution AI should inspect. This applies to paths and URLs in structured evidence and `user_context`.
85
- - Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`, uploaded-report paths, screenshot paths, or ad-hoc log paths in durable bug contracts. Instead, copy or normalize the task-relevant content and exact evidence excerpt into `description` and `acceptance_criteria`; the bug must not depend on that source file still existing.
86
- - Good: `src/auth/validation.ts — inspect empty-password handling`; Bad: `logs/api-500.log — inspect the failure`. For a transient log, inline the relevant request, exception, and correlation evidence without retaining the path.
87
- - For large materials, preserve purpose and only task-relevant exact excerpts, and move confirmed expected behavior, selected scope, severity rationale, and verification decisions into `description` and `acceptance_criteria`. Retain a location only when it is a stable execution-time source of truth.
88
- - Embed complete large materials only when the execution session cannot access the source and all content is genuinely required.
89
-
90
- ### Good and Bad Normalization Examples
27
+ In an ordinary successful flow, `.prizmkit/plans/bug-fix-list.draft.json` is a private reasoning workspace: never presented as a deliverable, never given its own approval round, never retained after the batch lands. Build, validate, and run Local Generated-Plan Review against it; the final list is written exactly once, after that review returns `PASS`, by one `append` (existing list) or `generate` (new list). Then delete the draft immediately and report `Draft cleanup: removed`. Conditions that must keep a draft (`explicit save`, `interruption`, `writer rejection`, `cleanup failure`) are in `${SKILL_DIR}/references/error-recovery.md` (name any retained path). For later adjustments, recreate only the minimum source draft from confirmed in-memory entries or exact-ID `show`; modifying pre-existing entries uses `append --replace-tail`.
91
28
 
92
- - Bad: `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation` stored as selected fix scope.
93
- - Bad: `Selected decision: reject empty passwords with HTTP 400 (original response: "方案B")`; the annotation still requires an unseen option list.
94
- - Good: `Selected decision: reject empty passwords in request validation with HTTP 400 and do not enter credential verification`.
95
- - Good: `Selected decision: reproduce against the API integration test and retain UI verification as a regression check`.
96
- - Bad: storing or repeating `全部按照推荐` / `所有问题都按你的推荐处理` as a bug constraint; it is conversational authorization.
97
- - Bad: attaching a complete production log or retaining its local path while saying only `fix this`. Good: inline the relevant exception excerpt, actual/expected behavior, scope, and verification; retain a monitoring URL only when it is a stable execution-time source of truth.
29
+ ## Fresh-Session Task Contract (Hard Rule) & Bounded Existing-List Context (Hard Rule)
98
30
 
99
- **Multi-bug isolation example:**
100
- - User request includes: `Bug A: login crashes when password is empty`, `Bug B: CSV export loses Chinese characters`, and `Shared: production uses Node 20`.
101
- - The login bug contract fully defines its expected/actual behavior and includes only matching evidence plus the shared Node 20 environment; it MUST NOT include the CSV report.
102
- - The CSV bug contract fully defines encoding expectations and includes only matching evidence plus the shared Node 20 environment; it MUST NOT include the login report.
103
-
104
- ## When to Use
105
-
106
- The `description` frontmatter declares the trigger phrases for this skill. Beyond those:
107
-
108
- **Do NOT use when:**
109
- - User wants to start fixing bugs now → use `bugfix-pipeline-launcher`
110
- - User wants to fix a single bug interactively → use `bug-fix-workflow`
111
- - User wants to plan features → use `feature-planner`
112
-
113
- ## Priority and Severity Calibration (Mandatory)
114
-
115
- Bug planning must preserve the severity-to-priority mapping, but severity must be justified from concrete bug impact rather than from user frustration or the fact that something needs fixing.
116
-
117
- ### Severity → Priority Mapping (Preserved)
118
-
119
- - `critical` severity → `high` priority (treated with highest urgency)
120
- - `high` severity → `high` priority
121
- - `medium` severity → `medium` priority
122
- - `low` severity → `low` priority
123
-
124
- ### High Classification Guardrails
125
-
126
- Do not classify a user report as `high` severity or `high` priority unless the bug independently shows at least one high-impact indicator:
127
- - core feature outage or the user cannot complete a primary workflow
128
- - data loss, data corruption, or data integrity risk
129
- - security, privacy, authentication, or authorization failure
130
- - timeout, crash, unrecoverable error, or production 500 affecting a meaningful path
131
- - no reasonable workaround for affected users
132
-
133
- Do not assign every generated bug `Priority: high` and `Complexity: high` unless every bug independently satisfies the high/critical severity criteria and the rationale names the matching indicator. For bugs, `Complexity` is represented by the `Severity` classification in the planning summary. "The user cares about this", "this needs fixing", or "the bug is in framework code" is not enough.
134
-
135
- ### Required Planning Review Summary
136
-
137
- Before writing `.prizmkit/plans/bug-fix-list.json`, display severity and priority rationales for every bug:
138
-
139
- ```
140
- ID | Title | Severity | Severity Rationale | Priority | Priority Rationale
141
- B-001 | Login returns 500 | high | Core auth fails; no workaround | high | High severity maps to high priority
142
- B-002 | CSV export mojibake | medium | Incorrect output; workaround exists | medium | Medium severity maps to medium priority
143
- B-003 | Warning text typo | low | Cosmetic copy issue only | low | Low severity maps to low priority
31
+ For append flows on `.prizmkit/plans/bug-fix-list.json`, NEVER read the complete existing list or NEVER perform default full-history keyword search:
32
+ ```bash
33
+ python3 ${SKILL_DIR}/scripts/validate-bug-list.py context --input .prizmkit/plans/bug-fix-list.json
144
34
  ```
35
+ Consume only root metadata (`project_description`, `global_context`), `task_count`, `next_id`, and the five most recently appended `{id, description}` pairs (fetch explicit IDs/validation targets via `show --id B-NNN`). Write additions-only `{ "bugs": [...] }` to `.prizmkit/plans/bug-fix-list.draft.json` (do not ask for separate user approval merely to promote it; after `PASS`, insert once and present the final written result). Full fresh-session contract, normalization examples, and cross-bug checks live in `${SKILL_DIR}/references/input-formats.md`:
36
+ - `description` + `acceptance_criteria` must be self-contained (`user_context` is supplementary evidence only; removing it leaves a complete contract); label unconfirmed root cause, code location, or fix direction as evidence-backed hypotheses or unknowns (`do not force certainty or invent a fix`). Keep one bug per task (merge only on shared root cause + confirmation).
145
37
 
146
- Medium and low bug assignments are expected for partial failures, workaround cases, cosmetic issues, and non-critical edge cases.
147
-
148
- ---
149
-
150
- ## Intent Routing
151
-
152
- This skill handles multiple operations. Determine the user's intent and dispatch to the matching operation section below — each operation's authoritative trigger phrases live in its own **Operation:** section.
153
-
154
- | User Intent | Operation Section |
155
- |---|---|
156
- | Plan bugs interactively | **Operation: Interactive Planning** |
157
- | Parse error logs into bugs | **Operation: From Log** |
158
- | Parse test failures into bugs | **Operation: From Tests** |
159
- | Validate existing bug list | **Operation: Validate** |
160
- | Summarize bug list | **Operation: Summary** |
161
-
162
- ## Bounded Existing-List Context (Hard Rule)
163
- For any content-generating flow that appends to an existing `.prizmkit/plans/bug-fix-list.json`, NEVER read the complete historical list into AI context and NEVER perform default full-history keyword search.
164
- 1. Run `python3 ${SKILL_DIR}/scripts/validate-bug-list.py context --input .prizmkit/plans/bug-fix-list.json`; consume only `project_name`, `project_description`, `global_context`, `task_count`, `next_id`, and the five most recently appended top-level bugs as `{id, description}` pairs (or all available bugs when fewer than five exist).
165
- 2. Inspect those pairs only for material continuation, duplication, conflict, a shared public behavior contract, or an execution prerequisite. Add no historical content by default. Chronology, broad module overlap, shared technology, reusable implementation ideas, or similar wording alone do not establish relevance.
166
- 3. Incorporate only the minimum exact information whose omission would make scope, behavior, compatibility, acceptance criteria, or dependency ordering incorrect. Reject vague `related to B-123` text and whole-description copying; add an old ID to `dependencies` only when it is a real execution prerequisite.
167
- 4. Only for an explicitly identified old ID or a validation error, run `python3 ${SKILL_DIR}/scripts/validate-bug-list.py show --input .prizmkit/plans/bug-fix-list.json --id B-NNN`.
168
- 5. For append-only planning, write `.prizmkit/plans/bug-fix-list.draft.json` with exactly one root field, `bugs`, containing non-empty unchanged-schema items. This bounded draft is a private reasoning workspace and the review target, not a user approval artifact or a deliverable. Required draft fields are `id`, `title`, `description`, `severity`, `error_source`, `verification_type`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; existing optional fields remain allowed. Copy no root metadata or historical bugs.
169
- 6. After consequential decisions and the pre-generation gate pass, write the batch to the additions-only draft with the `context` IDs and check merge feasibility without writing: `python3 ${SKILL_DIR}/scripts/validate-bug-list.py append --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json --dry-run`. Do not ask for separate user approval merely to promote the draft into the final list. The dry run applies the same base, exact-ID, dependency, and complete-DAG checks the real insert will, so a `PASS` review is a promise the insert keeps. Run the real `append` once, after §Local Generated-Plan Review Gate returns `PASS`, then follow §Draft Lifecycle. `generate` remains the new-list/full-rewrite path.
170
- ## Scenario Routing
171
-
172
- Classify user intent first:
173
-
174
- ### Route A: New Bug List (No Existing Plan)
175
-
176
- Use when no `.prizmkit/plans/bug-fix-list.json` exists.
38
+ ## Priority, Severity & Scenario Routing
177
39
 
178
- Actions:
179
- 1. Run full Interactive Planning (Phase 1-5)
180
- 2. Generate initial `.prizmkit/plans/bug-fix-list.json`
40
+ Preserve exact Severity → Priority mapping (`critical`/`high` → `high`, `medium` → `medium`, `low` → `low`). During bug extraction and prioritization, follow `${SKILL_DIR}/references/severity-rules.md`: do not collapse into uniform `high/high`; require a concrete high-impact indicator (core outage, data loss/integrity, security/auth failure, timeout/crash/500, no workaround) and show `ID | Title | Severity | Severity Rationale | Priority | Priority Rationale | Verification` before writing.
181
41
 
182
- ### Route B: Append to Existing Bug List
183
-
184
- Use when `.prizmkit/plans/bug-fix-list.json` already exists and user wants to add more bugs.
185
-
186
- Actions:
187
- 1. Run the bounded `context` command from §Bounded Existing-List Context (if the file is missing, ask whether to start a new plan); do not read the complete list
188
- 2. Continue with the returned next sequential `B-NNN` ID
189
- 3. Write only new bugs to the additions-only draft and merge through `append`
190
- 4. Preserve existing entries and validate the complete merged list outside AI context
191
-
192
- ---
42
+ **Operations**: **Interactive Planning** (`plan bug fixes`, `report bugs`) · **From Log** (`parse errors`, stack traces) · **From Tests** (`these tests are failing`, `parse test output`) · **Validate** (`validate bug list`) · **Summary** (`bug summary`, `list bugs`). Route A generates a new list (`Phase 1-5`); Route B appends via bounded `context` → draft → `append`.
193
43
 
194
44
  ## Operation: Interactive Planning
195
45
 
196
- Triggers: "plan bug fixes", "report bugs".
197
-
198
- Launch the interactive bug planning process through 5 phases.
199
-
200
- ### Phase 1: Project Context
201
-
202
- 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.
203
-
204
- 1. **Identify project**: Read project name and description from these sources (first match wins):
205
- - `.prizmkit/config.json` (`project_name`, `description` fields)
206
- - `.prizmkit/prizm-docs/root.prizm` (project overview section)
207
- - `package.json` / `pyproject.toml` / `Cargo.toml` (name + description fields)
208
- - If none found, ask the user
209
- 2. **Identify tech stack**: Read from these sources (first match wins):
210
- - `.prizmkit/config.json` `tech_stack` (preferred — contains language, frameworks, DB, etc.)
211
- - `.prizmkit/prizm-docs/root.prizm` (architecture section)
212
- - Auto-detect from project files (`package.json`, `requirements.txt`, `go.mod`, etc.)
213
- - If none found, ask the user
214
- 3. **Identify testing framework**: Read from `.prizmkit/config.json` `tech_stack.testing`, or auto-detect from package.json/requirements.txt/etc., or ask user
215
- 4. **Clarify context by impact** — inspect project evidence first. Ask when ambiguity in the environment, affected systems, expected behavior, or scope would materially alter the bug contract; label recommendations as recommendations and group related questions unless one answer changes the next. Record low-risk reversible assumptions explicitly instead of questioning until subjective full understanding.
216
- 5. **Collect reference materials** — **Upfront Material Detection (Hard Rule)**: If the user has already provided materials (file paths, URLs, rules, specifications, code snippets) in the same message that invoked this skill: (a) Acknowledge what was received: "I received the following materials: [list]"; (b) Read/fetch all provided materials immediately; (c) You MUST still ask: "Are there any additional materials you'd like to provide?"; (d) NEVER skip this collection step just because the user already provided some materials.
217
-
218
- If the user has NOT provided any materials upfront, explicitly ask whether they have any supplementary materials for you to review before proceeding to bug collection:
219
- > "Do you have any reference materials I should review to better understand these bugs? This can include:
220
- > - **Code paths** — files or directories where the bugs likely originate
221
- > - **Documents** — related design docs, API specs, or architecture docs for the affected area
222
- > - **Error screenshots** — UI screenshots, console output images, or monitoring dashboards
223
- > - **Web links** — related issue tracker links, Stack Overflow threads, or documentation pages
224
- > - **Log files** — error log paths or monitoring tool URLs
225
- >
226
- > If none, we'll proceed with bug collection."
227
-
228
- If the user provides materials, require or infer only when unambiguous a bug-specific purpose for each material; otherwise ask what the execution AI should inspect. Read/fetch the relevant material before Phase 2. For web links, retrieve the relevant content; for images, analyze the relevant visual evidence. Material ingestion follows the same durability rule as final output: copy or normalize task-relevant requirements and exact evidence, omit transient non-code paths, and retain only purpose-tagged stable execution-time sources. Do not inject complete large materials merely to preserve them.
229
-
230
- Output: `project_name`, `project_description`, `global_context` fields populated.
231
-
232
- **Gate → CP-BP-1**: Tech stack and project info confirmed before proceeding.
233
-
234
- ### Phase 2: Bug Collection
235
-
236
- Accept bug information in ANY of these formats (auto-detect):
237
-
238
- #### Severity & Input Format References
239
-
240
- When classifying severity, read `${SKILL_DIR}/references/severity-rules.md` for the auto-classification table (critical/high/medium/low indicators and special cases).
241
-
242
- 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.
243
-
244
- **For each bug collected**, interactively confirm or fill in:
245
- - Title (auto-suggest from error message, user can edit)
246
- - Description (auto-generate expected vs actual, user can edit)
247
- - Severity (auto-suggest based on error type, user can override)
248
- - Environment (ask or auto-detect from logs)
249
- - Verification type (suggest `automated` by default, ask user)
250
- - Acceptance criteria (auto-suggest based on description, user can edit)
251
- - Model override (optional; if specified, overrides $MODEL env var for this bug fix)
252
-
253
- **Per-bug clarification** — require confirmed current/actual behavior, desired/expected behavior, consequential scope, severity rationale, and verification decisions. Inspect evidence before asking, group related consequential questions, and label any root cause, code location, integration impact, or fix direction as confirmed, evidence-backed hypothesis, or unknown. A fresh execution session may investigate an unknown root cause; do not force certainty or invent a fix merely to finish planning. Do not finalize shorthand that requires an unseen question, recommendation, or option list.
254
-
255
- **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.
256
-
257
- 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."
258
-
259
- Only finalize the bug entry after user confirms all three points.
260
-
261
- **Multiple bugs per session**: After each bug, ask "Any more bugs to add? (yes/no)"
262
-
263
- **Gate → CP-BP-2**: All bugs extracted and confirmed by user.
46
+ ### Phase 1: Project Context (CP-BP-1)
47
+ Gather `project_name`, `project_description`, `global_context` (`tech_stack`, `testing`) from `.prizmkit/config.json`, `.prizmkit/prizm-docs/root.prizm`, or project manifests (ask if missing). Clarify consequential context gaps by impact.
48
+ **Upfront Material Detection (Hard Rule)**: If materials were supplied upfront, acknowledge them ("I received the following materials: [list]"), read/fetch them immediately, AND still ask "Are there any additional materials you'd like to provide?". Otherwise ask once for code paths, docs/API specs, error screenshots, web links, or log files. Tag bug-specific purposes and normalize cleanly: Material ingestion follows the same durability rule as final output (inline excerpts, omit transient non-code paths, retain purpose-tagged stable refs).
264
49
 
265
- ### Phase 3: Prioritization & Review
50
+ ### Phase 2: Bug Collection (CP-BP-2)
51
+ Read `${SKILL_DIR}/references/severity-rules.md` and `${SKILL_DIR}/references/input-formats.md` (and `${SKILL_DIR}/references/verification.md` when `verification_type` is `manual`/`hybrid` or involves UI/browser flows) to extract Title, Description (expected vs actual + severity rationale), Severity, Environment, Verification type (`automated` default), Acceptance criteria (verifiable, never subjective), and optional model override.
52
+ - **Per-bug clarification**: require confirmed actual/expected behavior, scope, severity rationale, and verification decisions; keep unverified root cause/location as evidence-backed hypotheses or unknowns.
53
+ - **Per-bug confirmation (mandatory)** — present the structured summary using `${SKILL_DIR}/assets/bug-confirmation-template.md`, ask its three confirmation questions, finalize only after user confirms all three, and ask "Any more bugs to add? (yes/no)".
266
54
 
267
- 1. **Auto-assign priorities**: Based on severity, adjustable by user; require a short severity rationale and priority rationale for each bug
268
-
269
- **Severity → Priority Mapping**:
270
- - `critical` severity → `high` priority (treated with highest urgency)
271
- - `high` severity → `high` priority
272
- - `medium` severity → `medium` priority
273
- - `low` severity → `low` priority
274
-
275
- 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. Preserve this mapping exactly.
276
-
277
- **Calibration check before accepting high**:
278
- - High/critical severity requires a concrete indicator: core feature outage, data loss/integrity, security/privacy/auth failure, timeout/crash/production 500, or no workaround.
279
- - If the report is "annoying", partially broken, has a workaround, or affects a non-critical edge case, prefer `medium` or `low` as documented in the severity rules.
280
- - Do not treat "needs fixing", "user reported it", or "framework bug" as automatic high priority.
281
- 2. **Display summary table with rationales**:
282
- ```
283
- ID | Title | Severity | Severity Rationale | Priority | Priority Rationale | Verification
284
- B-001 | Login null reference crash | high | Core auth fails; no workaround | high | High severity maps to high | automated
285
- B-002 | CSV export Chinese encoding | medium | Incorrect output; workaround exists | medium | Medium severity maps to medium | hybrid
286
- B-003 | Slow dashboard loading | low | Non-critical page; minor delay | low | Low severity maps to low | manual
287
- ```
288
- 3. **Ask for adjustments**: "Want to reorder priorities, change severity, or remove any bugs?"
289
- 4. **Detect potential duplicates**: If two bugs have similar error messages or affected modules, warn user
290
-
291
- **Gate → CP-BP-3**: Severity/priority assigned, duplicates resolved.
292
-
293
- ### Phase 4: Pre-Generation Headless Context Completeness Gate
294
-
295
- Before generating `.prizmkit/plans/bug-fix-list.json`, review every new or changed bug as if the reviewer has never seen the planning conversation. Preserve unchanged historical bugs; do not bulk-rewrite them. Scan all AI-visible fields and sections first: every generated natural-language value in `project_description`, `global_context`, item fields, `error_source`, environment/evidence, `user_context`, comments, and parentheticals must be session-independent, with no dialogue-role labels, question IDs, answer tokens, planning-option recommendation markers, or planning provenance. Review changed root prose even when no bug item changed. Then remove `user_context` from the review view and answer from `description` plus `acceptance_criteria` alone:
55
+ ### Phase 3: Prioritization & Review (CP-BP-3)
56
+ Apply calibrated Severity → Priority mapping (using `${SKILL_DIR}/references/severity-rules.md`), display the rationale summary table, detect duplicates, and ask for reordering/adjustments.
296
57
 
58
+ ### Phase 4: Pre-Generation Headless Context Completeness Gate (CP-BP-4)
59
+ Before generating `.prizmkit/plans/bug-fix-list.json`, review every new or changed bug as if the reviewer has never seen the planning conversation (preserve unchanged historical bugs; review changed root prose even when no bug item changed). Scan all AI-visible fields and sections first (`project_description`, `global_context`, item fields, `error_source`, environment/evidence, `user_context`, comments, parentheticals) for standalone domain statements. Do not emit transcript annotations (`(original response: "...")`), blanket recommendation approval (`全部按照推荐`), dialogue/question/option tokens, or standalone shorthand. Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`; normalize content inline. Remove `user_context` from the review view and answer from `description` plus `acceptance_criteria` alone:
297
60
  1. What exact problem or outcome is this task responsible for?
298
61
  2. What exists today, including actual behavior, and what must change to the expected behavior?
299
62
  3. Which fix scope and verification approach were selected, expressed by meaning rather than an option label?
@@ -303,51 +66,16 @@ Before generating `.prizmkit/plans/bug-fix-list.json`, review every new or chang
303
66
  7. Does any phrase require an unseen earlier question, recommendation, or option list?
304
67
  8. Do quoted source materials agree with the final task decision?
305
68
 
306
- Return `NEEDS_FIXES` whenever any answer is missing, ambiguous, or available only in supplementary evidence. Ask the user for clarification rather than guessing when a reference does not have one provable antecedent.
307
-
308
- **Step 1 — Description adequacy scan (Headless Execution Readiness)**: The bugfix pipeline runs each bug through an autonomous AI session with NO human interaction. Every task contract must be unambiguous enough for headless execution. For each bug, check:
309
- - Description clearly states **expected** vs **actual** behavior (not just "X doesn't work")
310
- - Reproduction path is specific enough for the pipeline AI to locate the relevant code
311
- - If the bug involves user interaction, the trigger action is described (not just the symptom)
312
- - **Code location guidance**: Provide evidence-backed file/module/function hints when known; otherwise state the bounded discovery target and mark the exact location unknown rather than inventing one
313
- - **Verification method**: How should the AI verify the fix? (run specific test, check specific behavior)
314
- - Bad: "Login is broken" — too vague, AI will search the entire codebase
315
- - 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."
316
-
317
- **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"), omit expected behavior, or leave reproduction and verification decisions only in `user_context`.
318
-
319
- **Step 3 — Cross-bug analysis**: Check for:
320
- - **Root cause overlap**: Keep one bug per task. Multiple bugs in the same module are not merged by module. Merge only when they share the same root cause or the same failing contract and the user confirms.
321
- - **Missing dependencies**: If fixing B-002 requires B-001 to be fixed first, flag the dependency
322
- - **Scope gaps**: If bugs describe symptoms but the underlying cause likely affects more areas, suggest additional bugs
323
-
324
- **Step 4 — Present review table**: Display the completeness assessment using the template in `${SKILL_DIR}/assets/bug-confirmation-template.md` (§Completeness Review Template).
325
-
326
- For any items that need attention, ask targeted questions to fill consequential gaps. Iterate until every flagged semantic gap is resolved. Present the prompt:
327
-
328
- > "Above is the completeness review. Every `NEEDS_FIXES` item must be clarified before generation. Which flagged item should we address first?"
329
-
330
- For every `NEEDS_FIXES` result, ask only for the consequential missing decision, update the draft/source bug contract, and rerun the artifact-alone questions until all new or changed bugs return `PASS`. Then proceed directly to Phase 5; do not add a separate approval merely to write the already-confirmed content.
331
-
332
- **Gate → CP-BP-4**: All new or changed bugs pass the Headless Context Completeness Gate without relying on conversation history or `user_context`.
69
+ Return `NEEDS_FIXES` whenever any answer is missing, ambiguous, or present only in `user_context` (ask rather than guessing; update the draft/source bug contract and re-run until `PASS`). Run Steps 1–4 in `${SKILL_DIR}/references/input-formats.md` (adequacy scan, autonomy test on acceptance criteria, root-cause/dependency cross-check, and `${SKILL_DIR}/assets/bug-confirmation-template.md` §Completeness Review Template) until every new/changed bug returns `PASS`, then proceed directly to Phase 5.
333
70
 
334
- ### Phase 5: Generate & Validate
335
-
336
- 1. **Write draft JSON**: For a new list, write the complete `.prizmkit/plans/bug-fix-list.draft.json` conforming to the final schema. For an existing list, follow §Bounded Existing-List Context and write only the additions-only `bugs` object. The draft is the review target, so nothing is written to the final list yet.
337
- 2. **Check merge feasibility without writing** — once required semantic gates pass, run the matching check without a second draft-approval pause:
338
- - New list or explicit full-list rewrite: the draft is complete and nothing exists to overwrite, so its post-review `generate` is the validator.
339
- - Ordinary existing-list append:
340
- ```bash
341
- python3 ${SKILL_DIR}/scripts/validate-bug-list.py append --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json --dry-run
342
- ```
343
- The dry run applies the same base, exact-ID, dependency, and complete-DAG checks the real insert will, including `append`'s preservation of root metadata and historical bugs.
344
- 3. **If validation fails**: Fix the draft and retry (max 3 attempts). If the script is unavailable, use the checklist in `${SKILL_DIR}/references/schema-validation.md`.
345
- 4. **Run the mandatory Local Generated-Plan Review Gate** (see §Local Generated-Plan Review Gate below): load `${SKILL_DIR}/references/generated-plan-review.md` and review only the draft batch before the insert.
346
- 5. **Insert once and output**: After local review returns `PASS`, run a single `append`/`generate`, confirm its `appended_ids`, follow §Draft Lifecycle, then report the file path, summary, local review, inserted IDs, validation, cleanup result, and next steps.
347
-
348
- **Gate → CP-BP-5**: The draft batch validates and its merge dry run returns zero errors; the final list is still untouched.
349
-
350
- **Gate → CP-BP-6**: Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only the draft batch, applied accepted fixes through the draft, revalidated, returned `PASS`, then ran exactly one insert whose `appended_ids` match the batch and removed the draft.
71
+ ### Phase 5: Generate & Validate (CP-BP-5 → CP-BP-6)
72
+ 1. Write `.prizmkit/plans/bug-fix-list.draft.json` (complete for new list, `{ "bugs": [...] }` for existing list).
73
+ 2. Check merge feasibility without writing (for existing lists):
74
+ ```bash
75
+ python3 ${SKILL_DIR}/scripts/validate-bug-list.py append --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json --dry-run
76
+ ```
77
+ Retry validation fixes at most 3 times (fallback checklist in `${SKILL_DIR}/references/schema-validation.md`).
78
+ 3. Run §Local Generated-Plan Review Gate until `PASS`, insert once (`append` or `generate`), complete §Draft Lifecycle cleanup, and report output summary.
351
79
 
352
80
  ## Local Generated-Plan Review Gate
353
81
 
@@ -355,135 +83,26 @@ Run this gate after the batch is written to the draft and passes draft validatio
355
83
 
356
84
  Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the draft directly, reading `.prizmkit` artifacts from disk rather than from `git status` or `git diff`, because those files may be gitignored. Use bounded `context` and explicit-ID `show` only for already-committed entries whose contract or dependency semantics a reviewed item relies on; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed bug. Keep the review planning-only: apply accepted findings to the draft, re-run draft validation and the merge dry run, and repeat local review until it returns `PASS`. Only then insert once and complete §Draft Lifecycle cleanup before reporting the final written result. If the insert is rejected after `PASS`, nothing landed; fix the draft, re-run validation and the dry run, and re-review only the entries you changed.
357
85
 
358
- #### Success Output
359
-
360
- Report the final path and bug counts, Local Generated-Plan Review verdict and reviewed batch IDs, accepted fixes, the single insert's `appended_ids` and validation result, draft cleanup result, and `bugfix-pipeline-launcher` handoff.
361
-
362
- ### Checkpoints (Mandatory Gates)
363
-
364
- Checkpoints catch cascading errors early — skipping one means the next phase builds on unvalidated assumptions.
365
-
366
- | Checkpoint | Artifact/State | Criteria | Phase |
367
- |-----------|----------------|----------|-------|
368
- | **CP-BP-1** | Project Context | Tech stack and project info confirmed | 1 |
369
- | **CP-BP-2** | Bugs Collected | All bugs extracted and confirmed by user | 2 |
370
- | **CP-BP-3** | Priorities Set | Severity/priority assigned, duplicates resolved | 3 |
371
- | **CP-BP-4** | Completeness Passed | All bugs pass headless execution readiness check | 4 |
372
- | **CP-BP-5** | Draft Batch Ready | Additions-only or complete draft holds the whole batch with `context` IDs; merge dry run clean; final list still untouched | 5 |
373
- | **CP-BP-6** | Reviewed, Then Inserted Once | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only the draft batch, applied accepted fixes through the draft, revalidated, returned `PASS`, then ran exactly one insert whose `appended_ids` match the batch, and removed the draft | 5 |
374
-
375
- **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.
376
-
377
- ---
86
+ **Checkpoints**: **CP-BP-1** Project Context (1) · **CP-BP-2** Bugs Collected (2) · **CP-BP-3** Priorities Set (3) · **CP-BP-4** Completeness Passed (4) · **CP-BP-5** Draft Batch Ready + merge dry run clean (5) · **CP-BP-6** Reviewed, Then Inserted Once (`generated-plan-review.md` reviewed draft batch → accepted fixes → revalidated → `PASS` → single insert matching `appended_ids` → draft removed; 5). For resume support, read `${SKILL_DIR}/references/error-recovery.md`.
378
87
 
379
88
  ## Operation: From Log
380
-
381
- Triggers: "parse this error log", "here's a stack trace", "parse these errors".
382
-
383
- Batch-parse error logs with minimal interaction: parse automatically, resolve consequential gaps through targeted questions, then write the final list immediately:
384
-
385
- 1. Accept log file path or piped content
386
- 2. Parse all unique errors (deduplicate by error message pattern)
387
- 3. Auto-generate bug entries with:
388
- - Title: first line of error message
389
- - Description: full error context
390
- - Severity: use `${SKILL_DIR}/references/severity-rules.md`
391
- - error_source: populated from log content
392
- - verification_type: default to `automated`
393
- - acceptance_criteria: auto-generate "Error no longer occurs in [scenario]"
394
- 4. Write `.prizmkit/plans/bug-fix-list.draft.json` as the private review workspace.
395
- 5. Run the Phase 4 Headless Context Completeness Gate on every parsed bug. Ask targeted clarification for missing expected behavior, selected scope, severity rationale, or verification decisions; update the draft until all entries pass.
396
- 6. Check merge feasibility without writing: the complete draft for a new list, or `append --dry-run` when a final list already exists. Do not add another broad approval after the consequential gaps are resolved.
397
- 7. Run the mandatory Local Generated-Plan Review Gate on the draft; on `PASS`, insert once with the matching Phase 5 writer, complete §Draft Lifecycle cleanup, and present the final written result. For later adjustments, recreate the minimum source draft from confirmed in-memory entries or exact-ID `show`, then rerun `generate` for a new-list rewrite or `append --replace-tail` for an ordinary append before recommending `bugfix-pipeline-launcher`.
89
+ Triggers: `"parse this error log"`, `"here's a stack trace"`, `"parse these errors"`.
90
+ 1. Accept log path/content, deduplicate unique errors, and generate entries (Severity via `severity-rules.md`, `error_source`, `verification_type: "automated"`, measurable criteria).
91
+ 2. Write `.prizmkit/plans/bug-fix-list.draft.json`. Run the Phase 4 Headless Context Completeness Gate on every parsed bug (clarifying missing expected behavior, scope, rationale, or verification).
92
+ 3. Run merge check (`--dry-run` if list exists) and §Local Generated-Plan Review Gate (`PASS`), insert once, complete §Draft Lifecycle cleanup, and present final result. For later adjustments, recreate the minimum source draft from confirmed in-memory entries or exact-ID `show`, then rerun `generate` or `append --replace-tail` before recommending `bugfix-pipeline-launcher`.
398
93
 
399
94
  ## Operation: From Tests
400
-
401
- Triggers: "these tests are failing", "parse test output".
402
-
403
- Batch-parse failed test output:
404
-
405
- 1. Accept test runner output (Jest, pytest, Go test, etc.)
406
- 2. Parse each failed test case as a separate bug entry
407
- 3. Auto-populate `failed_test_path`, `error_message`
408
- 4. Set verification_type to `automated` (test already exists)
409
- 5. Write `.prizmkit/plans/bug-fix-list.draft.json` as the private review workspace.
410
- 6. Run the Phase 4 Headless Context Completeness Gate on every parsed failed-test bug; ask only for consequential missing expected behavior or scope, and allow needed edits, merges, or removals until all entries pass.
411
- 7. Check merge feasibility without writing: the complete draft for a new list, or `append --dry-run` when a final list already exists. Do not add another broad approval after the consequential gaps are resolved.
412
- 8. Run the mandatory Local Generated-Plan Review Gate on the draft; on `PASS`, insert once with the matching Phase 5 writer, complete §Draft Lifecycle cleanup, and present the final written result. For later adjustments, recreate the minimum source draft from confirmed in-memory entries or exact-ID `show`, then rerun `generate` for a new-list rewrite or `append --replace-tail` for an ordinary append before recommending `bugfix-pipeline-launcher`.
413
-
414
- ## Operation: Validate
415
-
416
- Triggers: "validate bug list", "check .prizmkit/plans/bug-fix-list.json".
417
-
418
- Run the deterministic validator so this operation uses the same contract as generation:
419
-
420
- ```bash
421
- python3 ${SKILL_DIR}/scripts/validate-bug-list.py validate .prizmkit/plans/bug-fix-list.json
422
- ```
423
-
424
- Report the validator's errors and warnings without modifying source code. If the file needs correction, update the planning draft or final planning artifact only, then rerun the validator.
425
-
426
- ## Operation: Summary
427
-
428
- Triggers: "bug summary", "show bug list", "list bugs".
429
-
430
- Print human-readable summary:
431
-
432
- ```
433
- Bug Fix List Summary: my-web-app
434
-
435
- Total: 3 bugs
436
- By Severity: critical=1, high=0, medium=1, low=1
437
- By Status: pending=3
438
-
439
- Bug List (by priority):
440
- 1. [B-001] Login null reference crash (CRITICAL) — automated
441
- 2. [B-002] CSV export Chinese encoding (MEDIUM) — hybrid
442
- 3. [B-003] Slow dashboard loading (LOW) — manual
443
- ```
444
-
445
- ---
446
-
447
- ## Verification Defaults
448
-
449
- When configuring bug verification, read `${SKILL_DIR}/references/verification.md` for verification type and browser verification guidance.
450
-
451
- Key points:
452
- - Critical/high severity bugs require clear automated, manual, or hybrid verification evidence.
453
- - Medium/low severity bugs use the smallest verification that proves the fix and guards against regression.
454
- - `browser_interaction` is supported for UI-reproducible bugs; `verification_type` still declares whether verification is automated, manual, or hybrid.
455
-
456
- ---
457
-
458
- ## Next-Step Execution Policy
459
-
460
- Recommend invoking `bugfix-pipeline-launcher` to configure and launch the pipeline. Do NOT recommend running shell scripts directly — that is the launcher's responsibility.
461
-
462
- After `.prizmkit/plans/bug-fix-list.json` is inserted, present:
463
- 1. Summary of generated bugs (count, severity breakdown)
464
- 2. Local generated-plan review result: verdict, reviewed batch IDs plus reviewed root prose when applicable, and accepted fixes (or "none")
465
- 3. Insert result: the single writer run and the `appended_ids` it reported
466
- 4. Draft cleanup result: `removed`, or retained path and recovery reason
467
- 5. Recommend: "Say 'start fixing' to launch the bugfix pipeline via `bugfix-pipeline-launcher`"
468
- 6. Alternative: fix a single bug interactively via `bug-fix-workflow`
469
-
470
- ## Error Handling
471
-
472
- 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.
473
-
474
- Common errors handled inline:
475
-
476
- | Error | Action |
477
- |-------|--------|
478
- | Cannot parse error log format | Ask user to specify format or provide raw text |
479
- | Ambiguous severity classification | Present options, ask user to choose |
480
- | Duplicate bug detected | Warn user, suggest merging or keeping separate |
481
- | No bugs provided | Prompt with examples of supported input formats |
482
- | Invalid dependency reference | Warn and ask user to correct or remove the dependency |
483
- | Schema validation failure | Show specific errors, offer to fix interactively |
484
-
485
- ## Output
486
-
487
- - `.prizmkit/plans/bug-fix-list.json` conforming to `.prizmkit/dev-pipeline/templates/bug-fix-list-schema.json`
488
- - Validation report (if validation run)
489
- - Summary report (if summary run)
95
+ Triggers: `"these tests are failing"`, `"parse test output"`.
96
+ 1. Parse failed test cases (`failed_test_path`, `error_message`, `verification_type: "automated"`).
97
+ 2. Write `.prizmkit/plans/bug-fix-list.draft.json`. Run the Phase 4 Headless Context Completeness Gate on every parsed failed-test bug (clarifying consequential missing expectations/scope; allow edits/merges/removals).
98
+ 3. Run merge check + §Local Generated-Plan Review Gate (`PASS`), insert once, complete §Draft Lifecycle cleanup, and present final result. For later adjustments, recreate the minimum source draft from confirmed in-memory entries or exact-ID `show`, then rerun `generate` or `append --replace-tail` before recommending `bugfix-pipeline-launcher`.
99
+
100
+ ## Operation: Validate & Operation: Summary
101
+ - **Validate** (`"validate bug list"`, `"check .prizmkit/plans/bug-fix-list.json"`): run `python3 ${SKILL_DIR}/scripts/validate-bug-list.py validate .prizmkit/plans/bug-fix-list.json` and report errors/warnings without modifying source code.
102
+ - **Summary** (`"bug summary"`, `"show bug list"`, `"list bugs"`): print totals by severity/status and prioritized `[B-NNN] Title (SEVERITY) — verification_type` summary.
103
+
104
+ ## Verification, Policy, Errors & Output
105
+ - **Verification Defaults**: Apply `${SKILL_DIR}/references/verification.md` defaults (`automated`/`manual`/`hybrid`; `browser_interaction` for UI bugs) when not already resolved in Phase 2.
106
+ - **Next-Step Execution Policy**: Report bug summary/counts, Local generated-plan review result (verdict, reviewed batch IDs plus reviewed root prose when applicable, accepted fixes), single insert `appended_ids` + validation result, Draft cleanup result: `removed`, or retained path and recovery reason, and recommend `bugfix-pipeline-launcher` (or `bug-fix-workflow` for a single interactive bug). Never run scripts directly or auto-execute.
107
+ - **Error Handling**: Read `${SKILL_DIR}/references/error-recovery.md` on validation failures/interruptions (ask clarifying questions on unparseable logs, ambiguous severity, potential duplicates, empty input, or broken dependencies).
108
+ - **Output**: `.prizmkit/plans/bug-fix-list.json` conforming to `.prizmkit/dev-pipeline/templates/bug-fix-list-schema.json` (plus validation/summary report when requested).
@@ -91,8 +91,9 @@ The dry run enforces the same base, exact-ID, dependency, and complete-DAG check
91
91
 
92
92
  5. Never hand-patch `.prizmkit/plans/bug-fix-list.json` as the source of truth and do not add a user approval round for the mechanical rewrite.
93
93
  6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
94
- 7. Do not report `PASS` until every required fresh-session answer is available and the draft validation plus merge dry run pass.
95
- 8. After `PASS`, insert the batch exactly once (`append`, or `generate` for a new list), confirm the writer's `appended_ids`, then delete `.prizmkit/plans/bug-fix-list.draft.json`. Retain a draft only under the conditions in `${SKILL_DIR}/references/error-recovery.md`; report the retained path and reason.
94
+ 7. **Confirmed-Decision Anchoring & Bounded Convergence**: user-confirmed actual/expected behavior, behavioral scope, technical choices, and non-goals are anchored constraints; this loop may only repair self-containment, normalization, completeness, or schema/DAG defects and must never silently overturn confirmed decisions or oscillate between alternative designs across re-review passes (cap local re-review at 3 passes before asking the user to resolve any remaining ambiguity).
95
+ 8. Do not report `PASS` until every required fresh-session answer is available and the draft validation plus merge dry run pass.
96
+ 9. After `PASS`, insert the batch exactly once (`append`, or `generate` for a new list), confirm the writer's `appended_ids`, then delete `.prizmkit/plans/bug-fix-list.draft.json`. Retain a draft only under the conditions in `${SKILL_DIR}/references/error-recovery.md`; report the retained path and reason.
96
97
 
97
98
  ## Report Format
98
99