debugging-methodology

Name: debugging-methodology
Author: DevelopersGlobal

64stars10forks

How to install debugging-methodology?

developersglobal/ai-agent-skills/debugging-methodology

$npx -y skills add DevelopersGlobal/ai-agent-skills --skill debugging-methodology

Installs into the current project.

Summary

Systematic root cause analysis for production and development bugs. Hypothesis-driven debugging — never guess-and-check.

Files · 1

View on GitHub

SKILL.md

1	## Overview
2
3	Random code changes in response to errors are not debugging — they're noise generation. This skill enforces a systematic, hypothesis-driven approach: understand the problem, form a hypothesis, test it, confirm the root cause, then fix.
4
5	AI agents often cycle through random fixes until something "works." This skill prevents that.
6
7	## When to Use
8
9	- Any time a test fails unexpectedly
10	- Any time you encounter an error or exception
11	- When behavior differs between environments
12	- When performance degrades unexpectedly
13
14	## Process
15
16	### Step 1: Reproduce Reliably
17
18	1. Before doing anything else: reproduce the bug reliably. If you can't reproduce it, you can't fix it.
19	2. Write a failing test that captures the bug — this becomes your regression test.
20	3. Note the exact conditions that trigger the bug: inputs, environment, sequence of actions.
21
22	Verify: You can trigger the bug on demand.
23
24	### Step 2: Understand Before Diagnosing
25
26	4. Read the full error message — not just the first line.
27	5. Read the stack trace from bottom to top — the root cause is usually near the bottom.
28	6. Identify: What was the program trying to do? What happened instead?
29
30	Verify: You can explain the bug in one sentence without using the word "error."
31
32	### Step 3: Form a Hypothesis
33
34	7. Based on what you know, form a specific hypothesis: "I think the bug is X because Y."
35	8. The hypothesis must be falsifiable — you can design a test that proves or disproves it.
36	9. Do not start making code changes until you have a hypothesis.
37
38	Verify: Your hypothesis is specific enough to design a test for.
39
40	### Step 4: Test the Hypothesis
41
42	10. Add targeted logging or a targeted test that confirms or refutes the hypothesis.
43	11. Run it. Read the output carefully.
44	12. If the hypothesis is wrong: update your understanding, form a new hypothesis, repeat.
45	13. If the hypothesis is right: you've found the root cause.
46
47	Verify: Root cause is confirmed by evidence, not assumed.
48
49	### Step 5: Fix the Root Cause (Not the Symptom)
50
51	14. Fix the root cause — not the symptom. Suppressing an error message is not a fix.
52	15. Make the minimum change that fixes the root cause.
53	16. Run the failing test you wrote in Step 1 — it should now pass.
54	17. Run the full test suite — no regressions.
55
56	Verify: The specific failing test now passes. Full suite still passes.
57
58	### Step 6: Prevent Recurrence
59
60	18. If the bug wasn't caught by existing tests: add a test that would have caught it.
61	19. If the bug was caused by a bad assumption: document the assumption or add a guard.
62	20. Consider: does this class of bug exist elsewhere in the codebase?
63
64	## Common Rationalizations (and Rebuttals)
65
66	\| Excuse \| Rebuttal \|
67	\|--------\|----------\|
68	\| "Let me just try this and see" \| Random changes produce random results. Form a hypothesis first. \|
69	\| "It must be a framework bug" \| It's almost never the framework. Prove it before blaming it. \|
70	\| "Works on my machine" \| Environment differences are root causes. Find them. Don't dismiss them. \|
71	\| "I'll add a try/catch" \| That hides the bug. Find and fix the root cause. \|
72
73	## Red Flags
74
75	- Making code changes before understanding the bug
76	- Adding try/catch to silence errors without investigating root cause
77	- "I'll try this and see if it helps"
78	- Assuming the bug is in a dependency before proving it
79	- Fixing the symptom (error message) rather than the cause
80
81	## Verification
82
83	- [ ] Bug reproducible on demand
84	- [ ] Root cause identified (not just symptom)
85	- [ ] Fix targets root cause, not symptom
86	- [ ] Reproduction test written and now passes
87	- [ ] Full test suite passes with no regressions
88	- [ ] Regression test added to prevent future occurrence
89
90	## References
91
92	- [test-driven-development skill](../test-driven-development/SKILL.md)
93	- [observability skill](../observability/SKILL.md)

People who liked this also viewed

6 picks

Type

