systematic-debugging

Name: systematic-debugging
Author: AlexAI-MCP

132stars24forks

How to install systematic-debugging?

alexai-mcp/hermes-ccc/systematic-debugging

$npx -y skills add AlexAI-MCP/hermes-CCC --skill systematic-debugging

Installs into the current project.

Summary

Run a disciplined multi-phase debugging loop for Claude Code tasks. Use when failures are ambiguous, regressions are hard to localize, logs are noisy, or a bug fix must be proven rather than guessed.

Files · 1

View on GitHub

SKILL.md

1	# Systematic Debugging
2
3	## Purpose
4
5	- Prevent guess-driven bug fixing.
6	- Turn a vague failure into a proved root cause.
7	- Separate symptom collection from patching.
8	- Minimize regressions while repairing defects.
9	- Leave behind a reproducible explanation of the failure.
10
11	## Activation Signals
12
13	- Use this skill when the root cause is unknown.
14	- Use this skill when a previous fix attempt failed.
15	- Use this skill when the bug spans multiple files or layers.
16	- Use this skill when logs, stack traces, or user reports disagree.
17	- Use this skill when the fix must be defensible in review.
18
19	## Debugging Phases
20
21	1. Stabilize the report.
22	2. Reproduce the failure.
23	3. Narrow the surface area.
24	4. Instrument the system.
25	5. Generate hypotheses.
26	6. Prove or kill hypotheses.
27	7. Patch the true cause.
28	8. Verify the fix.
29	9. Add regression protection.
30	10. Save the lesson if durable.
31
32	## Phase 1: Stabilize The Report
33
34	- Write the exact symptom in one sentence.
35	- Record expected behavior.
36	- Record actual behavior.
37	- Capture environment assumptions.
38	- Capture whether the issue is deterministic or flaky.
39	- Capture whether it is new, old, or recently regressed.
40	- Avoid editing code during this phase.
41
42	## Phase 2: Reproduce The Failure
43
44	- Find the smallest reproducible path.
45	- Prefer automated reproduction over manual UI clicking.
46	- Save the failing command when possible.
47	- If no test exists, create a reproduction harness.
48	- Record exact inputs, flags, and fixtures.
49	- If the bug is flaky, measure frequency instead of pretending it is stable.
50
51	## Phase 3: Narrow The Surface Area
52
53	- Identify likely subsystem boundaries.
54	- Diff recent changes when history is relevant.
55	- Check whether the failure begins before or after I/O boundaries.
56	- Compare passing and failing code paths.
57	- Use binary search over scope when the change window is large.
58	- Reduce the problem before adding more instrumentation.
59
60	## Phase 4: Instrument The System
61
62	- Add temporary logging only where uncertainty exists.
63	- Prefer cheap inspection over permanent noisy logging.
64	- Log invariant checkpoints, not everything.
65	- Print or inspect the variables that decide branching behavior.
66	- If async behavior is involved, log timestamps and ordering.
67	- Remove temporary instrumentation after the fix unless it becomes useful observability.
68
69	## Phase 5: Generate Hypotheses
70
71	- Generate multiple plausible causes, not one favorite theory.
72	- Rank hypotheses by explanatory power and test cost.
73	- Prefer hypotheses that explain all observed symptoms.
74	- Write down what evidence would falsify each one.
75	- Do not patch based on intuition alone.
76
77	## Phase 6: Prove Or Kill Hypotheses
78
79	- Design the smallest experiment that differentiates the top hypotheses.
80	- Run one high-signal experiment at a time.
81	- Keep notes on what each result means.
82	- Kill hypotheses aggressively when evidence contradicts them.
83	- Escalate instrumentation only when the current evidence is insufficient.
84
85	## Phase 7: Patch The True Cause
86
87	- Change only the code implicated by evidence.
88	- Prefer the smallest change that restores the invariant.
89	- Avoid bundling unrelated cleanup in the debug patch.
90	- If the bug exposed a missing boundary, add the boundary explicitly.
91	- Preserve readability even for emergency fixes.
92
93	## Phase 8: Verify The Fix
94
95	- Re-run the original reproduction.
96	- Re-run nearby tests.
97	- Check negative cases, not just the positive happy path.
98	- Validate that logs or state transitions now match expectation.
99	- If the bug was flaky, run enough repetitions to earn confidence.
100
101	## Phase 9: Add Regression Protection
102
103	- Add or strengthen a test that would have caught the bug.
104	- Place the test at the lowest layer that reliably expresses the defect.
105	- If a test is impossible, document the missing seam.
106	- Prefer deterministic tests over timing-sensitive ones.
107
108	## Phase 10: Save The Lesson
109
110	- Save a durable memory entry if the issue reflects a reusable pattern.
111	- Save a trajectory if the investigation is valuable for QA or training data.
112	- Update docs only if the bug revealed a workflow or contract gap.
113
114	## Evidence Sources
115
116	- failing tests
117	- stack traces
118	- logs
119	- diffs
120	- recent commits
121	- config files
122	- environment variables
123	- production reports
124	- screenshots or traces
125
126	## Useful Commands
127
128	```bash
129	pytest -k "failing_case" -vv
130	rg "relevant_symbol\|error_text" .
131	git diff --stat
132	git log --oneline -- path/to/file
133	```
134
135	## Decision Rules
136
137	- If you cannot reproduce the issue, stop calling it fixed.
138	- If two symptoms disagree, debug t

People who liked this also viewed

