heimdall-agent 1.0.0 → 1.1.0

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 (231) hide show
  1. package/README.md +57 -26
  2. package/README.pt-BR.md +429 -0
  3. package/agents/cloud-engineer.md +77 -0
  4. package/agents/code-sentinel.md +66 -35
  5. package/agents/database-architect.md +31 -25
  6. package/agents/frontend-designer.md +30 -28
  7. package/agents/mobile-designer.md +25 -24
  8. package/agents/modernizer.md +66 -0
  9. package/agents/orchestrator.md +94 -93
  10. package/agents/reviewer.md +100 -71
  11. package/agents/security-auditor.md +27 -27
  12. package/agents/tester.md +97 -90
  13. package/commands/grill-me.md +20 -4
  14. package/commands/orchestrate.md +16 -0
  15. package/commands/orchestrator.md +16 -0
  16. package/commands/plan.md +17 -1
  17. package/config/agents.json +21 -3
  18. package/config/mcp.json +72 -0
  19. package/config/models.json +26 -16
  20. package/config/profiles.json +2 -4
  21. package/config/skills.json +210 -100
  22. package/docs/SKILLS.md +341 -245
  23. package/docs/designs/old/2026-10-31 plan-lifecycle-backlog-and-clean-code-skill.md +87 -0
  24. package/docs/designs/old/2026-11-02 skill-upstream-audit-and-update.md +105 -0
  25. package/docs/designs/old/2026-11-05 communication-doctrine-bluf-ste.md +94 -0
  26. package/docs/designs/old/2026-11-06-cloud-engineer-and-resilience-synthesis.md +67 -0
  27. package/docs/designs/old/2026-11-06-herdr-native-agent-orchestration.md +45 -0
  28. package/docs/runs/skill-audit/add_progressive_disclosure.cjs +30 -0
  29. package/docs/runs/skill-audit/check_heimdall_skills.ps1 +9 -0
  30. package/docs/runs/skill-audit/compare_classics.ps1 +26 -0
  31. package/docs/runs/skill-audit/compare_taste.ps1 +12 -0
  32. package/docs/runs/skill-audit/customization-report.json +380 -0
  33. package/docs/runs/skill-audit/diff_pending_skills.cjs +94 -0
  34. package/docs/runs/skill-audit/fetch_and_apply_skill.cjs +58 -0
  35. package/docs/runs/skill-audit/fetch_and_apply_taste_v2.cjs +65 -0
  36. package/docs/runs/skill-audit/inspect_pending_skills.cjs +71 -0
  37. package/docs/runs/skill-audit/inventory.json +308 -0
  38. package/docs/runs/skill-audit/list_local_taste.ps1 +1 -0
  39. package/docs/runs/skill-audit/phase5-update-plan.json +595 -0
  40. package/docs/runs/skill-audit/phase5-update-plan.md +138 -0
  41. package/docs/runs/skill-audit/probe.ps1 +16 -0
  42. package/docs/runs/skill-audit/probe_classics_branches.ps1 +3 -0
  43. package/docs/runs/skill-audit/probe_commits.ps1 +15 -0
  44. package/docs/runs/skill-audit/probe_repos.ps1 +17 -0
  45. package/docs/runs/skill-audit/probe_sentry_sec.ps1 +3 -0
  46. package/docs/runs/skill-audit/probe_sentry_sweep.ps1 +5 -0
  47. package/docs/runs/skill-audit/probe_snyk.ps1 +3 -0
  48. package/docs/runs/skill-audit/probe_snyk_recipes.ps1 +5 -0
  49. package/docs/runs/skill-audit/probe_taste_branches.ps1 +8 -0
  50. package/docs/runs/skill-audit/probe_taste_v19.ps1 +3 -0
  51. package/docs/runs/skill-audit/probe_user_repos.ps1 +19 -0
  52. package/docs/runs/skill-audit/prune_taste_skills.cjs +22 -0
  53. package/docs/runs/skill-audit/run_phase1_2.cjs +142 -0
  54. package/docs/runs/skill-audit/run_phase6_verification.cjs +107 -0
  55. package/docs/runs/skill-audit/show_16_details.ps1 +25 -0
  56. package/docs/runs/skill-audit/show_20_skills.ps1 +28 -0
  57. package/docs/runs/skill-audit/show_classics_diff.cjs +37 -0
  58. package/docs/runs/skill-audit/sync_agent_markdowns.cjs +30 -0
  59. package/docs/runs/skill-audit/taste-skill-upstream.md +542 -0
  60. package/docs/runs/skill-audit/update-manifest.md +88 -0
  61. package/docs/runs/skill-audit/update_config_skills.cjs +52 -0
  62. package/docs/runs/skill-audit/update_registry_phase7.cjs +83 -0
  63. package/docs/runs/skill-audit/upstream-status.json +563 -0
  64. package/docs/runs/skill-audit/verification-results.json +252 -0
  65. package/doctrine/AGENTS.md +39 -77
  66. package/hooks/git/pre-commit +11 -0
  67. package/hooks/heimdall-hook.cjs +81 -2
  68. package/hooks/herdr-agent-state.ps1 +55 -0
  69. package/hooks/hooks.json +0 -11
  70. package/lib/catalog-sync.cjs +162 -0
  71. package/lib/hermes-context.cjs +57 -0
  72. package/lib/model-context.cjs +123 -0
  73. package/lib/path-discovery.cjs +94 -0
  74. package/package.json +7 -3
  75. package/playbooks/01-interactive-grilling-gate.md +14 -1
  76. package/playbooks/02-fast-code-deep-verification.md +3 -2
  77. package/playbooks/03-adversarial-code-review.md +3 -3
  78. package/playbooks/05-canonical-plan-template.md +32 -18
  79. package/playbooks/06-model-registry-matrix.md +24 -13
  80. package/playbooks/07-legacy-code-modernization.md +74 -0
  81. package/playbooks/08-backlog-and-change-request-flow.md +122 -0
  82. package/setup.mjs +592 -172
  83. package/skills/antislop/SKILL.md +76 -56
  84. package/skills/antislop/VERSION +1 -0
  85. package/skills/antislop-copywriting/SKILL.md +372 -372
  86. package/skills/antislop-human/LICENSE-web-quality-skills +21 -0
  87. package/skills/antislop-human/SKILL.md +204 -147
  88. package/skills/antislop-human/contrast-check.py +168 -165
  89. package/skills/antislop-human/contrast-mcp.py +6 -3
  90. package/skills/antislop-human/references/A11Y-PATTERNS.md +249 -0
  91. package/skills/antislop-human/references/WCAG.md +127 -0
  92. package/skills/antislop-ui/LICENSE-web-quality-skills +21 -0
  93. package/skills/antislop-ui/SKILL.md +344 -304
  94. package/skills/antislop-ui/references/CORE-WEB-VITALS.md +181 -0
  95. package/skills/antislop-ui/references/WEB-BASELINE.md +28 -0
  96. package/skills/brainstorming/SKILL.md +274 -265
  97. package/skills/brainstorming/builder-check-prompt.md +23 -0
  98. package/skills/brainstorming/scripts/frame-template.html +213 -213
  99. package/skills/brainstorming/scripts/server.cjs +723 -723
  100. package/skills/brandkit/SKILL.md +798 -798
  101. package/skills/brutalist-skill/SKILL.md +93 -92
  102. package/skills/caveman/README.md +68 -0
  103. package/skills/caveman/SKILL.md +73 -38
  104. package/skills/claude-collaborator/SKILL.md +24 -44
  105. package/skills/clean-code/SKILL.md +152 -0
  106. package/skills/cloudflare-security-audit/AI-AND-LLM.md +83 -83
  107. package/skills/cloudflare-security-audit/ATTACK-CLASSES.md +130 -130
  108. package/skills/cloudflare-security-audit/CLIENT-SIDE.md +83 -83
  109. package/skills/cloudflare-security-audit/CLOUD-AND-DEPLOYMENT.md +86 -86
  110. package/skills/cloudflare-security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -84
  111. package/skills/cloudflare-security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -89
  112. package/skills/cloudflare-security-audit/HUNTING.md +251 -251
  113. package/skills/cloudflare-security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -101
  114. package/skills/cloudflare-security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -81
  115. package/skills/cloudflare-security-audit/RECONNAISSANCE.md +156 -156
  116. package/skills/cloudflare-security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -78
  117. package/skills/cloudflare-security-audit/SKILL.md +192 -192
  118. package/skills/cloudflare-security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -73
  119. package/skills/cloudflare-security-audit/VALIDATION-AND-REPORTING.md +186 -186
  120. package/skills/cloudflare-security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -105
  121. package/skills/cloudflare-security-audit/report-schema.json +461 -461
  122. package/skills/cloudflare-security-audit/validate-coverage-ledger.cjs +872 -872
  123. package/skills/cloudflare-security-audit/validate-coverage-ledger.test.cjs +740 -740
  124. package/skills/cloudflare-security-audit/validate-findings.cjs +773 -773
  125. package/skills/cloudflare-security-audit/validate-findings.test.cjs +652 -652
  126. package/skills/codex-collaborator/SKILL.md +24 -45
  127. package/skills/communication-doctrine/SKILL.md +89 -0
  128. package/skills/diagnosing-superpowers/SKILL.md +1 -1
  129. package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
  130. package/skills/diagnosing-superpowers/templates/issue.md +23 -4
  131. package/skills/executing-plans/SKILL.md +0 -52
  132. package/skills/executing-plans/scripts/task-done +52 -52
  133. package/skills/executing-plans/scripts/task-start +28 -28
  134. package/skills/gemini-collaborator/SKILL.md +24 -56
  135. package/skills/herdr/SKILL.md +243 -0
  136. package/skills/image-to-code-skill/SKILL.md +1228 -1228
  137. package/skills/imagegen-frontend-mobile/SKILL.md +1465 -1465
  138. package/skills/imagegen-frontend-web/SKILL.md +987 -987
  139. package/skills/karpathy-guidelines/SKILL.md +67 -67
  140. package/skills/mcp-engineering/SKILL.md +74 -0
  141. package/skills/minimalist-skill/SKILL.md +87 -85
  142. package/skills/output-skill/SKILL.md +49 -49
  143. package/skills/ponytail/SKILL.md +36 -52
  144. package/skills/postgres-best-practices/SKILL.md +30 -52
  145. package/skills/postgres-best-practices/references/backup-restore.md +372 -0
  146. package/skills/postgres-best-practices/references/bulk-loading.md +315 -0
  147. package/skills/postgres-best-practices/references/connection-pooling.md +310 -0
  148. package/skills/postgres-best-practices/references/hot-standby.md +221 -0
  149. package/skills/postgres-best-practices/references/indexing.md +318 -0
  150. package/skills/postgres-best-practices/references/logical-replication.md +610 -0
  151. package/skills/postgres-best-practices/references/major-version-upgrades.md +334 -0
  152. package/skills/postgres-best-practices/references/performance-diagnostics.md +553 -0
  153. package/skills/postgres-best-practices/references/query-optimization.md +294 -0
  154. package/skills/postgres-best-practices/references/query-patterns.md +566 -0
  155. package/skills/postgres-best-practices/references/schema-design.md +362 -0
  156. package/skills/postgres-best-practices/references/security-roles.md +489 -0
  157. package/skills/postgres-best-practices/references/transaction-isolation.md +344 -0
  158. package/skills/progressive-disclosure/SKILL.md +68 -0
  159. package/skills/pstack-discipline/SKILL.md +40 -0
  160. package/skills/receiving-code-review/SKILL.md +2 -23
  161. package/skills/requesting-code-review/SKILL.md +7 -36
  162. package/skills/soft-skill/SKILL.md +99 -98
  163. package/skills/stitch-skill/DESIGN.md +121 -121
  164. package/skills/stitch-skill/SKILL.md +185 -184
  165. package/skills/strix-security/SKILL.md +54 -53
  166. package/skills/subagent-driven-development/SKILL.md +28 -260
  167. package/skills/subagent-driven-development/references/batching.md +11 -0
  168. package/skills/subagent-driven-development/references/cannot-verify.md +10 -0
  169. package/skills/subagent-driven-development/references/final-review.md +47 -0
  170. package/skills/subagent-driven-development/references/fix-loop.md +77 -0
  171. package/skills/subagent-driven-development/references/handling-reports.md +15 -0
  172. package/skills/subagent-driven-development/references/preflight.md +26 -0
  173. package/skills/subagent-driven-development/references/resuming.md +12 -0
  174. package/skills/subagent-driven-development/scripts/review-package +53 -53
  175. package/skills/subagent-driven-development/scripts/sdd-workspace +87 -82
  176. package/skills/subagent-driven-development/scripts/task-brief +43 -43
  177. package/skills/systematic-debugging/SKILL.md +283 -306
  178. package/skills/taste-skill/SKILL.md +542 -1206
  179. package/skills/taste-skill/references/app-screens.md +1199 -0
  180. package/skills/taste-skill/references/colour.md +141 -0
  181. package/skills/taste-skill/references/copy.md +177 -0
  182. package/skills/taste-skill/references/critique.md +182 -0
  183. package/skills/taste-skill/references/imagery.md +791 -0
  184. package/skills/taste-skill/references/layout.md +292 -0
  185. package/skills/taste-skill/references/motion.md +980 -0
  186. package/skills/taste-skill/references/research.md +356 -0
  187. package/skills/taste-skill/references/scenes.md +174 -0
  188. package/skills/taste-skill/references/tells.md +115 -0
  189. package/skills/taste-skill/references/type.md +170 -0
  190. package/skills/test-driven-development/SKILL.md +330 -337
  191. package/skills/thermo/SKILL.md +67 -0
  192. package/skills/threat-modeling/SKILL.md +55 -0
  193. package/skills/trailofbits-audit-context/SKILL.md +72 -72
  194. package/skills/trailofbits-insecure-defaults/commands/audit.md +35 -0
  195. package/skills/trailofbits-insecure-defaults/references/debug-features.json +13 -13
  196. package/skills/trailofbits-insecure-defaults/references/debug-features.md +75 -75
  197. package/skills/trailofbits-insecure-defaults/references/default-credentials.json +12 -12
  198. package/skills/trailofbits-insecure-defaults/references/default-credentials.md +76 -76
  199. package/skills/trailofbits-insecure-defaults/references/fail-open-security.json +11 -11
  200. package/skills/trailofbits-insecure-defaults/references/fail-open-security.md +70 -70
  201. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.json +11 -11
  202. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.md +70 -70
  203. package/skills/trailofbits-insecure-defaults/references/permissive-access.json +13 -13
  204. package/skills/trailofbits-insecure-defaults/references/permissive-access.md +62 -62
  205. package/skills/trailofbits-insecure-defaults/references/weak-crypto.json +13 -13
  206. package/skills/trailofbits-insecure-defaults/references/weak-crypto.md +71 -71
  207. package/skills/trailofbits-triage-brocards/SKILL.md +208 -208
  208. package/skills/verification-before-completion/SKILL.md +0 -14
  209. package/skills/writing-plans/SKILL.md +11 -15
  210. package/skills/writing-skills/SKILL.md +21 -303
  211. package/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
  212. package/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
  213. package/skills/writing-skills/references/bulletproofing.md +80 -0
  214. package/skills/writing-skills/references/discovery.md +201 -0
  215. package/skills/writing-skills/references/flowcharts.md +37 -0
  216. package/skills/writing-skills/references/graphviz-conventions.dot +172 -0
  217. package/skills/writing-skills/references/persuasion-principles.md +187 -0
  218. package/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
  219. package/tools/{claude-bridge.ps1 → archive/claude-bridge.ps1} +10 -7
  220. package/tools/{codex-bridge.ps1 → archive/codex-bridge.ps1} +1 -1
  221. package/tools/{gemini-bridge.ps1 → archive/gemini-bridge.ps1} +12 -19
  222. package/skills/gpt-tasteskill/SKILL.md +0 -74
  223. package/skills/taste-skill-v1/SKILL.md +0 -226
  224. /package/tools/{claude-bridge.cmd → archive/claude-bridge.cmd} +0 -0
  225. /package/tools/{claude-bridge.sh → archive/claude-bridge.sh} +0 -0
  226. /package/tools/{codex-bridge.cmd → archive/codex-bridge.cmd} +0 -0
  227. /package/tools/{codex-bridge.sh → archive/codex-bridge.sh} +0 -0
  228. /package/tools/{codexcli-bridge.cmd → archive/codexcli-bridge.cmd} +0 -0
  229. /package/tools/{codexcli-bridge.ps1 → archive/codexcli-bridge.ps1} +0 -0
  230. /package/tools/{gemini-bridge.cmd → archive/gemini-bridge.cmd} +0 -0
  231. /package/tools/{gemini-bridge.sh → archive/gemini-bridge.sh} +0 -0
