debugging

Name: debugging
Author: krzysztofsurdy

43installs1forks

How to install debugging?

krzysztofsurdy/code-virtuoso/debugging

$npx -y skills add krzysztofsurdy/code-virtuoso --skill debugging

Installs into the current project.

Summary

Systematic debugging methodology for finding and fixing bugs through root cause analysis. Use when the user encounters a bug, test failure, flaky behavior, production error, performance degradation, or integration failure. Covers the reproduce-investigate-hypothesize-fix-prevent

Files · 1

View on GitHub

SKILL.md

1	# Debugging
2
3	Systematic methodology for finding and fixing bugs. Prioritizes root cause analysis over symptom treatment, evidence over intuition, and prevention over recurrence.
4
5	## Iron Law
6
7	No fix without root cause. Never apply a fix until you can explain WHY the bug exists, not just WHERE it manifests. Symptom-level fixes create new bugs.
8
9	## When to Use
10
11	- Bug report from QA or production alert
12	- Test failure with unclear cause
13	- Intermittent/flaky behavior
14	- Performance degradation
15	- Unexpected behavior that "used to work"
16	- Integration failures between components
17
18	## Workflow
19
20	### Phase 1: Reproduce
21
22	Establish a reliable reproduction before investigating.
23
24	1. Collect all evidence — error messages, stack traces, logs, screenshots, user steps
25	2. Identify the exact conditions: environment, data state, user actions, timing
26	3. Create a minimal reproduction — strip away everything that isn't needed to trigger the bug
27	4. Confirm reproduction is consistent (if intermittent, note frequency and conditions)
28	5. Write down the reproduction steps precisely — someone else should be able to follow them
29
30	Output: Documented reproduction steps, minimal test case
31
32	If you cannot reproduce: Document what you tried, check environment differences, add instrumentation and wait for next occurrence. Do not proceed to Phase 2 on guesswork — unreproducible bugs get logged, not "fixed."
33
34	### Phase 2: Investigate
35
36	Gather evidence systematically. Do NOT form hypotheses yet — this phase is about observation, not explanation.
37
38	1. Read the full error message and stack trace — every line, not just the first one
39	2. Check git history — what changed recently? (`git log --since="2 weeks ago"`, `git bisect`)
40	3. Trace the data flow — follow the input from entry point to failure point
41	4. Check boundaries — where does data cross component/service/layer boundaries?
42	5. Collect environmental context — versions, configuration, dependencies, resource state
43	6. Map the blast radius — what else is affected? Is this an isolated failure or systemic?
44
45	Production vs development debugging:
46	- Production: Prioritize impact assessment and mitigation first. Can you reduce blast radius before investigating? Read-only access only — never debug by modifying production state.
47	- Development: You have full control. Use breakpoints, modify state, add temporary logging freely.
48
49	Output: Evidence log (what you found, where, timestamps), affected component map
50
51	### Phase 3: Hypothesize
52
53	Form competing hypotheses ranked by evidence strength.
54
55	1. List ALL plausible causes — do not anchor on the first idea
56	2. Classify each hypothesis by bug category (see [bug categories reference](references/bug-categories.md))
57	3. Rate each: evidence strength (strong/medium/weak), testability (easy/hard), likelihood
58	4. Pick the most likely AND most testable hypothesis first
59	5. Define what would CONFIRM and what would FALSIFY each hypothesis
60
61	Example hypothesis table:
62
63	\| # \| Hypothesis \| Category \| Evidence \| Testability \| Test Plan \|
64	\|---\|---\|---\|---\|---\|---\|
65	\| 1 \| Cache returns stale data after update \| State \| Log shows old value 2s after write \| Easy \| Bypass cache and compare \|
66	\| 2 \| Race condition between two workers \| Race condition \| Intermittent, high load correlation \| Medium \| Add locking, stress test \|
67	\| 3 \| Upstream API returns unexpected format \| Integration \| No evidence yet \| Easy \| Log raw response \|
68
69	Output: Ranked hypothesis list with evidence and test plan
70
71	### Phase 4: Test
72
73	Validate one hypothesis at a time. Single-variable changes only.
74
75	1. Change ONE thing and observe the result
76	2. If confirmed — proceed to Phase 5
77	3. If falsified — update evidence log, return to next hypothesis
78	4. If inconclusive — add more instrumentation, gather more evidence
79	5. After 3 failed hypotheses — STOP. Re-examine your assumptions. The bug model may be wrong.
80
81	Red flags (return to Phase 2 immediately):
82	- "Quick fix for now, investigate later"
83	- Changing multiple things at once
84	- Fixing without understanding
85	- Copy-pasting a fix from the internet without understanding why it works
86
87	Output: Confirmed root cause with evidence chain
88
89	### Phase 5: Fix
90
91	Implement the fix at the source, not at the symptom.
92
93	1. Write a failing test that reproduces the bug FIRST
94	2. Implement the fix — single, focused change addressing the root cause
95	3. Verify the failing test now passes
96	4. Run the full test suite — ensure no regressions
97	5. Review

