prizmkit 1.1.57 → 1.1.60

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 (188) hide show
  1. package/bin/create-prizmkit.js +8 -6
  2. package/bundled/VERSION.json +3 -3
  3. package/bundled/adapters/codex/agent-adapter.js +38 -0
  4. package/bundled/adapters/codex/paths.js +27 -0
  5. package/bundled/adapters/codex/rules-adapter.js +30 -0
  6. package/bundled/adapters/codex/settings-adapter.js +27 -0
  7. package/bundled/adapters/codex/skill-adapter.js +65 -0
  8. package/bundled/adapters/codex/team-adapter.js +37 -0
  9. package/bundled/dev-pipeline/.env.example +2 -1
  10. package/bundled/dev-pipeline/README.md +10 -7
  11. package/bundled/dev-pipeline/lib/common.sh +278 -37
  12. package/bundled/dev-pipeline/run-bugfix.sh +10 -61
  13. package/bundled/dev-pipeline/run-feature.sh +10 -78
  14. package/bundled/dev-pipeline/run-recovery.sh +10 -46
  15. package/bundled/dev-pipeline/run-refactor.sh +10 -61
  16. package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py +17 -7
  17. package/bundled/dev-pipeline/scripts/generate-bugfix-prompt.py +9 -3
  18. package/bundled/dev-pipeline/scripts/generate-refactor-prompt.py +9 -3
  19. package/bundled/dev-pipeline/scripts/utils.py +6 -4
  20. package/bundled/dev-pipeline-windows/.env.example +28 -0
  21. package/bundled/dev-pipeline-windows/README.md +30 -0
  22. package/bundled/dev-pipeline-windows/SCHEMA_ANALYSIS.md +525 -0
  23. package/bundled/dev-pipeline-windows/assets/feature-list-example.json +146 -0
  24. package/bundled/dev-pipeline-windows/assets/prizm-dev-team-integration.md +138 -0
  25. package/bundled/dev-pipeline-windows/launch-bugfix-daemon.ps1 +9 -0
  26. package/bundled/dev-pipeline-windows/launch-feature-daemon.ps1 +9 -0
  27. package/bundled/dev-pipeline-windows/launch-refactor-daemon.ps1 +9 -0
  28. package/bundled/dev-pipeline-windows/lib/common.ps1 +432 -0
  29. package/bundled/dev-pipeline-windows/lib/daemon.ps1 +140 -0
  30. package/bundled/dev-pipeline-windows/lib/pipeline.ps1 +446 -0
  31. package/bundled/dev-pipeline-windows/lib/reset.ps1 +87 -0
  32. package/bundled/dev-pipeline-windows/reset-bug.ps1 +9 -0
  33. package/bundled/dev-pipeline-windows/reset-feature.ps1 +9 -0
  34. package/bundled/dev-pipeline-windows/reset-refactor.ps1 +9 -0
  35. package/bundled/dev-pipeline-windows/run-bugfix.ps1 +9 -0
  36. package/bundled/dev-pipeline-windows/run-feature.ps1 +9 -0
  37. package/bundled/dev-pipeline-windows/run-recovery.ps1 +76 -0
  38. package/bundled/dev-pipeline-windows/run-refactor.ps1 +9 -0
  39. package/bundled/dev-pipeline-windows/scripts/check-session-status.py +228 -0
  40. package/bundled/dev-pipeline-windows/scripts/cleanup-logs.py +192 -0
  41. package/bundled/dev-pipeline-windows/scripts/detect-stuck.py +530 -0
  42. package/bundled/dev-pipeline-windows/scripts/generate-bootstrap-prompt.py +1737 -0
  43. package/bundled/dev-pipeline-windows/scripts/generate-bugfix-prompt.py +685 -0
  44. package/bundled/dev-pipeline-windows/scripts/generate-recovery-prompt.py +805 -0
  45. package/bundled/dev-pipeline-windows/scripts/generate-refactor-prompt.py +763 -0
  46. package/bundled/dev-pipeline-windows/scripts/init-bugfix-pipeline.py +316 -0
  47. package/bundled/dev-pipeline-windows/scripts/init-dev-team.py +134 -0
  48. package/bundled/dev-pipeline-windows/scripts/init-pipeline.py +380 -0
  49. package/bundled/dev-pipeline-windows/scripts/init-refactor-pipeline.py +399 -0
  50. package/bundled/dev-pipeline-windows/scripts/parse-stream-progress.py +388 -0
  51. package/bundled/dev-pipeline-windows/scripts/patch-completion-notes.py +191 -0
  52. package/bundled/dev-pipeline-windows/scripts/update-bug-status.py +864 -0
  53. package/bundled/dev-pipeline-windows/scripts/update-checkpoint.py +173 -0
  54. package/bundled/dev-pipeline-windows/scripts/update-feature-status.py +1501 -0
  55. package/bundled/dev-pipeline-windows/scripts/update-refactor-status.py +1073 -0
  56. package/bundled/dev-pipeline-windows/scripts/utils.py +542 -0
  57. package/bundled/dev-pipeline-windows/templates/agent-prompts/critic-plan-challenge.md +7 -0
  58. package/bundled/dev-pipeline-windows/templates/agent-prompts/dev-fix.md +7 -0
  59. package/bundled/dev-pipeline-windows/templates/agent-prompts/dev-implement.md +30 -0
  60. package/bundled/dev-pipeline-windows/templates/agent-prompts/dev-resume.md +5 -0
  61. package/bundled/dev-pipeline-windows/templates/agent-prompts/reviewer-review.md +7 -0
  62. package/bundled/dev-pipeline-windows/templates/bootstrap-prompt.md +46 -0
  63. package/bundled/dev-pipeline-windows/templates/bootstrap-tier1.md +43 -0
  64. package/bundled/dev-pipeline-windows/templates/bootstrap-tier2.md +43 -0
  65. package/bundled/dev-pipeline-windows/templates/bootstrap-tier3.md +43 -0
  66. package/bundled/dev-pipeline-windows/templates/bug-fix-list-schema.json +263 -0
  67. package/bundled/dev-pipeline-windows/templates/bugfix-bootstrap-prompt.md +320 -0
  68. package/bundled/dev-pipeline-windows/templates/feature-list-schema.json +237 -0
  69. package/bundled/dev-pipeline-windows/templates/refactor-bootstrap-prompt.md +331 -0
  70. package/bundled/dev-pipeline-windows/templates/refactor-list-schema.json +270 -0
  71. package/bundled/dev-pipeline-windows/templates/sections/ac-verification-checklist.md +13 -0
  72. package/bundled/dev-pipeline-windows/templates/sections/checkpoint-system.md +91 -0
  73. package/bundled/dev-pipeline-windows/templates/sections/context-budget-rules.md +33 -0
  74. package/bundled/dev-pipeline-windows/templates/sections/critical-paths-agent.md +10 -0
  75. package/bundled/dev-pipeline-windows/templates/sections/critical-paths-full.md +12 -0
  76. package/bundled/dev-pipeline-windows/templates/sections/critical-paths-lite.md +7 -0
  77. package/bundled/dev-pipeline-windows/templates/sections/directory-convention-agent.md +8 -0
  78. package/bundled/dev-pipeline-windows/templates/sections/directory-convention-full.md +9 -0
  79. package/bundled/dev-pipeline-windows/templates/sections/directory-convention-lite.md +6 -0
  80. package/bundled/dev-pipeline-windows/templates/sections/failure-capture.md +21 -0
  81. package/bundled/dev-pipeline-windows/templates/sections/feature-context.md +31 -0
  82. package/bundled/dev-pipeline-windows/templates/sections/phase-browser-verification-auto.md +72 -0
  83. package/bundled/dev-pipeline-windows/templates/sections/phase-browser-verification-opencli.md +63 -0
  84. package/bundled/dev-pipeline-windows/templates/sections/phase-browser-verification.md +62 -0
  85. package/bundled/dev-pipeline-windows/templates/sections/phase-commit-full.md +71 -0
  86. package/bundled/dev-pipeline-windows/templates/sections/phase-commit.md +64 -0
  87. package/bundled/dev-pipeline-windows/templates/sections/phase-context-snapshot-agent-suffix.md +23 -0
  88. package/bundled/dev-pipeline-windows/templates/sections/phase-context-snapshot-base.md +24 -0
  89. package/bundled/dev-pipeline-windows/templates/sections/phase-context-snapshot-lite-suffix.md +12 -0
  90. package/bundled/dev-pipeline-windows/templates/sections/phase-critic-plan-full.md +53 -0
  91. package/bundled/dev-pipeline-windows/templates/sections/phase-critic-plan.md +32 -0
  92. package/bundled/dev-pipeline-windows/templates/sections/phase-implement-agent.md +37 -0
  93. package/bundled/dev-pipeline-windows/templates/sections/phase-implement-full.md +50 -0
  94. package/bundled/dev-pipeline-windows/templates/sections/phase-implement-lite.md +52 -0
  95. package/bundled/dev-pipeline-windows/templates/sections/phase-plan-agent.md +27 -0
  96. package/bundled/dev-pipeline-windows/templates/sections/phase-plan-lite.md +27 -0
  97. package/bundled/dev-pipeline-windows/templates/sections/phase-review-agent.md +27 -0
  98. package/bundled/dev-pipeline-windows/templates/sections/phase-review-full.md +29 -0
  99. package/bundled/dev-pipeline-windows/templates/sections/phase-specify-plan-full.md +77 -0
  100. package/bundled/dev-pipeline-windows/templates/sections/phase0-init.md +13 -0
  101. package/bundled/dev-pipeline-windows/templates/sections/phase0-test-baseline.md +23 -0
  102. package/bundled/dev-pipeline-windows/templates/sections/session-context.md +5 -0
  103. package/bundled/dev-pipeline-windows/templates/sections/subagent-timeout-recovery.md +6 -0
  104. package/bundled/dev-pipeline-windows/templates/sections/test-failure-recovery-agent.md +67 -0
  105. package/bundled/dev-pipeline-windows/templates/sections/test-failure-recovery-lite.md +58 -0
  106. package/bundled/dev-pipeline-windows/templates/session-status-schema.json +83 -0
  107. package/bundled/skills/_metadata.json +1 -1
  108. package/bundled/skills/app-planner/SKILL.md +26 -18
  109. package/bundled/skills/app-planner/references/architecture-decisions.md +9 -5
  110. package/bundled/skills/app-planner/references/frontend-design-guide.md +1 -1
  111. package/bundled/skills/feature-planner/SKILL.md +9 -2
  112. package/bundled/skills/prizmkit-init/SKILL.md +7 -6
  113. package/bundled/skills/recovery-workflow/scripts/detect-recovery-state.py +2 -0
  114. package/bundled/skills-windows/app-planner/SKILL.md +639 -0
  115. package/bundled/skills-windows/app-planner/assets/app-design-guide.md +101 -0
  116. package/bundled/skills-windows/app-planner/references/architecture-decisions.md +52 -0
  117. package/bundled/skills-windows/app-planner/references/brainstorm-guide.md +101 -0
  118. package/bundled/skills-windows/app-planner/references/frontend-design-guide.md +71 -0
  119. package/bundled/skills-windows/app-planner/references/project-brief-guide.md +82 -0
  120. package/bundled/skills-windows/app-planner/references/red-team-checklist.md +40 -0
  121. package/bundled/skills-windows/app-planner/references/rules/backend/derivation-rules.md +609 -0
  122. package/bundled/skills-windows/app-planner/references/rules/backend/fixed-rules.md +285 -0
  123. package/bundled/skills-windows/app-planner/references/rules/backend/question-bank.md +249 -0
  124. package/bundled/skills-windows/app-planner/references/rules/backend/template.md +173 -0
  125. package/bundled/skills-windows/app-planner/references/rules/database/derivation-rules.md +373 -0
  126. package/bundled/skills-windows/app-planner/references/rules/database/fixed-rules.md +211 -0
  127. package/bundled/skills-windows/app-planner/references/rules/database/question-bank.md +184 -0
  128. package/bundled/skills-windows/app-planner/references/rules/database/template.md +158 -0
  129. package/bundled/skills-windows/app-planner/references/rules/frontend/derivation-rules.md +810 -0
  130. package/bundled/skills-windows/app-planner/references/rules/frontend/fixed-rules.md +188 -0
  131. package/bundled/skills-windows/app-planner/references/rules/frontend/question-bank.md +302 -0
  132. package/bundled/skills-windows/app-planner/references/rules/frontend/template.md +320 -0
  133. package/bundled/skills-windows/app-planner/references/rules/mobile/derivation-rules.md +639 -0
  134. package/bundled/skills-windows/app-planner/references/rules/mobile/fixed-rules.md +290 -0
  135. package/bundled/skills-windows/app-planner/references/rules/mobile/question-bank.md +232 -0
  136. package/bundled/skills-windows/app-planner/references/rules/mobile/template.md +175 -0
  137. package/bundled/skills-windows/bug-fix-workflow/SKILL.md +415 -0
  138. package/bundled/skills-windows/bug-planner/SKILL.md +395 -0
  139. package/bundled/skills-windows/bug-planner/assets/bug-confirmation-template.md +43 -0
  140. package/bundled/skills-windows/bug-planner/references/critic-and-verification.md +44 -0
  141. package/bundled/skills-windows/bug-planner/references/error-recovery.md +73 -0
  142. package/bundled/skills-windows/bug-planner/references/input-formats.md +53 -0
  143. package/bundled/skills-windows/bug-planner/references/schema-validation.md +25 -0
  144. package/bundled/skills-windows/bug-planner/references/severity-rules.md +16 -0
  145. package/bundled/skills-windows/bug-planner/scripts/validate-bug-list.py +322 -0
  146. package/bundled/skills-windows/bugfix-pipeline-launcher/SKILL.md +380 -0
  147. package/bundled/skills-windows/feature-pipeline-launcher/SKILL.md +441 -0
  148. package/bundled/skills-windows/feature-pipeline-launcher/scripts/preflight-check.py +462 -0
  149. package/bundled/skills-windows/feature-planner/SKILL.md +401 -0
  150. package/bundled/skills-windows/feature-planner/assets/evaluation-guide.md +64 -0
  151. package/bundled/skills-windows/feature-planner/assets/planning-guide.md +214 -0
  152. package/bundled/skills-windows/feature-planner/references/browser-interaction.md +59 -0
  153. package/bundled/skills-windows/feature-planner/references/completeness-review.md +57 -0
  154. package/bundled/skills-windows/feature-planner/references/decomposition-patterns.md +75 -0
  155. package/bundled/skills-windows/feature-planner/references/error-recovery.md +90 -0
  156. package/bundled/skills-windows/feature-planner/references/incremental-feature-planning.md +112 -0
  157. package/bundled/skills-windows/feature-planner/references/new-project-planning.md +85 -0
  158. package/bundled/skills-windows/feature-planner/scripts/validate-and-generate.py +1029 -0
  159. package/bundled/skills-windows/feature-workflow/SKILL.md +531 -0
  160. package/bundled/skills-windows/prizmkit-init/SKILL.md +356 -0
  161. package/bundled/skills-windows/prizmkit-init/assets/project-brief-template.md +82 -0
  162. package/bundled/skills-windows/prizmkit-init/references/config-schema.md +68 -0
  163. package/bundled/skills-windows/prizmkit-init/references/rules/layer-detection.md +41 -0
  164. package/bundled/skills-windows/prizmkit-init/references/tech-stack-catalog.md +13 -0
  165. package/bundled/skills-windows/prizmkit-init/references/update-supplement.md +9 -0
  166. package/bundled/skills-windows/recovery-workflow/SKILL.md +456 -0
  167. package/bundled/skills-windows/recovery-workflow/evals/evals.json +46 -0
  168. package/bundled/skills-windows/recovery-workflow/scripts/detect-recovery-state.py +544 -0
  169. package/bundled/skills-windows/refactor-pipeline-launcher/SKILL.md +406 -0
  170. package/bundled/skills-windows/refactor-planner/SKILL.md +540 -0
  171. package/bundled/skills-windows/refactor-planner/assets/planning-guide.md +292 -0
  172. package/bundled/skills-windows/refactor-planner/references/behavior-preservation.md +301 -0
  173. package/bundled/skills-windows/refactor-planner/references/refactor-scoping-guide.md +221 -0
  174. package/bundled/skills-windows/refactor-planner/scripts/validate-and-generate-refactor.py +858 -0
  175. package/bundled/skills-windows/refactor-workflow/SKILL.md +503 -0
  176. package/package.json +3 -2
  177. package/src/clean.js +73 -2
  178. package/src/config.js +159 -50
  179. package/src/detect-platform.js +16 -8
  180. package/src/external-skills.js +26 -19
  181. package/src/index.js +31 -9
  182. package/src/manifest.js +6 -2
  183. package/src/metadata.js +43 -5
  184. package/src/platforms.js +36 -0
  185. package/src/prompts.js +31 -6
  186. package/src/runtimes.js +20 -0
  187. package/src/scaffold.js +314 -110
  188. package/src/upgrade.js +81 -41