azure-diagnosticsDebug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deploySkillsJul 2026472k1.3k
systematic-debuggingUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesSkillsJul 2026197k259k
safe-debugRigor Debug / Rigor Audit skill for deep learning research work. Use when the user pastes a traceback, terminal error, CUDA OOM, checkpoint load failure, shape mismatch, NaN loss symptom, or training SkillsMay 2026161k507
explore-runRigor Improve / Rigor Explore run leaf skill for bounded exploratory evidence in deep learning research repositories. Use when the researcher explicitly authorizes exploratory runs such as small-subseSkillsMay 2026161k507
minimal-run-and-auditRigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation SkillsMay 2026161k507
insforge-debugUse when diagnosing problems in an InsForge project — reactive failures (SDK error object, HTTP 4xx/5xx, gateway timeout 502/503/504, edge function failure or timeout, login/OAuth/auth errors, RLS denSkillsJul 202618k31

debugging-methodology

64stars10forks

View on GitHub

How to install debugging-methodology?

developersglobal/ai-agent-skills/debugging-methodology

$npx -y skills add DevelopersGlobal/ai-agent-skills --skill debugging-methodology

Installs into the current project.

Summary

Systematic root cause analysis for production and development bugs. Hypothesis-driven debugging — never guess-and-check.

Files · 1

View on GitHub

SKILL.md

1	## Overview
2
3	Random code changes in response to errors are not debugging — they're noise generation. This skill enforces a systematic, hypothesis-driven approach: understand the problem, form a hypothesis, test it, confirm the root cause, then fix.
4
5	AI agents often cycle through random fixes until something "works." This skill prevents that.
6
7	## When to Use
8
9	- Any time a test fails unexpectedly
10	- Any time you encounter an error or exception
11	- When behavior differs between environments
12	- When performance degrades unexpectedly
13
14	## Process
15
16	### Step 1: Reproduce Reliably
17
18	1. Before doing anything else: reproduce the bug reliably. If you can't reproduce it, you can't fix it.
19	2. Write a failing test that captures the bug — this becomes your regression test.
20	3. Note the exact conditions that trigger the bug: inputs, environment, sequence of actions.
21
22	Verify: You can trigger the bug on demand.
23
24	### Step 2: Understand Before Diagnosing
25
26	4. Read the full error message — not just the first line.
27	5. Read the stack trace from bottom to top — the root cause is usually near the bottom.
28	6. Identify: What was the program trying to do? What happened instead?
29
30	Verify: You can explain the bug in one sentence without using the word "error."
31
32	### Step 3: Form a Hypothesis
33
34	7. Based on what you know, form a specific hypothesis: "I think the bug is X because Y."
35	8. The hypothesis must be falsifiable — you can design a test that proves or disproves it.
36	9. Do not start making code changes until you have a hypothesis.
37
38	Verify: Your hypothesis is specific enough to design a test for.
39
40	### Step 4: Test the Hypothesis
41
42	10. Add targeted logging or a targeted test that confirms or refutes the hypothesis.
43	11. Run it. Read the output carefully.
44	12. If the hypothesis is wrong: update your understanding, form a new hypothesis, repeat.
45	13. If the hypothesis is right: you've found the root cause.
46
47	Verify: Root cause is confirmed by evidence, not assumed.
48
49	### Step 5: Fix the Root Cause (Not the Symptom)
50
51	14. Fix the root cause — not the symptom. Suppressing an error message is not a fix.
52	15. Make the minimum change that fixes the root cause.
53	16. Run the failing test you wrote in Step 1 — it should now pass.
54	17. Run the full test suite — no regressions.
55
56	Verify: The specific failing test now passes. Full suite still passes.
57
58	### Step 6: Prevent Recurrence
59
60	18. If the bug wasn't caught by existing tests: add a test that would have caught it.
61	19. If the bug was caused by a bad assumption: document the assumption or add a guard.
62	20. Consider: does this class of bug exist elsewhere in the codebase?
63
64	## Common Rationalizations (and Rebuttals)
65
66	\| Excuse \| Rebuttal \|
67	\|--------\|----------\|
68	\| "Let me just try this and see" \| Random changes produce random results. Form a hypothesis first. \|
69	\| "It must be a framework bug" \| It's almost never the framework. Prove it before blaming it. \|
70	\| "Works on my machine" \| Environment differences are root causes. Find them. Don't dismiss them. \|
71	\| "I'll add a try/catch" \| That hides the bug. Find and fix the root cause. \|
72
73	## Red Flags
74
75	- Making code changes before understanding the bug
76	- Adding try/catch to silence errors without investigating root cause
77	- "I'll try this and see if it helps"
78	- Assuming the bug is in a dependency before proving it
79	- Fixing the symptom (error message) rather than the cause
80
81	## Verification
82
83	- [ ] Bug reproducible on demand
84	- [ ] Root cause identified (not just symptom)
85	- [ ] Fix targets root cause, not symptom
86	- [ ] Reproduction test written and now passes
87	- [ ] Full test suite passes with no regressions
88	- [ ] Regression test added to prevent future occurrence
89
90	## References
91
92	- [test-driven-development skill](../test-driven-development/SKILL.md)
93	- [observability skill](../observability/SKILL.md)

People who liked this also viewed

6 picks

Type