systematic-debugging
Four-phase root cause investigation for bugs and unexpected behavior
Install / Use
npx skills add taracodlabs/aiden --skill systematic-debuggingInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of systematic-debugging
systematic-debugging scores 85/100 on our quality scale, 2738th of 4,702 Development & Engineering skills we index.
Its SKILL.md is 4.6 KB long, well organised into 14 sections with 7 code examples: a solid amount of guidance for an agent.
It has 843 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so systematic-debugging is actively maintained.
- Our last check on 2026-11-05 found the source still online.
- It is released under AGPL-3.0, a copyleft license: you can use it, but modified versions you distribute must carry the same license.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit ā read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-06. Automated pattern scan on 2026-10-06. It catches known dangerous patterns, not every risk ā read a skill before letting an agent act on it.
systematic-debugging compared with similar skills
All 4 of these similar skills score higher than systematic-debugging; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| systematic-debugging (this skill)by taracodlabs | 85 | 843 | 2mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 117.6k | 9d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.3k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.4k | 3d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.7k | today | MCP Server |
Frequently asked questions
- How do I install systematic-debugging?
- Run
npx skills add taracodlabs/aiden --skill systematic-debugging. The install tabs above show the steps for each supported agent. - Which AI agents does systematic-debugging work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is systematic-debugging safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is AGPL-3.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is systematic-debugging still maintained?
- The repository was last updated about 2 months ago, so systematic-debugging is actively maintained.
Skill content
View source on GitHubname: systematic-debugging description: Four-phase root cause investigation for bugs and unexpected behavior category: developer version: 1.0.0 origin: aiden license: Apache-2.0 tags: debugging, root-cause, investigation, bug, error, diagnosis, troubleshooting, logs, testing
Systematic Debugging
A structured four-phase process for diagnosing software bugs: Reproduce ā Isolate ā Hypothesize ā Verify. Prevents guessing and ensures you find the root cause, not just a workaround.
When to Use
- User reports a bug or unexpected behavior without an obvious cause
- An error message appears but the source is unclear
- A fix was applied but the problem persists
- Tests are failing intermittently (flaky tests)
- Production behavior differs from local behavior
How to Use
Phase 1: Reproduce reliably
A bug you can reproduce consistently is halfway solved.
1. Get the exact error message, stack trace, and environment
2. Identify exact steps to trigger the bug
3. Confirm the bug happens in a clean environment (not just local state)
4. Record: OS, runtime version, dependencies, config values
5. Try: does it fail on every run, or only sometimes?
If intermittent: add timing, logging, or retry logic to isolate the trigger.
Phase 2: Isolate the failure
Narrow the failure to the smallest possible unit.
1. Add logging before/after suspected areas to find where state diverges
2. Binary search through code: comment out half, does it still fail?
3. Check: when did this last work? (git log, git bisect)
4. Check: what changed recently? (git diff main, dependency updates)
5. Reproduce in a minimal test case ā strip away all unrelated code
# git bisect to find the breaking commit
git bisect start
git bisect bad # current commit is broken
git bisect good v2.0.0 # last known good tag
# git will checkout commits ā test each, then:
git bisect good # or
git bisect bad
# Repeat until git identifies the culprit commit
git bisect reset
Phase 3: Generate hypotheses
Form 2-3 specific, testable hypotheses about the root cause.
Bad hypothesis: "Something is wrong with the database"
Good hypothesis: "The connection pool is exhausted under concurrent load
because maxConnections defaults to 5 in test config"
For each hypothesis:
- What evidence supports it?
- What evidence would refute it?
- What one-line change would test it?
Rank by probability and test from most to least likely.
Phase 4: Verify and fix
Prove the fix, not just that the error goes away.
1. Apply the smallest change that addresses the root cause
2. Run the original reproduction steps ā confirm bug is gone
3. Run the full test suite ā confirm no regressions
4. Check edge cases: empty input, null values, concurrent access
5. Write a regression test that would have caught this bug
# Regression test template
def test_issue_42_connection_pool_exhaustion():
"""
Regression test: ensure concurrent requests don't exhaust the connection pool.
Root cause: maxConnections was not configurable; defaulted to 5 in test.
Fixed in commit abc123.
"""
results = run_concurrent_requests(count=20)
assert all(r.status_code == 200 for r in results), "Some requests failed under concurrency"
Debugging cheat sheet
Error: KeyError / undefined ā check input shapes; add null guard
Error: Off-by-one ā examine loop bounds and index math
Error: Works locally, fails in CI ā check env vars, file paths, timing
Error: Works first run, fails after ā check state mutation, cache, side effects
Error: Inconsistent / race condition ā check shared mutable state, locks
Error: Memory leak ā profile allocations; check event listener cleanup
Examples
"My API returns 500 randomly but I can't reproduce it" ā Start at Phase 1 ā add structured logging with request IDs. Once patterns emerge, apply Phase 2 binary search.
"Tests pass locally but fail in GitHub Actions" ā Phase 2: diff the environments (OS, Node version, env vars). Often caused by missing env vars or OS path differences.
"I fixed the bug but it came back after a week" ā Phase 4: add a regression test and check if the root cause fix addressed the underlying issue or just a symptom.
Cautions
- Never apply multiple changes at once when debugging ā you won't know which one fixed it
- "Works on my machine" is a Phase 1 failure ā always reproduce in the target environment
- Logs and print statements are powerful ā do not underestimate them in favor of complex tooling
- Document the root cause in the fix commit message so future developers understand why the change was made
Related Skills
taste-skill
117.6kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.3kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.4kA visual, example-driven guide to Claude Code ā from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.7k𤯠LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit ā see the Safety scan above for what the skill file itself contains.