6 picks

Type

systematic-debugging

132stars24forks

View on GitHub

How to install systematic-debugging?

alexai-mcp/hermes-ccc/systematic-debugging

$npx -y skills add AlexAI-MCP/hermes-CCC --skill systematic-debugging

Installs into the current project.

Summary

Run a disciplined multi-phase debugging loop for Claude Code tasks. Use when failures are ambiguous, regressions are hard to localize, logs are noisy, or a bug fix must be proven rather than guessed.

Files · 1

View on GitHub

SKILL.md

1	# Systematic Debugging
2
3	## Purpose
4
5	- Prevent guess-driven bug fixing.
6	- Turn a vague failure into a proved root cause.
7	- Separate symptom collection from patching.
8	- Minimize regressions while repairing defects.
9	- Leave behind a reproducible explanation of the failure.
10
11	## Activation Signals
12
13	- Use this skill when the root cause is unknown.
14	- Use this skill when a previous fix attempt failed.
15	- Use this skill when the bug spans multiple files or layers.
16	- Use this skill when logs, stack traces, or user reports disagree.
17	- Use this skill when the fix must be defensible in review.
18
19	## Debugging Phases
20
21	1. Stabilize the report.
22	2. Reproduce the failure.
23	3. Narrow the surface area.
24	4. Instrument the system.
25	5. Generate hypotheses.
26	6. Prove or kill hypotheses.
27	7. Patch the true cause.
28	8. Verify the fix.
29	9. Add regression protection.
30	10. Save the lesson if durable.
31
32	## Phase 1: Stabilize The Report
33
34	- Write the exact symptom in one sentence.
35	- Record expected behavior.
36	- Record actual behavior.
37	- Capture environment assumptions.
38	- Capture whether the issue is deterministic or flaky.
39	- Capture whether it is new, old, or recently regressed.
40	- Avoid editing code during this phase.
41
42	## Phase 2: Reproduce The Failure
43
44	- Find the smallest reproducible path.
45	- Prefer automated reproduction over manual UI clicking.
46	- Save the failing command when possible.
47	- If no test exists, create a reproduction harness.
48	- Record exact inputs, flags, and fixtures.
49	- If the bug is flaky, measure frequency instead of pretending it is stable.
50
51	## Phase 3: Narrow The Surface Area
52
53	- Identify likely subsystem boundaries.
54	- Diff recent changes when history is relevant.
55	- Check whether the failure begins before or after I/O boundaries.
56	- Compare passing and failing code paths.
57	- Use binary search over scope when the change window is large.
58	- Reduce the problem before adding more instrumentation.
59
60	## Phase 4: Instrument The System
61
62	- Add temporary logging only where uncertainty exists.
63	- Prefer cheap inspection over permanent noisy logging.
64	- Log invariant checkpoints, not everything.
65	- Print or inspect the variables that decide branching behavior.
66	- If async behavior is involved, log timestamps and ordering.
67	- Remove temporary instrumentation after the fix unless it becomes useful observability.
68
69	## Phase 5: Generate Hypotheses
70
71	- Generate multiple plausible causes, not one favorite theory.
72	- Rank hypotheses by explanatory power and test cost.
73	- Prefer hypotheses that explain all observed symptoms.
74	- Write down what evidence would falsify each one.
75	- Do not patch based on intuition alone.
76
77	## Phase 6: Prove Or Kill Hypotheses
78
79	- Design the smallest experiment that differentiates the top hypotheses.
80	- Run one high-signal experiment at a time.
81	- Keep notes on what each result means.
82	- Kill hypotheses aggressively when evidence contradicts them.
83	- Escalate instrumentation only when the current evidence is insufficient.
84
85	## Phase 7: Patch The True Cause
86
87	- Change only the code implicated by evidence.
88	- Prefer the smallest change that restores the invariant.
89	- Avoid bundling unrelated cleanup in the debug patch.
90	- If the bug exposed a missing boundary, add the boundary explicitly.
91	- Preserve readability even for emergency fixes.
92
93	## Phase 8: Verify The Fix
94
95	- Re-run the original reproduction.
96	- Re-run nearby tests.
97	- Check negative cases, not just the positive happy path.
98	- Validate that logs or state transitions now match expectation.
99	- If the bug was flaky, run enough repetitions to earn confidence.
100
101	## Phase 9: Add Regression Protection
102
103	- Add or strengthen a test that would have caught the bug.
104	- Place the test at the lowest layer that reliably expresses the defect.
105	- If a test is impossible, document the missing seam.
106	- Prefer deterministic tests over timing-sensitive ones.
107
108	## Phase 10: Save The Lesson
109
110	- Save a durable memory entry if the issue reflects a reusable pattern.
111	- Save a trajectory if the investigation is valuable for QA or training data.
112	- Update docs only if the bug revealed a workflow or contract gap.
113
114	## Evidence Sources
115
116	- failing tests
117	- stack traces
118	- logs
119	- diffs
120	- recent commits
121	- config files
122	- environment variables
123	- production reports
124	- screenshots or traces
125
126	## Useful Commands
127
128	```bash
129	pytest -k "failing_case" -vv
130	rg "relevant_symbol\|error_text" .
131	git diff --stat
132	git log --oneline -- path/to/file
133	```
134
135	## Decision Rules
136
137	- If you cannot reproduce the issue, stop calling it fixed.
138	- If two symptoms disagree, debug t

People who liked this also viewed

6 picks

Type