People who liked this also viewed

6 picks

Type

debugging

43installs1forks

View on GitHub

How to install debugging?

krzysztofsurdy/code-virtuoso/debugging

$npx -y skills add krzysztofsurdy/code-virtuoso --skill debugging

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Debugging
2
3	Systematic methodology for finding and fixing bugs. Prioritizes root cause analysis over symptom treatment, evidence over intuition, and prevention over recurrence.
4
5	## Iron Law
6
7	No fix without root cause. Never apply a fix until you can explain WHY the bug exists, not just WHERE it manifests. Symptom-level fixes create new bugs.
8
9	## When to Use
10
11	- Bug report from QA or production alert
12	- Test failure with unclear cause
13	- Intermittent/flaky behavior
14	- Performance degradation
15	- Unexpected behavior that "used to work"
16	- Integration failures between components
17
18	## Workflow
19
20	### Phase 1: Reproduce
21
22	Establish a reliable reproduction before investigating.
23
24	1. Collect all evidence — error messages, stack traces, logs, screenshots, user steps
25	2. Identify the exact conditions: environment, data state, user actions, timing
26	3. Create a minimal reproduction — strip away everything that isn't needed to trigger the bug
27	4. Confirm reproduction is consistent (if intermittent, note frequency and conditions)
28	5. Write down the reproduction steps precisely — someone else should be able to follow them
29
30	Output: Documented reproduction steps, minimal test case
31
32	If you cannot reproduce: Document what you tried, check environment differences, add instrumentation and wait for next occurrence. Do not proceed to Phase 2 on guesswork — unreproducible bugs get logged, not "fixed."
33
34	### Phase 2: Investigate
35
36	Gather evidence systematically. Do NOT form hypotheses yet — this phase is about observation, not explanation.
37
38	1. Read the full error message and stack trace — every line, not just the first one
39	2. Check git history — what changed recently? (`git log --since="2 weeks ago"`, `git bisect`)
40	3. Trace the data flow — follow the input from entry point to failure point
41	4. Check boundaries — where does data cross component/service/layer boundaries?
42	5. Collect environmental context — versions, configuration, dependencies, resource state
43	6. Map the blast radius — what else is affected? Is this an isolated failure or systemic?
44
45	Production vs development debugging:
46	- Production: Prioritize impact assessment and mitigation first. Can you reduce blast radius before investigating? Read-only access only — never debug by modifying production state.
47	- Development: You have full control. Use breakpoints, modify state, add temporary logging freely.
48
49	Output: Evidence log (what you found, where, timestamps), affected component map
50
51	### Phase 3: Hypothesize
52
53	Form competing hypotheses ranked by evidence strength.
54
55	1. List ALL plausible causes — do not anchor on the first idea
56	2. Classify each hypothesis by bug category (see [bug categories reference](references/bug-categories.md))
57	3. Rate each: evidence strength (strong/medium/weak), testability (easy/hard), likelihood
58	4. Pick the most likely AND most testable hypothesis first
59	5. Define what would CONFIRM and what would FALSIFY each hypothesis
60
61	Example hypothesis table:
62
63	\| # \| Hypothesis \| Category \| Evidence \| Testability \| Test Plan \|
64	\|---\|---\|---\|---\|---\|---\|
65	\| 1 \| Cache returns stale data after update \| State \| Log shows old value 2s after write \| Easy \| Bypass cache and compare \|
66	\| 2 \| Race condition between two workers \| Race condition \| Intermittent, high load correlation \| Medium \| Add locking, stress test \|
67	\| 3 \| Upstream API returns unexpected format \| Integration \| No evidence yet \| Easy \| Log raw response \|
68
69	Output: Ranked hypothesis list with evidence and test plan
70
71	### Phase 4: Test
72
73	Validate one hypothesis at a time. Single-variable changes only.
74
75	1. Change ONE thing and observe the result
76	2. If confirmed — proceed to Phase 5
77	3. If falsified — update evidence log, return to next hypothesis
78	4. If inconclusive — add more instrumentation, gather more evidence
79	5. After 3 failed hypotheses — STOP. Re-examine your assumptions. The bug model may be wrong.
80
81	Red flags (return to Phase 2 immediately):
82	- "Quick fix for now, investigate later"
83	- Changing multiple things at once
84	- Fixing without understanding
85	- Copy-pasting a fix from the internet without understanding why it works
86
87	Output: Confirmed root cause with evidence chain
88
89	### Phase 5: Fix
90
91	Implement the fix at the source, not at the symptom.
92
93	1. Write a failing test that reproduces the bug FIRST
94	2. Implement the fix — single, focused change addressing the root cause
95	3. Verify the failing test now passes
96	4. Run the full test suite — ensure no regressions
97	5. Review

People who liked this also viewed

6 picks

Type