systematic-debugging

Name: systematic-debugging
Author: obra

byobra· 95 skills

Installs

205k

Stars

261k

Forks

23k

How to install systematic-debugging?

obra/superpowers/systematic-debugging

$npx -y skills add obra/superpowers --skill systematic-debugging

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/obra/superpowers" --skill "obra/superpowers/systematic-debugging"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/obra/superpowers" that are relevant to the current task. Run `npx skills add "https://github.com/obra/superpowers"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	# Systematic Debugging
2
3	## Overview
4
5	Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
6
7	Violating the letter of this process is violating the spirit of debugging.
8
9	## The Iron Law
10
11	```
12	NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
13	```
14
15	If you haven't completed Phase 1, you cannot propose fixes.
16
17	## When to Use
18
19	Use for ANY technical issue:
20	- Test failures
21	- Bugs in production
22	- Unexpected behavior
23	- Performance problems
24	- Build failures
25	- Integration issues
26
27	Use this ESPECIALLY when:
28	- Under time pressure (emergencies make guessing tempting)
29	- "Just one quick fix" seems obvious
30	- You've already tried multiple fixes
31	- Previous fix didn't work
32	- You don't fully understand the issue
33
34	Don't skip when:
35	- Issue seems simple (simple bugs have root causes too)
36	- You're in a hurry (rushing guarantees rework)
37	- Manager wants it fixed NOW (systematic is faster than thrashing)
38
39	## The Four Phases
40
41	You MUST complete each phase before proceeding to the next.
42
43	### Phase 1: Root Cause Investigation
44
45	BEFORE attempting ANY fix:
46
47	1. Read Error Messages Carefully
48	- Don't skip past errors or warnings
49	- They often contain the exact solution
50	- Read stack traces completely
51	- Note line numbers, file paths, error codes
52
53	2. Reproduce Consistently
54	- Can you trigger it reliably?
55	- What are the exact steps?
56	- Does it happen every time?
57	- If not reproducible → gather more data, don't guess
58
59	3. Check Recent Changes
60	- What changed that could cause this?
61	- Git diff, recent commits
62	- New dependencies, config changes
63	- Environmental differences
64
65	4. Gather Evidence in Multi-Component Systems
66
67	WHEN system has multiple components (CI → build → signing, API → service → database):
68
69	BEFORE proposing fixes, add diagnostic instrumentation:
70	```
71	For EACH component boundary:
72	- Log what data enters component
73	- Log what data exits component
74	- Verify environment/config propagation
75	- Check state at each layer
76
77	Run once to gather evidence showing WHERE it breaks
78	THEN analyze evidence to identify failing component
79	THEN investigate that specific component
80	```
81
82	Example (multi-layer system):
83	```bash
84	# Layer 1: Workflow
85	echo "=== Secrets available in workflow: ==="
86	echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
87
88	# Layer 2: Build script
89	echo "=== Env vars in build script: ==="
90	env \| grep IDENTITY \|\| echo "IDENTITY not in environment"
91
92	# Layer 3: Signing script
93	echo "=== Keychain state: ==="
94	security list-keychains
95	security find-identity -v
96
97	# Layer 4: Actual signing
98	codesign --sign "$IDENTITY" --verbose=4 "$APP"
99	```
100
101	This reveals: Which layer fails (secrets → workflow ✓, workflow → build ✗)
102
103	5. Trace Data Flow
104
105	WHEN error is deep in call stack:
106
107	See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
108
109	Quick version:
110	- Where does bad value originate?
111	- What called this with bad value?
112	- Keep tracing up until you find the source
113	- Fix at source, not at symptom
114
115	### Phase 2: Pattern Analysis
116
117	Find the pattern before fixing:
118
119	1. Find Working Examples
120	- Locate similar working code in same codebase
121	- What works that's similar to what's broken?
122
123	2. Compare Against References
124	- If implementing pattern, read reference implementation COMPLETELY
125	- Don't skim - read every line
126	- Understand the pattern fully before applying
127
128	3. Identify Differences
129	- What's different between working and broken?
130	- List every difference, however small
131	- Don't assume "that can't matter"
132
133	4. Understand Dependencies
134	- What other components does this need?
135	- What settings, config, environment?
136	- What assumptions does it make?
137
138	### Phase 3: Hypothesis and Testing
139
140	Scientific method:
141
142	1. Form Single Hypothesis
143	- State clearly: "I think X is the root cause because Y"
144	- Write it down
145	- Be specific, not vague
146
147	2. Test Minimally
148	- Make the SMALLEST possible change to test hypothesis
149	- One variable at a time
150	- Don't fix multiple things at once
151
152	3. Verify Before Continuing
153	- Did it work? Yes → Phase 4
154	- Didn't work? Form NEW hypothesis
155	- DON'T add more fixes on top
156
157	4. When You Don't Know
158	- Say "I don't understand X"
159	- Don't pretend to know
160	- Ask for help
161	- Research more
162
163	### Phase 4: Implementation
164
165	Fix the root cause, not the symptom:
166
167	1. Create Failing Test Case
168	- Simplest possible reproduction
169	- Automated test if possible
170	- One-off test script if no framework
171	- MUST have before fixing
172	- Use the `superpowers:test-driven-development` skill for writing proper failing tests
173
174	2. Implement Single Fix
175	- Address the root cause identified
176	- ONE change at a time
177	- No "while I'm here" improvements
178	- No bundled refactoring
179
180	3. Verify Fix
181	- Test passes now?
182	- No other tests broken?
183	- Issue actually resolved?
184	- Use the `superpowers:verification-before-completion` skill before claiming success
185
186	4. If Fix Doesn't Work
187	- STOP
188	- Count: How many fixes have you tried?
189	- If < 3: Return to Phase 1, re-analyze with new information
190	- If ≥ 3: STOP and question the architecture (step 5 below)
191	- DON'T attempt Fix #4 without architectural discussion
192
193	5. If 3+ Fixes Failed: Question Architecture
194
195	Pattern indicating architectural problem:
196	- Each fix reveals new shared state/coupling/problem in different place
197	- Fixes require "massive refactoring" to implement
198	- Each fix creates new symptoms elsewhere
199
200	STOP and question fundamentals:
201	- Is this pattern fundamentally sound?
202	- Are we "sticking with it through sheer inertia"?
203	- Should we refactor architecture vs. continue fixing symptoms?
204
205	Discuss with your human partner before attempting more fixes
206
207	This is NOT a failed hypothesis - this is a wrong architecture.
208
209	## Red Flags - STOP and Follow Process
210
211	If you catch yourself thinking:
212	- "Quick fix for now, investigate later"
213	- "Just try changing X and see if it works"
214	- "Add multiple changes, run tests"
215	- "Skip the test, I'll manually verify"
216	- "It's probably X, let me fix that"
217	- "I don't fully understand but this might work"
218	- "Pattern says X but I'll adapt it differently"
219	- "Here are the main problems: [lists fixes without investigation]"
220	- Proposing solutions before tracing data flow
221	- "One more fix attempt" (when already tried 2+)
222	- Each fix reveals new problem in different place
223
224	ALL of these mean: STOP. Return to Phase 1.
225
226	If 3+ fixes failed: Question the architecture (see Phase 4.5)
227
228	## your human partner's Signals You're Doing It Wrong
229
230	Watch for these redirections:
231	- "Is that not happening?" - You assumed without verifying
232	- "Will it show us...?" - You should have added evidence gathering
233	- "Stop guessing" - You're proposing fixes without understanding
234	- "Ultra-think this" - Question fundamentals, not just symptoms
235	- "We're stuck?" (frustrated) - Your approach isn't working
236
237	When you see these: STOP. Return to Phase 1.
238
239	## Common Rationalizations
240
241	\| Excuse \| Reality \|
242	\|--------\|---------\|
243	\| "Issue is simple, don't need process" \| Simple issues have root causes too. Process is fast for simple bugs. \|
244	\| "Emergency, no time for process" \| Systematic debugging is FASTER than guess-and-check thrashing. \|
245	\| "Just try this first, then investigate" \| First fix sets the pattern. Do it right from the start. \|
246	\| "I'll write test after confirming fix works" \| Untested fixes don't stick. Test first proves it. \|
247	\| "Multiple fixes at once saves time" \| Can't isolate what worked. Causes new bugs. \|
248	\| "Reference too long, I'll adapt the pattern" \| Partial understanding guarantees bugs. Read it completely. \|
249	\| "I see the problem, let me fix it" \| Seeing symptoms ≠ understanding root cause. \|
250	\| "One more fix attempt" (after 2+ failures) \| 3+ failures = architectural problem. Question pattern, don't fix again. \|
251
252	## Quick Reference
253
254	\| Phase \| Key Activities \| Success Criteria \|
255	\|-------\|---------------\|------------------\|
256	\| 1. Root Cause \| Read errors, reproduce, check changes, gather evidence \| Understand WHAT and WHY \|
257	\| 2. Pattern \| Find working examples, compare \| Identify differences \|
258	\| 3. Hypothesis \| Form theory, test minimally \| Confirmed or new hypothesis \|
259	\| 4. Implementation \| Create test, fix, verify \| Bug resolved, tests pass \|
260
261	## When Process Reveals "No Root Cause"
262
263	If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
264
265	1. You've completed the process
266	2. Document what you investigated
267	3. Implement appropriate handling (retry, timeout, error message)
268	4. Add monitoring/logging for future investigation
269
270	But: 95% of "no root cause" cases are incomplete investigation.
271
272	## Supporting Techniques
273
274	These techniques are part of systematic debugging and available in this directory:
275
276	- `root-cause-tracing.md` - Trace bugs backward through call stack to find original trigger
277	- `defense-in-depth.md` - Add validation at multiple layers after finding root cause
278	- `condition-based-waiting.md` - Replace arbitrary timeouts with condition polling

6 picks

Type

Run `npx skills use "https://github.com/obra/superpowers" --skill "obra/superpowers/systematic-debugging"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/obra/superpowers" that are relevant to the current task. Run `npx skills add "https://github.com/obra/superpowers"` and select the relevant skills, then follow their instructions.

systematic-debugging

How to install systematic-debugging?

Related

systematic-debugging

How to install systematic-debugging?

Related