@@ -0,0 +1,175 @@
1
+ # Mobile Rules — {{ project_name }}
2
+
3
+ > This document was generated by the `mobile-rules` skill on {{ generated_at }}
4
+ > Audience: All mobile developers + all AI coding assistants on this project
5
+ >
6
+ > **Usage**:
7
+ > 1. All AI coding assistants must read this file before generating or modifying any mobile code
8
+ > 2. This document takes precedence over "general best practices" in AI training data
9
+ > 3. Code conflicting with this document must not be committed
10
+
11
+ ---
12
+
13
+ ## 0. TL;DR — Key Decisions at a Glance
14
+
15
+ | Dimension | Decision |
16
+ |-----------|----------|
17
+ | Platform | {{ platform }} |
18
+ | Min OS Version | {{ min_os_version }} |
19
+ | Architecture Pattern | {{ architecture }} |
20
+ | UI Framework | {{ ui_framework }} |
21
+ | Navigation | {{ navigation }} |
22
+ | State Management | {{ state_management }} |
23
+ | Networking | {{ networking }} |
24
+ | Local Persistence | {{ persistence }} |
25
+ | Push Notifications | {{ push_notifications }} |
26
+ | Background Tasks | {{ background_tasks }} |
27
+ | Permissions Strategy | {{ permissions_strategy }} |
28
+ | Test Coverage | {{ test_coverage }} |
29
+ | Unit Test Framework | {{ unit_test_framework }} |
30
+ | E2E Test Framework | {{ e2e_framework }} |
31
+ | Distribution | {{ distribution }} |
32
+ | Performance Target | {{ performance_target }} |
33
+ | Accessibility Target | {{ a11y_target }} |
34
+
35
+ ---
36
+
37
+ ## 1. Project Structure
38
+
39
+ {{ FIXED_RULES_STRUCTURE }}
40
+
41
+ {{ tech_stack_rules }}
42
+
43
+ ---
44
+
45
+ ## 2. UI Development
46
+
47
+ {{ FIXED_RULES_UI }}
48
+
49
+ {{ ui_rules }}
50
+
51
+ ---
52
+
53
+ ## 3. Navigation & Deep Linking
54
+
55
+ {{ FIXED_RULES_NAVIGATION }}
56
+
57
+ {{ navigation_rules }}
58
+
59
+ ---
60
+
61
+ ## 4. State Management
62
+
63
+ {{ FIXED_RULES_STATE }}
64
+
65
+ {{ state_rules }}
66
+
67
+ ---
68
+
69
+ ## 5. Networking
70
+
71
+ {{ FIXED_RULES_NETWORKING }}
72
+
73
+ {{ networking_rules }}
74
+
75
+ ---
76
+
77
+ ## 6. Data Persistence
78
+
79
+ {{ FIXED_RULES_PERSISTENCE }}
80
+
81
+ {{ persistence_rules }}
82
+
83
+ ---
84
+
85
+ ## 7. Platform Features
86
+
87
+ {{ FIXED_RULES_PLATFORM_FEATURES }}
88
+
89
+ {{ platform_features_rules }}
90
+
91
+ ---
92
+
93
+ ## 8. Performance
94
+
95
+ {{ FIXED_RULES_PERFORMANCE }}
96
+
97
+ {{ performance_rules }}
98
+
99
+ ---
100
+
101
+ ## 9. Accessibility
102
+
103
+ {{ FIXED_RULES_A11Y }}
104
+
105
+ {{ a11y_rules }}
106
+
107
+ ---
108
+
109
+ ## 10. Security
110
+
111
+ {{ FIXED_RULES_SECURITY }}
112
+
113
+ ---
114
+
115
+ ## 11. Testing
116
+
117
+ {{ FIXED_RULES_TEST }}
118
+
119
+ {{ test_rules }}
120
+
121
+ ---
122
+
123
+ ## 12. App Distribution
124
+
125
+ {{ FIXED_RULES_DISTRIBUTION }}
126
+
127
+ {{ distribution_rules }}
128
+
129
+ ---
130
+
131
+ ## 13. AI Vibecoding Behavior Constraints
132
+
133
+ ### 13.1 Baseline Constraints (project-agnostic, always active)
134
+
135
+ {{ FIXED_RULES_AI_BASE }}
136
+
137
+ ### 13.2 Project-Specific Hard Constraints
138
+
139
+ - **Adding dependencies**: {{ ai_dependency_rule }}
140
+ - **Modifying shared code**: {{ ai_breaking_change_rule }}
141
+ - **Platform-specific code**: {{ ai_platform_rule }}
142
+
143
+ ### 13.3 Mandatory Pre-Actions (before every code generation)
144
+
145
+ AI must complete the following in order before generating or modifying any mobile code:
146
+
147
+ 1. Read this file (`mobile-rules.md`)
148
+ 2. Read existing files in the target feature's directory to confirm whether similar functionality already exists
149
+ 3. If modifying shared widgets/components/services, search all callers and assess platform impact
150
+ 4. If modifying navigation routes or deep link schemes, assess all entry points
151
+
152
+ ---
153
+
154
+ ## 14. Architecture
155
+
156
+ {{ arch_rules }}
157
+
158
+ ---
159
+
160
+ ## Appendix A: Deny List (Quick Reference)
161
+
162
+ > This appendix is auto-generated by AI in Phase 4 by extracting all forbidden entries from each section.
163
+
164
+ {{ deny_list_summary }}
165
+
166
+ ## Appendix B: Recommended Libraries & Tools
167
+
168
+ > This appendix is auto-generated by AI in Phase 4 to recommend the supporting ecosystem based on platform and framework choices.
169
+
170
+ {{ recommended_libs }}
171
+
172
+ ---
173
+
174
+ **Version**: v1.0 — Generated on {{ generated_at }}
175
+ **Next review recommended**: before tech stack changes or platform migration
@@ -0,0 +1,415 @@
1
+ ---
2
+ name: "bug-fix-workflow"
3
+ description: "Interactive single-bug fix in current session. Guides through deep diagnosis Q&A → triage → reproduce → fix → review → commit without the background pipeline. Use this skill when the user wants to fix one specific bug right now, interactively. Trigger on: 'fix this bug', 'debug this', 'fix B-001', 'help me fix', 'let me fix this bug myself', 'fix this bug', 'interactive fix', 'manually fix bug'."
4
+ ---
5
+
6
+ # Bug Fix Workflow
7
+
8
+ Fix a single bug interactively within the current AI CLI session. This is the in-session counterpart to `bugfix-pipeline-launcher` (which runs multiple bugs in the background).
9
+
10
+ ## When to Use
11
+
12
+ - User wants to fix **one specific bug** right now, with full visibility
13
+ - User says "fix this bug", "debug this error", "help me fix B-001", "fix this bug"
14
+ - User has a stack trace or error and wants interactive debugging
15
+ - User prefers hands-on fixing over background pipeline
16
+
17
+ **Do NOT use when:**
18
+ - User has multiple bugs to fix in batch → `bug-planner` + `bugfix-pipeline-launcher`
19
+ - User wants to plan/collect bugs without fixing → `bug-planner`
20
+ - User wants background autonomous fixing → `bugfix-pipeline-launcher`
21
+ - User wants to build features → `feature-workflow`
22
+
23
+ ## Input
24
+
25
+ **PRECONDITION:**
26
+
27
+ | Input Source | Detection | Example |
28
+ |---|---|---|
29
+ | Bug-fix-list.json entry | User says "fix B-001" → read entry from `.prizmkit/plans/bug-fix-list.json` | `fix B-001` |
30
+ | Stack trace / error message | User pastes error directly | `TypeError: Cannot read property...` |
31
+ | Natural language description | User describes the problem | "login page crashes on submit" |
32
+ | Failed test | User references a failing test file | `src/auth/__tests__/login.test.ts` |
33
+
34
+ At least one input source must be provided. If none is clear, ask the user to describe the bug.
35
+
36
+ ## Fast Path
37
+
38
+ For trivial bugs with clear root cause and minimal scope:
39
+
40
+ ### Eligibility Criteria (ALL must be true)
41
+ - Root cause is immediately obvious (typo, missing null check, wrong variable name, off-by-one)
42
+ - Fix is ≤10 lines of code in a single file
43
+ - No cross-module impact
44
+ - Existing tests cover the affected path (or bug is in untested utility)
45
+ - No data model or API changes
46
+
47
+ ### Fast Path Workflow
48
+ 1. Branch Setup → `fix/<BUG_ID>-<short-desc>`
49
+ 2. Write reproduction test → confirm failing
50
+ 3. Apply fix → confirm test passes + full suite green
51
+ 4. Run `/prizmkit-code-review` for quality check
52
+ 5. Ask user: "Quick fix applied. Verify before commit? (Y/skip)"
53
+ 6. Commit with `fix(<scope>):` prefix
54
+ 7. Ask merge preference
55
+
56
+ **Fast Path still requires**: fix branch, reproduction test, full test suite pass, code review, user merge decision.
57
+
58
+ ---
59
+
60
+ ## Execution
61
+
62
+ ### Phase 0: Branch Setup
63
+
64
+ **Goal**: Create an isolated working branch to keep main clean.
65
+
66
+ 1. **Check current branch**:
67
+ ```powershell
68
+ git branch --show-current
69
+ ```
70
+ 2. **If on `main` or a shared branch**: Create and switch to fix branch:
71
+ ```powershell
72
+ git checkout -b fix/<BUG_ID>-<short-description>
73
+ ```
74
+ Example: `git checkout -b fix/B-001-login-null-crash`
75
+ 3. **If already on a fix branch**: Confirm with user: "Continue on current branch `<branch-name>`, or create a new one?"
76
+ 4. **Record the original branch name** for later merge.
77
+
78
+ **CHECKPOINT CP-BFW-0**: On a dedicated fix branch, not main/shared branch.
79
+
80
+ ---
81
+
82
+ ### Phase 1: Deep Bug Diagnosis — Interactive Q&A
83
+
84
+ **Goal**: Fully understand the bug before touching any code. Vague bug reports lead to incorrect fixes that mask the real issue or introduce new bugs.
85
+
86
+ **Fast Path Decision Point**: After initial information gathering (Step 1.1), evaluate the Fast Path Eligibility Criteria in Step 1.4. If ALL simple bug criteria are met, use `AskUserQuestion` to let the user choose the execution approach. Only proceed with fast path implementation if the user explicitly selects "Fix now". Never guess the user's intent from text — always present the interactive selection.
87
+
88
+ **CRITICAL RULE**: Ask as many questions as needed until the bug is fully understood. Do NOT rush into code. A misdiagnosed bug leads to a wrong fix, which is worse than no fix.
89
+
90
+ #### Step 1.1: Initial Bug Information Gathering
91
+
92
+ - If bug ID given (e.g. B-001): read entry from `.prizmkit/plans/bug-fix-list.json` — but DO NOT assume the description is complete
93
+ - If raw error/stack trace: extract error message, affected files, line numbers
94
+ - If natural language description: start the deep-dive Q&A below
95
+
96
+ #### Step 1.2: Systematic Bug Clarification
97
+
98
+ Ask questions across these dimensions until every aspect is clear. **Adapt to what the user has already provided** — skip questions that are already answered.
99
+
100
+ **Reproduction Conditions:**
101
+ - What exact steps trigger the bug? (step-by-step)
102
+ - Which environment/browser/OS/version?
103
+ - Is it reproducible every time, or intermittent?
104
+ - When did it first appear? (after a specific change/deploy?)
105
+ - Does it happen for all users or only specific accounts/roles/data?
106
+
107
+ **Expected vs Actual Behavior:**
108
+ - What should happen? (the correct behavior)
109
+ - What actually happens? (the buggy behavior)
110
+ - Is there partial functionality (e.g., works for some inputs but not others)?
111
+
112
+ **Scope and Impact:**
113
+ - Which features/pages/modules are affected?
114
+ - Are there workarounds users are currently using?
115
+ - Is this blocking other work?
116
+ - Are there related symptoms elsewhere?
117
+
118
+ **Data and State:**
119
+ - What data/state triggers the issue? (specific input values, DB state, user session state)
120
+ - Does the bug involve data corruption or just incorrect display/behavior?
121
+ - If database-related: which tables/records are affected?
122
+
123
+ **Error Details** (if not already provided):
124
+ - Full error message and stack trace?
125
+ - Browser console errors?
126
+ - Server-side logs?
127
+ - Network request/response details?
128
+
129
+ #### Step 1.3: Confirmation Before Triage
130
+
131
+ Summarize the bug understanding:
132
+
133
+ ```
134
+ Bug Summary:
135
+ - Symptom: [what happens]
136
+ - Reproduction: [exact steps]
137
+ - Environment: [where it occurs]
138
+ - Expected: [correct behavior]
139
+ - Impact: [who/what is affected]
140
+ - Data trigger: [what data/state causes it]
141
+ ```
142
+
143
+ Ask the user: "Is this summary accurate? Any details to add?"
144
+
145
+ **CHECKPOINT CP-BFW-1**: Bug fully understood and confirmed by user.
146
+
147
+ ---
148
+
149
+ #### Step 1.4: Complexity Assessment
150
+
151
+ After confirming bug understanding, assess whether this bug needs structured planning:
152
+
153
+ **Simple bug → Fast Path candidate** (ALL must be true):
154
+ - Root cause is immediately obvious (typo, missing null check, wrong variable name, off-by-one)
155
+ - Fix is ≤10 lines of code in a single file
156
+ - No cross-module impact
157
+ - Existing tests cover the affected path (or bug is in untested utility)
158
+ - No data model or API changes
159
+
160
+ **User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
161
+
162
+ ```
163
+ AskUserQuestion:
164
+ question: "This bug appears straightforward. How would you like to proceed?"
165
+ header: "Approach"
166
+ options:
167
+ - label: "Fix now (fast path)"
168
+ description: "Implement the fix directly in this session — branch → test → fix → review → commit"
169
+ - label: "Add to bug-fix-list.json (pipeline)"
170
+ description: "Add this bug to .prizmkit/plans/bug-fix-list.json via bug-planner, then use bugfix-pipeline-launcher to launch autonomous pipeline execution"
171
+ - label: "Full diagnosis"
172
+ description: "Continue with in-depth analysis before deciding"
173
+ ```
174
+
175
+ - **Fix now** → Proceed with Fast Path Workflow (Phase 0 branch already set up)
176
+ - **Add to bug-fix-list.json** → Invoke `bug-planner` to add this bug to `.prizmkit/plans/bug-fix-list.json`, then suggest user run `bugfix-pipeline-launcher` to start the pipeline. End this workflow.
177
+ - **Full diagnosis** → Continue with full diagnosis (Phase 2 Triage)
178
+
179
+ **Complex bug → Planning Path** (ANY is true):
180
+ - Cross-module impact (>2 files affected)
181
+ - Data model or API changes required
182
+ - Root cause is uncertain or multi-layered
183
+ - Fix requires structural changes
184
+ - Multiple interrelated symptoms
185
+
186
+ **User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
187
+
188
+ ```
189
+ AskUserQuestion:
190
+ question: "This bug appears complex and will need structured planning. How would you like to proceed?"
191
+ header: "Approach"
192
+ options:
193
+ - label: "Plan and fix now"
194
+ description: "Create a plan and fix it in this session using /prizmkit-plan + /prizmkit-implement"
195
+ - label: "Add to bug-fix-list.json (pipeline)"
196
+ description: "Add this bug to .prizmkit/plans/bug-fix-list.json via bug-planner, then use bugfix-pipeline-launcher to launch autonomous pipeline execution"
197
+ ```
198
+
199
+ - **Plan and fix now** → Invoke `/prizmkit-plan` with `artifact_dir=.prizmkit/bugfix/<BUG_ID>/`:
200
+ 1. `/prizmkit-plan` generates `spec.md` (bug description + acceptance criteria) + `plan.md` (fix strategy + test specifications) under `.prizmkit/bugfix/<BUG_ID>/`
201
+ 2. Invoke `/prizmkit-implement` to execute the plan (TDD: write failing reproduction test → implement fix → tests pass)
202
+ 3. Run `/prizmkit-code-review` for quality check
203
+ 4. Commit via `/prizmkit-committer` with `fix(<scope>):` prefix
204
+ 5. **End workflow** — skip Phase 2-7. No `/prizmkit-retrospective` (bug fixes are incomplete features, not new architecture)
205
+ - **Add to bug-fix-list.json** → Invoke `bug-planner` to add this bug to `.prizmkit/plans/bug-fix-list.json`, then suggest user run `bugfix-pipeline-launcher` to start the pipeline. End this workflow.
206
+
207
+ **NEVER proceed with direct code changes without explicit user confirmation via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
208
+
209
+ ---
210
+
211
+ ### Phase 2: Triage
212
+
213
+ **Goal**: Locate affected code, identify root cause, classify severity.
214
+
215
+ > **Triage**: Classify error into: Runtime / Network / Auth / Data / Resource / Logic / Config / External. Check `.prizmkit/prizm-docs/` TRAPS for known patterns first. If a TRAPS match is found, use documented solution and reference the specific `.prizmkit/prizm-docs/` entry. If no match, trace the call chain from the stack frame to identify root cause from first principles.
216
+
217
+ 1. **Read project context**: `.prizmkit/prizm-docs/root.prizm` → relevant L1/L2 docs for affected modules
218
+ 2. **Locate affected code**: read the files mentioned in the error/stack trace or identified during diagnosis
219
+ 3. **Check known issues**: search `.prizmkit/prizm-docs/` TRAPS sections for matching patterns
220
+ 4. **If database-related**: read existing schema/model files to understand the data layer
221
+ ```powershell
222
+ Get-ChildItem -Path . -File -Recurse -Depth 4 -Include *.prisma,*.sql,schema.*,*.entity.* -ErrorAction SilentlyContinue |
223
+ Where-Object { $_.FullName -match '\\(migrations|models)\\|schema\.|\.prisma$|\.sql$|\.entity\.' } |
224
+ Where-Object { $_.FullName -notmatch '\\(node_modules|\.git)(\\|$)' } |
225
+ Select-Object -First 20 -ExpandProperty FullName
226
+ ```
227
+ 5. **Classify**: root cause (confirmed/suspected), blast radius, fix complexity
228
+ 6. **Present diagnosis to user**:
229
+ ```
230
+ Bug: Login page crash on submit
231
+ Root Cause: AuthService.handleLogin() receives null token when API returns 401
232
+ Affected Files: src/services/auth.ts (L42), src/pages/login.tsx (L28)
233
+ Fix Complexity: Low (null check + error handling)
234
+ ```
235
+ Ask: "Does this diagnosis look right? Should I proceed with the fix?"
236
+
237
+ **CHECKPOINT CP-BFW-2**: Root cause identified and diagnosis confirmed by user.
238
+
239
+ ### Phase 3: Reproduce
240
+
241
+ **Goal**: Create a failing test that proves the bug exists.
242
+
243
+ > **Reproduce**: For API bugs: generate curl/HTTP request sequence with assertions. For UI bugs: generate step-by-step interaction guide. For logic bugs: generate unit test (arrange/act/assert). For data bugs: generate seed data + query sequence. The reproduction must FAIL with current behavior and be designed to PASS after the fix is applied — making it a regression guard.
244
+
245
+ 1. **Write a reproduction test** that demonstrates the bug:
246
+ - Name: `<module>.test.ts` → add a test case named `should handle <bug scenario>`
247
+ - The test captures the exact failure condition
248
+ 2. **Run the test** → confirm it **fails** (red)
249
+ 3. **Show result to user**: "Reproduction test written and confirmed failing."
250
+
251
+ If the bug is hard to reproduce automatically (e.g. environment-specific):
252
+ - Ask the user for reproduction steps
253
+ - Write a manual reproduction checklist instead
254
+ - Proceed to Phase 4 with the manual checklist
255
+
256
+ **CHECKPOINT CP-BFW-3**: Bug reproduction test written and confirmed failing.
257
+
258
+ ### Phase 4: Fix
259
+
260
+ **Goal**: Implement the minimal fix. Red test → green.
261
+
262
+ 1. **Implement the fix**:
263
+ - Change the minimum amount of code to fix the root cause
264
+ - Do NOT refactor or add unrelated improvements — fix the bug only
265
+ - Follow existing code conventions (read from `.prizmkit/prizm-docs/` RULES/PATTERNS)
266
+ - If the fix involves database changes: read existing schema first, follow existing naming/constraint conventions
267
+ 2. **Run the reproduction test** → must **pass** (green)
268
+ 3. **Run the full module test suite** → must pass (no regressions)
269
+ 4. **Show the fix to user**:
270
+ - Summary of changes made
271
+ - Test results (reproduction + regression)
272
+ - Ask: "Fix looks good? Any concerns?"
273
+
274
+ **CHECKPOINT CP-BFW-4**: Fix implemented and all tests passing (reproduction + regression).
275
+
276
+ If the fix causes test regressions:
277
+ - Show which tests broke and why
278
+ - Revise the fix (max 3 attempts)
279
+ - If still failing after 3 attempts, escalate to user with analysis
280
+
281
+ ### Phase 5: Review
282
+
283
+ **Goal**: Verify fix quality before committing.
284
+
285
+ 1. **Run `/prizmkit-code-review`** to review the fix:
286
+ - Reviews git diff against the bug context (root cause, fix approach, affected areas)
287
+ - Iterative Reviewer Agent + Dev Agent loop (max 3 rounds)
288
+ - Checks: root cause addressed (not just symptom), edge cases covered, reproduction test thoroughness, project conventions
289
+ 2. **If PASS**: Proceed to Phase 6
290
+ 3. **If NEEDS_FIXES after max rounds**: Present unresolved findings to user, ask whether to proceed or revise
291
+
292
+ **CHECKPOINT CP-BFW-5**: Code review completed and quality verified.
293
+
294
+ ### Phase 6: User Verification
295
+
296
+ **Goal**: Let the user verify the fix works as expected before committing.
297
+
298
+ 1. **Ask user**: "Fix passes all tests. Would you like to verify before committing?"
299
+ - **(a) Run the app** — Start the dev server so you can manually test the fix scenario
300
+ - **(b) Run a specific command** — Specify a test or script to run
301
+ - **(c) Skip verification** — Proceed directly to commit (automated tests already pass)
302
+ 2. **If (a)**: Detect and suggest dev server command (e.g. `npm run dev`, `python manage.py runserver`), start it, wait for user confirmation: "Fix verified? (yes/no)"
303
+ 3. **If (b)**: Run the specified command, show results, ask confirmation
304
+ 4. **If (c)**: Proceed to Phase 7
305
+
306
+ If user reports the fix is NOT working:
307
+ - Return to Phase 4 (max 2 more attempts)
308
+ - If still failing: escalate with analysis
309
+
310
+ **CHECKPOINT CP-BFW-6**: Fix manually verified by user and working as expected.
311
+
312
+ ---
313
+
314
+ ### Phase 7: Commit & Merge
315
+
316
+ **Goal**: Commit the fix and offer to merge back to the original branch.
317
+
318
+ 1. **Run `/prizmkit-committer`**:
319
+ - Commit message: `fix(<scope>): <description>`
320
+ - Include both fix code and reproduction test
321
+ - Do NOT push (user decides when to push)
322
+ - `/prizmkit-committer` is a pure commit tool — it does NOT modify `.prizmkit/prizm-docs/` or any project files
323
+ - No `/prizmkit-retrospective` — bug fixes are incomplete features, not new architecture worth documenting
324
+ 2. **Ask merge preference**:
325
+ ```
326
+ Fix committed on branch `fix/<BUG_ID>-<short-desc>`.
327
+ What would you like to do?
328
+ (a) Merge to <original-branch> and delete fix branch
329
+ (b) Keep fix branch (for PR review workflow)
330
+ (c) Decide later
331
+ ```
332
+ 3. **If (a)**:
333
+ ```powershell
334
+ git checkout <original-branch>
335
+ git merge fix/<BUG_ID>-<short-description>
336
+ git branch -d fix/<BUG_ID>-<short-description>
337
+ ```
338
+ 4. **If (b)**: Inform user: "Branch `fix/<BUG_ID>-<short-desc>` retained. Create a PR when ready."
339
+ 5. **If bug came from .prizmkit/plans/bug-fix-list.json**: inform user to update bug status
340
+ ```
341
+ Bug B-001 fixed and committed.
342
+ To update the bug list: manually set B-001 status to "fixed" in .prizmkit/plans/bug-fix-list.json
343
+ Or retry the pipeline to pick up remaining bugs.
344
+ ```
345
+
346
+ **CHECKPOINT CP-BFW-7**: Fix committed and merge decision made.
347
+
348
+ ## Resume — Interruption Recovery
349
+
350
+ The workflow supports resuming from the last completed phase by detecting existing artifacts.
351
+
352
+ **Detection logic**: Check `.prizmkit/bugfix/<BUG_ID>/` and git branch state:
353
+
354
+ | Artifact Found | Resume From |
355
+ |---------------|------------|
356
+ | (nothing) | Phase 0: Branch Setup |
357
+ | On `fix/<BUG_ID>-*` branch, no artifacts | Phase 1: Deep Bug Diagnosis |
358
+ | `fix-plan.md` only | Phase 4: Fix |
359
+ | `fix-plan.md` + code changes exist | Phase 5: Review |
360
+ | All docs + review passed | Phase 6: User Verification |
361
+ | All docs + committed | Phase 7: Merge decision |
362
+
363
+ **Resume**: If `<BUG_ID>` matches an existing `.prizmkit/bugfix/<BUG_ID>/` directory, resume instead of starting fresh.
364
+
365
+ ---
366
+
367
+ ## Artifacts
368
+
369
+ Bug fix artifacts are stored at `.prizmkit/bugfix/<BUG_ID>/`:
370
+ - `fix-plan.md` — Triage output (diagnosis, root cause, fix approach)
371
+ - `fix-report.md` — Post-fix summary (what changed, test results, TRAPS added)
372
+
373
+ Only 2 artifact files per bug, consistent with the pipeline convention.
374
+
375
+ ## Comparison with Pipeline Bug Fix
376
+
377
+ | Dimension | bug-fix-workflow (this skill) | bugfix-pipeline-launcher |
378
+ |-----------|-------------------------------|-----------------------------|
379
+ | Scope | One bug at a time | All bugs in batch |
380
+ | Execution | Interactive, in-session | Foreground or background daemon |
381
+ | Diagnosis | Deep interactive Q&A with user | Automated from bug description |
382
+ | Branch | Creates `fix/<BUG_ID>-*` branch | Pipeline manages branches |
383
+ | Visibility | Full user interaction at each phase | Async, check status periodically |
384
+ | User verification | Yes (Phase 6) | No (automated) |
385
+ | Best for | Complex bugs needing user input | Batch of well-defined bugs |
386
+ | Artifacts | Same (fix-plan.md + fix-report.md) | Same |
387
+ | Commit prefix | `fix(<scope>):` | `fix(<scope>):` |
388
+
389
+ ## Error Handling
390
+
391
+ | Scenario | Action |
392
+ |----------|--------|
393
+ | Bug ID not found in .prizmkit/plans/bug-fix-list.json | Ask user to provide bug details directly |
394
+ | User's bug description is too vague | Ask systematic clarification questions (Phase 1) |
395
+ | Cannot reproduce the bug | Ask for more context, try alternative reproduction |
396
+ | Fix causes regressions | Revert, analyze, retry (max 3 rounds) |
397
+ | Root cause unclear after investigation | Present findings, ask user for guidance |
398
+ | Affected files are in unfamiliar module | Read `.prizmkit/prizm-docs/` L1/L2 for that module first |
399
+ | Branch conflict during merge | Show conflict, ask user to resolve or keep branch |
400
+
401
+ ## HANDOFF
402
+
403
+ | From | To | Condition |
404
+ |------|----|-----------|
405
+ | `bug-planner` | **this skill** | User picks one bug to fix interactively |
406
+ | `bugfix-pipeline-launcher` | **this skill** | User wants to fix a stuck/complex bug manually |
407
+ | **this skill** | `bugfix-pipeline-launcher` | After fixing, user wants to continue with remaining bugs |
408
+ | **this skill** | `prizmkit-committer` | Built into Phase 7 (pure commit, no doc sync) |
409
+
410
+ ## Output
411
+
412
+ - Fixed code with reproduction test
413
+ - `.prizmkit/bugfix/<BUG_ID>/fix-plan.md`
414
+ - `.prizmkit/bugfix/<BUG_ID>/fix-report.md`
415
+ - Git commit with `fix(<scope>):` prefix on dedicated fix branch