Track Down the Root Cause of Bugs with systematic-debugging
機械翻訳 / Machine-translated
機械翻訳 / Machine-translated
Original article: Track Down the Root Cause of Bugs with systematic-debugging (cccskills)
Skill page: systematic-debugging
Key takeaways from this article
With systematic-debugging installed, Claude Code and Codex will verify the cause of a bug or test failure before attempting a fix.
It is a skill that proceeds step by step — forming hypotheses from reproduction steps, logs, and recent changes, verifying them, and finally confirming the fix with a failing test.
This article covers the four stages of investigation, how to install the skill, example prompts, and things to keep in mind when using it.
With systematic-debugging installed, the agent will not propose a fix until the cause has been confirmed.
For example, suppose you ask:
Reproduce this test failure and investigate the cause from recent changes and logs.
The agent starts by reading the error message and stack trace all the way through, noting line numbers, file paths, and error codes.
It then runs the test to confirm whether the failure is consistently reproducible.
Next, it reviews git diff, recent commits, and any changes to dependencies or configuration.
Even if the issue cannot be reproduced, it does not guess at a fix — instead it collects additional data.
Once candidate causes become visible, the agent compares the broken code against similar code in the same codebase that works correctly, listing small differences one by one.
From there, it formulates a single hypothesis in the form of "the cause is X because Y."
It then verifies that hypothesis with the smallest possible change.
If the hypothesis is wrong, it does not pile on more fixes — it forms a new hypothesis from scratch.
Even when a hypothesis proves correct, the agent does not immediately edit the code.
It first writes a failing test that reproduces the defect, then introduces exactly one fix targeting the root cause.
Only after confirming that the test passes and no other tests have broken does it return the result.
systematic-debugging is a skill that breaks debugging into four stages and prevents the agent from advancing to the next stage until the previous one is complete.
The central principle is "do not fix before investigating the root cause" — a fix that only removes the symptom is treated as a failure.
Here is what each stage entails:
| Stage | What the agent does | Condition to advance |
|---|---|---|
| 1. Root cause investigation | Read the error, reproduce it, review recent changes, gather evidence | Understands what is happening and why |
| 2. Pattern analysis | Find comparable working examples or reference implementations and compare | Can identify the difference from the broken code |
| 3. Hypothesis and verification | Form one hypothesis, test it with a minimal change | Hypothesis is confirmed (if wrong, form a new one) |
| 4. Implementation | Write a failing test, apply one fix, verify | Defect is resolved and tests pass |
For defects that span multiple layers, diagnostic logging is added before any fix is attempted.
This applies to flows such as CI → build → signing, or API → service → database.
At the boundary of each layer, the agent records incoming and outgoing data as well as any handoff of environment variables and configuration.
It then runs the process once to determine where the problem occurs.
Only after identifying the problematic layer does it investigate that layer in detail.
When an error surfaces deep in the call stack, the agent traces backward through callers to find where the invalid value originated.
The principle is to apply the fix at the point where the value is produced, not at the point where the symptom appears.
This backward-tracing procedure comes with explanatory notes.
How to validate input at multiple layers after the cause is found, and how to replace fixed wait times with condition checks, are also covered in those notes.
The agent counts each fix attempt, and after 3 or more failures it will not proceed to a fourth fix.
A state where every fix introduces a new problem elsewhere, or where a fix would require a large-scale rewrite, is treated as a problem with the design itself.
At this point the agent stops applying additional fixes and consults the user about whether to revisit the design.
After exhausting the investigation, it may become clear that the cause is environmental, timing-related, or external.
In that case, the findings are recorded and the issue is addressed with retries, timeouts, or improved error messages.
Monitoring and logging are also added in preparation for the next investigation.
systematic-debugging is one of the skills included in obra/superpowers on GitHub.
The repository has 309,845 stars.
The same repository contains other skills aligned with the development workflow, such as brainstorming and code review.
Running the following command in your terminal adds only systematic-debugging from obra/superpowers.
The target agent — Claude Code, Codex, or another — is selected at runtime.
npx skills add https://github.com/obra/superpowers --skill systematic-debugging
If you prefer to let the agent handle it, send the following message as-is.
Because the wording asks for a content review first, the agent will confirm there is no suspicious behavior before proceeding with the installation.
次の Agent Skill をインストールしてください。
https://github.com/obra/superpowers/tree/main/skills/systematic-debugging
まず SKILL.md と付属ファイルの中身を確認し、不審な処理（外部への送信、認証情報の読み取りなど）がないことを確かめてから、Claude Code なら ~/.claude/skills/systematic-debugging/、Codex なら ~/.agents/skills/systematic-debugging/ に配置してください。
The installation location depends on which agent you use and the desired scope.
| Agent | Use across all projects | Use for a specific project only |
|---|---|---|
| Claude Code | ~/.claude/skills/systematic-debugging/ | .claude/skills/systematic-debugging/ in the project |
| Codex | ~/.agents/skills/systematic-debugging/ | .agents/skills/systematic-debugging/ in the project |
A quick way to confirm the installation is to check whether SKILL.md exists inside the folder.
If you installed it globally for Claude Code, you can display the contents with the following command:
ls ~/.claude/skills/systematic-debugging/
If you see SKILL.md alongside explanatory Markdown files, TypeScript examples, and shell scripts, the installation is complete.
This skill is designed to be used before a fix is proposed.
The right moment is when you encounter a bug, a test failure, or unexpected behavior.
Including the symptom and the scope you want investigated in your prompt gives the investigation a clear starting point.
Login tests have been failing since yesterday.
Before fixing anything, reproduce the issue and review recent commits to identify the cause.
What comes back is whether the issue was reproduced, any related commits or configuration changes, and a hypothesis backed by evidence.
After the hypothesis is confirmed, a failing test and a single fix follow.
Trace the flow from the API through to the database and confirm where an invalid value is being introduced.
This is a prompt for tracking down a production defect.
The agent inserts diagnostic logging at each layer boundary, runs the process once, and shows which layer is producing the bad value.
The fix is then proposed at the point where the invalid value originates.
The CI build is failing at the signing step.
Check what is being passed at each stage — the workflow, the build script, and the signing step.
For build or integration failures, the agent adds per-stage checks to isolate the problem.
Secrets are shown as "set / not set" rather than their actual values, and the keychain state is also checked.
This leads to a conclusion like "the value reaches the workflow but is not passed to the build script," pinpointing the problematic stage.
How far the investigation progresses depends on what you provide at the start.
This skill does not guess at fixes for defects that cannot be reproduced — it returns to data collection instead.
The more you provide upfront — reproduction steps, the full error message, logs, and when the issue first appeared — the faster the investigation will close in on the cause.
Final review of any changes is done by a human.
It is also worth checking that diagnostic logging or verification code added during the investigation has not been left in the fix commit.
When fixes have failed three or more times, the agent will initiate a design discussion.
Whether to continue or start over is the user's decision to make.
The procedures for writing failing tests and for verification before completion refer to two other skills in the same superpowers repository (test-driven development and pre-completion verification).
If you have only installed systematic-debugging, those instructions will not be available.
Add them from the repository if needed.
The license is MIT.
SKILL.md is written in English, and the accompanying files include shell scripts and TypeScript examples.
Please read through SKILL.md and the accompanying files before installing.
The same obra/superpowers repository contains skills you can use before and after debugging.
dispatching-parallel-agents is a skill that assigns independent defects or test failures to separate agents for parallel investigation and fixing.
When failures are appearing in multiple places at once, it can be used to distribute the systematic-debugging investigation across agents.
requesting-code-review is a skill for asking a separate agent to review code after implementation or before merging.
It is useful when you want a second set of eyes on changes after the root cause has been fixed.
finishing-a-development-branch is a skill that confirms all tests pass and then lets you choose to merge or create a Pull Request.
It lets you hand off the cleanup of a fixed branch without interruption.
Yes.
The skill takes the position that even seemingly simple problems have a root cause, and it is designed to follow the procedure especially when you are in a hurry.
For straightforward bugs, each stage is expected to be brief.
Yes.
Situations where multiple fixes have already been tried, or where previous fixes did not work, are explicitly listed as prime use cases for this skill.
If there have been three or more failures, the flow moves to a design discussion before any further fixes are attempted.
If the cause turns out to be environmental, timing-related, or external, the findings are recorded and the issue is addressed with retries, timeouts, and so on.
Monitoring and logging are then added to assist the next investigation.
That said, most "no cause found" outcomes are treated as insufficient investigation, so the first thing to suspect is gaps in the investigation itself.
Yes.
Either select Codex as the target when running the install command, or place the files at ~/.agents/skills/systematic-debugging/.
For project-scoped use, place them in the project's .agents/skills/ directory.
systematic-debugging is a skill that enforces the order "do not fix until the root cause has been investigated" on the agent.
It proceeds one stage at a time — reading the error, reproducing it, reviewing the change history, verifying hypotheses, and confirming the fix with a failing test.
Because the agent switches to a design discussion after three failures, it stops the cycle of repeated ad-hoc patches.
If the fixes you've been asking AI to apply keep repeating the same failures, try installing this skill and letting it start from the investigation.
This article is a reprint of the cccskills feature "Track Down the Root Cause of Bugs with systematic-debugging."
Full details about the skill and installation instructions can be found on the cccskills systematic-debugging page.