SkillAgentSearch skills...

systematic-debugging

Four-phase root cause investigation for bugs and unexpected behavior

Install / Use

npx skills add taracodlabs/aiden --skill systematic-debugging

Installs into whichever agent you are using.

About this skill
šŸ“„

SKILL.md

Installable skill definition

Quality Score

85/100

Supported Platforms

Universal

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.

Substance
26/30
Structure
20/20
Description
12/15
Adoption
12/20
Freshness
15/15

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 found

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.

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.

SkillScoreStarsUpdatedFormat
systematic-debugging (this skill)by taracodlabs858432mo agoSKILL.md
taste-skillby Leonxlnx100117.6k9d agoCLAUDE.md
ai-job-searchby ai-job-search-dev10072.3ktodayCLAUDE.md
claude-howtoby luongnv8910047.4k3d agoCLAUDE.md
lobehubby lobehub10085.7ktodayMCP 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.

name: 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

View on GitHub
GitHub Stars843
CategoryDevelopment
Updated2mo ago
Forks147

Languages

TypeScript

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions
systematic-debugging — Universal Skill: Install & Safety Check | SkillAgent