@@ -1,306 +1,283 @@
1
- ---
2
- name: systematic-debugging
3
- description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
4
- ---
5
-
6
- # Systematic Debugging
7
-
8
- ## Overview
9
-
10
- **Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
11
-
12
- **Violating the letter of this process is violating the spirit of debugging.**
13
-
14
- ## The Iron Law
15
-
16
- ```
17
- NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
18
- ```
19
-
20
- If you haven't completed Phase 1, you cannot propose fixes.
21
-
22
- ## When to Use
23
-
24
- Use for ANY technical issue:
25
- - Test failures
26
- - Bugs in production
27
- - Unexpected behavior
28
- - Performance problems
29
- - Build failures
30
- - Integration issues
31
-
32
- **Use this ESPECIALLY when:**
33
- - Under time pressure (emergencies make guessing tempting)
34
- - "Just one quick fix" seems obvious
35
- - You've already tried multiple fixes
36
- - Previous fix didn't work
37
- - You don't fully understand the issue
38
-
39
- **Don't skip when:**
40
- - Issue seems simple (simple bugs have root causes too)
41
- - You're in a hurry (rushing guarantees rework)
42
- - Manager wants it fixed NOW (systematic is faster than thrashing)
43
-
44
- ## The Four Phases
45
-
46
- You MUST complete each phase before proceeding to the next.
47
-
48
- ### Phase 1: Root Cause Investigation
49
-
50
- **BEFORE attempting ANY fix:**
51
-
52
- 1. **Google EGM Blind Hypothesis Invariant**
53
- - **Withhold speculative guesses**: If dispatching an agent or subagent to isolate the bug, do NOT pass conversational guesses ("I suspect function X is broken").
54
- - Provide ONLY: the symptom, verbatim logs, reproduction steps, and relevant stack traces.
55
- - Force the diagnosing agent (the Goldfish) to observe and codify the failure independently. This prevents anchoring bias and rabbit-hole confirmation bias.
56
-
57
- 2. **Read Error Messages Carefully**
58
- - Don't skip past errors or warnings
59
- - They often contain the exact solution
60
- - Read stack traces completely
61
- - Note line numbers, file paths, error codes
62
-
63
- 2. **Reproduce Consistently**
64
- - Can you trigger it reliably?
65
- - What are the exact steps?
66
- - Does it happen every time?
67
- - If not reproducible → gather more data, don't guess
68
-
69
- 3. **Check Recent Changes**
70
- - What changed that could cause this?
71
- - Git diff, recent commits
72
- - New dependencies, config changes
73
- - Environmental differences
74
-
75
- 4. **Gather Evidence in Multi-Component Systems**
76
-
77
- **WHEN system has multiple components (CI → build → signing, API → service → database):**
78
-
79
- **BEFORE proposing fixes, add diagnostic instrumentation:**
80
- ```
81
- For EACH component boundary:
82
- - Log what data enters component
83
- - Log what data exits component
84
- - Verify environment/config propagation
85
- - Check state at each layer
86
-
87
- Run once to gather evidence showing WHERE it breaks
88
- THEN analyze evidence to identify failing component
89
- THEN investigate that specific component
90
- ```
91
-
92
- **Example (multi-layer system):**
93
- ```bash
94
- # Layer 1: Workflow
95
- echo "=== Secrets available in workflow: ==="
96
- echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
97
-
98
- # Layer 2: Build script
99
- echo "=== Env vars in build script: ==="
100
- env | grep IDENTITY || echo "IDENTITY not in environment"
101
-
102
- # Layer 3: Signing script
103
- echo "=== Keychain state: ==="
104
- security list-keychains
105
- security find-identity -v
106
-
107
- # Layer 4: Actual signing
108
- codesign --sign "$IDENTITY" --verbose=4 "$APP"
109
- ```
110
-
111
- **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
112
-
113
- 5. **Trace Data Flow**
114
-
115
- **WHEN error is deep in call stack:**
116
-
117
- See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
118
-
119
- **Quick version:**
120
- - Where does bad value originate?
121
- - What called this with bad value?
122
- - Keep tracing up until you find the source
123
- - Fix at source, not at symptom
124
-
125
- ### Phase 2: Pattern Analysis
126
-
127
- **Find the pattern before fixing:**
128
-
129
- 1. **Find Working Examples**
130
- - Locate similar working code in same codebase
131
- - What works that's similar to what's broken?
132
-
133
- 2. **Compare Against References**
134
- - If implementing pattern, read reference implementation COMPLETELY
135
- - Don't skim - read every line
136
- - Understand the pattern fully before applying
137
-
138
- 3. **Identify Differences**
139
- - What's different between working and broken?
140
- - List every difference, however small
141
- - Don't assume "that can't matter"
142
-
143
- 4. **Understand Dependencies**
144
- - What other components does this need?
145
- - What settings, config, environment?
146
- - What assumptions does it make?
147
-
148
- ### Phase 3: Hypothesis and Testing
149
-
150
- **Scientific method:**
151
-
152
- 1. **Form Single Hypothesis**
153
- - State clearly: "I think X is the root cause because Y"
154
- - Write it down
155
- - Be specific, not vague
156
-
157
- 2. **Test Minimally**
158
- - Make the SMALLEST possible change to test hypothesis
159
- - One variable at a time
160
- - Don't fix multiple things at once
161
-
162
- 3. **Verify Before Continuing**
163
- - Did it work? Yes → Phase 4
164
- - Didn't work? Form NEW hypothesis
165
- - DON'T add more fixes on top
166
-
167
- 4. **When You Don't Know**
168
- - Say "I don't understand X"
169
- - Don't pretend to know
170
- - Ask for help
171
- - Research more
172
-
173
- ### Phase 4: Implementation
174
-
175
- **Fix the root cause, not the symptom:**
176
-
177
- 1. **Create Failing Test Case**
178
- - Simplest possible reproduction
179
- - Automated test if possible
180
- - One-off test script if no framework
181
- - MUST have before fixing
182
- - Use the `superpowers:test-driven-development` skill for writing proper failing tests
183
-
184
- 2. **Implement Single Fix**
185
- - Address the root cause identified
186
- - ONE change at a time
187
- - No "while I'm here" improvements
188
- - No bundled refactoring
189
-
190
- 3. **Verify Fix**
191
- - Test passes now?
192
- - No other tests broken?
193
- - Issue actually resolved?
194
- - Use the `superpowers:verification-before-completion` skill before claiming success
195
-
196
- 4. **If Fix Doesn't Work**
197
- - STOP
198
- - Count: How many fixes have you tried?
199
- - If < 3: Return to Phase 1, re-analyze with new information
200
- - **If ≥ 3: STOP and question the architecture (step 5 below)**
201
- - DON'T attempt Fix #4 without architectural discussion
202
-
203
- 5. **If 3+ Fixes Failed: Question Architecture**
204
-
205
- **Pattern indicating architectural problem:**
206
- - Each fix reveals new shared state/coupling/problem in different place
207
- - Fixes require "massive refactoring" to implement
208
- - Each fix creates new symptoms elsewhere
209
-
210
- **STOP and question fundamentals:**
211
- - Is this pattern fundamentally sound?
212
- - Are we "sticking with it through sheer inertia"?
213
- - Should we refactor architecture vs. continue fixing symptoms?
214
-
215
- **Discuss with your human partner before attempting more fixes**
216
-
217
- This is NOT a failed hypothesis - this is a wrong architecture.
218
-
219
- ## Red Flags - STOP and Follow Process
220
-
221
- If you catch yourself thinking:
222
- - "Quick fix for now, investigate later"
223
- - "Just try changing X and see if it works"
224
- - "Add multiple changes, run tests"
225
- - "Skip the test, I'll manually verify"
226
- - "It's probably X, let me fix that"
227
- - "I don't fully understand but this might work"
228
- - "Pattern says X but I'll adapt it differently"
229
- - "Here are the main problems: [lists fixes without investigation]"
230
- - Proposing solutions before tracing data flow
231
- - **"One more fix attempt" (when already tried 2+)**
232
- - **Each fix reveals new problem in different place**
233
-
234
- **ALL of these mean: STOP. Return to Phase 1.**
235
-
236
- **If 3+ fixes failed:** Question the architecture (see Phase 4.5)
237
-
238
- ## your human partner's Signals You're Doing It Wrong
239
-
240
- **Watch for these redirections:**
241
- - "Is that not happening?" - You assumed without verifying
242
- - "Will it show us...?" - You should have added evidence gathering
243
- - "Stop guessing" - You're proposing fixes without understanding
244
- - "Ultra-think this" - Question fundamentals, not just symptoms
245
- - "We're stuck?" (frustrated) - Your approach isn't working
246
-
247
- **When you see these:** STOP. Return to Phase 1.
248
-
249
- ## Common Rationalizations
250
-
251
- | Excuse | Reality |
252
- |--------|---------|
253
- | "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
254
- | "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
255
- | "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
256
- | "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
257
- | "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
258
- | "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
259
- | "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
260
- | "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
261
-
262
- ## Quick Reference
263
-
264
- | Phase | Key Activities | Success Criteria |
265
- |-------|---------------|------------------|
266
- | **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
267
- | **2. Pattern** | Find working examples, compare | Identify differences |
268
- | **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
269
- | **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
270
-
271
- ## Build & Toolchain Triage Heuristics
272
-
273
- When debugging build, compilation, bundling, or toolchain failures, distinguish between application bugs and environment/dependency desync before attempting code fixes:
274
-
275
- 1. **Clean Slate Triage (Cache vs Reality)**:
276
- - Never debug build errors against stale caches.
277
- - Verify whether clearing build caches (`rm -rf dist .next .turbo node_modules/.cache`) reproduces or clears the failure.
278
- 2. **Lockfile & Peer Dependency Desync**:
279
- - Check if `package.json` was modified without updating lockfiles (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`).
280
- - Identify conflicting duplicate versions of peer dependencies (e.g. conflicting `react`, `typescript`, or `@types/*` versions across workspaces).
281
- 3. **Module Resolution & Target Mismatch**:
282
- - Verify `tsconfig.json` settings: `moduleResolution` (`NodeNext` vs `Bundler`), `target` (`ES2022`, `ESNext`), and `.mjs`/`.cjs` boundaries.
283
- - Watch for ESM/CJS interop traps (e.g. `require()` of pure ESM packages, missing `.js` extensions in ESM relative imports).
284
- 4. **Runtime & Toolchain Version Skew**:
285
- - Verify active Node/Bun/Python version matches engine constraints (`.node-version`, `.nvmrc`, `package.json` `engines`).
286
- 5. **Build-Time vs. Runtime Environment Variables**:
287
- - Distinguish variables required at bundling time (e.g. `NEXT_PUBLIC_*`, `VITE_*`) from secrets required only at server runtime.
288
-
289
- ## When Process Reveals "No Root Cause"
290
-
291
- If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
292
-
293
- 1. You've completed the process
294
- 2. Document what you investigated
295
- 3. Implement appropriate handling (retry, timeout, error message)
296
- 4. Add monitoring/logging for future investigation
297
-
298
- **But:** 95% of "no root cause" cases are incomplete investigation.
299
-
300
- ## Supporting Techniques
301
-
302
- These techniques are part of systematic debugging and available in this directory:
303
-
304
- - **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
305
- - **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
306
- - **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
1
+ ---
2
+ name: systematic-debugging
3
+ description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
4
+ ---
5
+
6
+ # Systematic Debugging
7
+
8
+ ## Overview
9
+
10
+ **Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
11
+
12
+ **Violating the letter of this process is violating the spirit of debugging.**
13
+
14
+ ## The Iron Law
15
+
16
+ ```
17
+ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
18
+ ```
19
+
20
+ If you haven't completed Phase 1, you cannot propose fixes.
21
+
22
+ ## When to Use
23
+
24
+ Use for ANY technical issue:
25
+ - Test failures
26
+ - Bugs in production
27
+ - Unexpected behavior
28
+ - Performance problems
29
+ - Build failures
30
+ - Integration issues
31
+
32
+ **Use this ESPECIALLY when:**
33
+ - Under time pressure (emergencies make guessing tempting)
34
+ - "Just one quick fix" seems obvious
35
+ - You've already tried multiple fixes
36
+ - Previous fix didn't work
37
+ - You don't fully understand the issue
38
+
39
+ **Don't skip when:**
40
+ - Issue seems simple (simple bugs have root causes too)
41
+ - You're in a hurry (rushing guarantees rework)
42
+ - Manager wants it fixed NOW (systematic is faster than thrashing)
43
+
44
+ ## The Four Phases
45
+
46
+ You MUST complete each phase before proceeding to the next.
47
+
48
+ ### Phase 1: Root Cause Investigation
49
+
50
+ **BEFORE attempting ANY fix:**
51
+
52
+ 1. **Read Error Messages Carefully**
53
+ - Don't skip past errors or warnings
54
+ - They often contain the exact solution
55
+ - Read stack traces completely
56
+ - Note line numbers, file paths, error codes
57
+
58
+ 2. **Reproduce Consistently**
59
+ - Can you trigger it reliably?
60
+ - What are the exact steps?
61
+ - Does it happen every time?
62
+ - If not reproducible → gather more data, don't guess
63
+
64
+ 3. **Check Recent Changes**
65
+ - What changed that could cause this?
66
+ - Git diff, recent commits
67
+ - New dependencies, config changes
68
+ - Environmental differences
69
+
70
+ 4. **Gather Evidence in Multi-Component Systems**
71
+
72
+ **WHEN system has multiple components (CI → build → signing, API → service → database):**
73
+
74
+ **BEFORE proposing fixes, add diagnostic instrumentation:**
75
+ ```
76
+ For EACH component boundary:
77
+ - Log what data enters component
78
+ - Log what data exits component
79
+ - Verify environment/config propagation
80
+ - Check state at each layer
81
+
82
+ Run once to gather evidence showing WHERE it breaks
83
+ THEN analyze evidence to identify failing component
84
+ THEN investigate that specific component
85
+ ```
86
+
87
+ **Example (multi-layer system):**
88
+ ```bash
89
+ # Layer 1: Workflow
90
+ echo "=== Secrets available in workflow: ==="
91
+ echo "IDENTITY: $([ -n "${IDENTITY:-}" ] && echo SET || echo UNSET)"
92
+
93
+ # Layer 2: Build script
94
+ echo "=== Env vars in build script: ==="
95
+ printenv IDENTITY >/dev/null 2>&1 && echo "IDENTITY in environment" || echo "IDENTITY not in environment"
96
+
97
+ # Layer 3: Signing script
98
+ echo "=== Keychain state: ==="
99
+ security list-keychains
100
+ security find-identity -v
101
+
102
+ # Layer 4: Actual signing
103
+ codesign --sign "$IDENTITY" --verbose=4 "$APP"
104
+ ```
105
+
106
+ **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
107
+
108
+ 5. **Trace Data Flow**
109
+
110
+ **WHEN error is deep in call stack:**
111
+
112
+ See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
113
+
114
+ **Quick version:**
115
+ - Where does bad value originate?
116
+ - What called this with bad value?
117
+ - Keep tracing up until you find the source
118
+ - Fix at source, not at symptom
119
+
120
+ ### Phase 2: Pattern Analysis
121
+
122
+ **Find the pattern before fixing:**
123
+
124
+ 1. **Find Working Examples**
125
+ - Locate similar working code in same codebase
126
+ - What works that's similar to what's broken?
127
+
128
+ 2. **Compare Against References**
129
+ - If implementing pattern, read reference implementation COMPLETELY
130
+ - Don't skim - read every line
131
+ - Understand the pattern fully before applying
132
+
133
+ 3. **Identify Differences**
134
+ - What's different between working and broken?
135
+ - List every difference, however small
136
+ - Don't assume "that can't matter"
137
+
138
+ 4. **Understand Dependencies**
139
+ - What other components does this need?
140
+ - What settings, config, environment?
141
+ - What assumptions does it make?
142
+
143
+ ### Phase 3: Hypothesis and Testing
144
+
145
+ **Scientific method:**
146
+
147
+ 1. **Form Single Hypothesis**
148
+ - State clearly: "I think X is the root cause because Y"
149
+ - Write it down
150
+ - Be specific, not vague
151
+
152
+ 2. **Test Minimally**
153
+ - Make the SMALLEST possible change to test hypothesis
154
+ - One variable at a time
155
+ - Don't fix multiple things at once
156
+
157
+ 3. **Verify Before Continuing**
158
+ - Did it work? Yes → Phase 4
159
+ - Didn't work? Form NEW hypothesis
160
+ - DON'T add more fixes on top
161
+
162
+ 4. **When You Don't Know**
163
+ - Say "I don't understand X"
164
+ - Don't pretend to know
165
+ - Ask for help
166
+ - Research more
167
+
168
+ ### Phase 4: Implementation
169
+
170
+ **Fix the root cause, not the symptom:**
171
+
172
+ 1. **Create Failing Test Case**
173
+ - Simplest possible reproduction
174
+ - Automated test if possible
175
+ - One-off test script if no framework
176
+ - MUST have before fixing
177
+ - Use the `superpowers:test-driven-development` skill for writing proper failing tests
178
+
179
+ 2. **Implement Single Fix**
180
+ - Address the root cause identified
181
+ - ONE change at a time
182
+ - No "while I'm here" improvements
183
+ - No bundled refactoring
184
+
185
+ 3. **Verify Fix**
186
+ - Test passes now?
187
+ - No other tests broken?
188
+ - Issue actually resolved?
189
+ - Use the `superpowers:verification-before-completion` skill before claiming success
190
+
191
+ 4. **If Fix Doesn't Work**
192
+ - STOP
193
+ - Count: How many fixes have you tried?
194
+ - If < 3: Return to Phase 1, re-analyze with new information
195
+ - **If ≥ 3: STOP and question the architecture (step 5 below)**
196
+ - DON'T attempt Fix #4 without architectural discussion
197
+
198
+ 5. **If 3+ Fixes Failed: Question Architecture**
199
+
200
+ **Pattern indicating architectural problem:**
201
+ - Each fix reveals new shared state/coupling/problem in different place
202
+ - Fixes require "massive refactoring" to implement
203
+ - Each fix creates new symptoms elsewhere
204
+
205
+ **STOP and question fundamentals:**
206
+ - Is this pattern fundamentally sound?
207
+ - Are we "sticking with it through sheer inertia"?
208
+ - Should we refactor architecture vs. continue fixing symptoms?
209
+
210
+ **Discuss with your human partner before attempting more fixes**
211
+
212
+ This is NOT a failed hypothesis - this is a wrong architecture.
213
+
214
+ ## Red Flags - STOP and Follow Process
215
+
216
+ If you catch yourself thinking:
217
+ - "Quick fix for now, investigate later"
218
+ - "Just try changing X and see if it works"
219
+ - "Add multiple changes, run tests"
220
+ - "Skip the test, I'll manually verify"
221
+ - "It's probably X, let me fix that"
222
+ - "I don't fully understand but this might work"
223
+ - "Pattern says X but I'll adapt it differently"
224
+ - "Here are the main problems: [lists fixes without investigation]"
225
+ - Proposing solutions before tracing data flow
226
+ - **"One more fix attempt" (when already tried 2+)**
227
+ - **Each fix reveals new problem in different place**
228
+
229
+ **ALL of these mean: STOP. Return to Phase 1.**
230
+
231
+ **If 3+ fixes failed:** Question the architecture (see Phase 4.5)
232
+
233
+ ## your human partner's Signals You're Doing It Wrong
234
+
235
+ **Watch for these redirections:**
236
+ - "Is that not happening?" - You assumed without verifying
237
+ - "Will it show us...?" - You should have added evidence gathering
238
+ - "Stop guessing" - You're proposing fixes without understanding
239
+ - "Ultra-think this" - Question fundamentals, not just symptoms
240
+ - "We're stuck?" (frustrated) - Your approach isn't working
241
+
242
+ **When you see these:** STOP. Return to Phase 1.
243
+
244
+ ## Common Rationalizations
245
+
246
+ | Excuse | Reality |
247
+ |--------|---------|
248
+ | "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
249
+ | "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
250
+ | "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
251
+ | "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
252
+ | "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
253
+ | "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
254
+ | "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
255
+ | "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
256
+
257
+ ## Quick Reference
258
+
259
+ | Phase | Key Activities | Success Criteria |
260
+ |-------|---------------|------------------|
261
+ | **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
262
+ | **2. Pattern** | Find working examples, compare | Identify differences |
263
+ | **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
264
+ | **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
265
+
266
+ ## When Process Reveals "No Root Cause"
267
+
268
+ If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
269
+
270
+ 1. You've completed the process
271
+ 2. Document what you investigated
272
+ 3. Implement appropriate handling (retry, timeout, error message)
273
+ 4. Add monitoring/logging for future investigation
274
+
275
+ **But:** 95% of "no root cause" cases are incomplete investigation.
276
+
277
+ ## Supporting Techniques
278
+
279
+ These techniques are part of systematic debugging and available in this directory:
280
+
281
+ - **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
282
+ - **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
283
+ - **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling