Preface¶

Debugging is an unavoidable part of a developer’s daily work. When a Bug occurs, human engineers follow a familiar workflow: reproduce the issue first, narrow down the scope, form hypotheses, validate with evidence, and finally make a minimal fix. But when you hand the problem to an AI programming assistant, the common outcome is that the Agent will make several consecutive code changes and add a bunch of defensive judgments. Sometimes the problem is fixed by chance, but sometimes new regressions are introduced, and you can’t even tell what exactly it found.

systematic-debugging was built to solve this pain point: originating from the community-curated repository awesome-cursor-skills, it encodes the structured debugging workflow of “Reproduce → Isolate → Hypothesize → Verify → Fix” into SKILL.md, teaching Agents to troubleshoot step-by-step instead of randomly modifying code and gambling on luck. It is worth installing for developers who often use tools like Cursor, Claude Code, etc., to help debug Bugs.

What is This¶

systematic-debugging is an Agent Skill from the awesome-cursor-skills project maintained by Spencer Pauly, categorized under the Workflow skills.

Its frontmatter is defined as follows:

---
name: systematic-debugging
description: Structured debugging methodology — reproduce, isolate, hypothesize, verify. Covers git bisect, binary search, logging, and minimal reproduction.
user-invocable: true
---

One-sentence positioning: Constraining AI’s debugging behavior with reproducible steps — first obtain a stable reproduction path, then narrow down the fault scope, form a testable hypothesis, verify it with minimal experiments, and finally make a minimal fix and perform regression testing. The Skill body explicitly states “Debug methodically instead of randomly changing code”, which is the core difference between it and ordinary “help me fix the Bug” prompts.

This Skill follows the universal SKILL.md open format and can be used in tools that support Agent Skills such as Cursor, Codex CLI, Claude Code, etc.; the installation directories vary slightly across different tools, which will be explained separately below.

Core Features and Highlights¶

Five-Step Debugging Workflow¶

The Skill breaks down debugging into five phases, and the Agent should proceed in order instead of skipping steps and making random changes:

1. Reproduce

Before modifying any code, you must first reliably reproduce the Bug:
- Record the exact steps that trigger the issue
- Clarify the difference between the “expected behavior” and the “actual behavior”
- Confirm whether the problem can be reproduced stably (rather than sporadically)
- Record the runtime environment: operating system, Node version, browser, etc.

The Skill states it very directly: “If you can’t reproduce it, you can’t fix it.” — If you cannot reproduce the issue, continue asking the user for details instead of guessing out of thin air.

2. Isolate

Narrow down the fault scope step by step. The Skill provides three common methods:

Binary search of the codebase: Comment out half of the logic to see if the Bug still occurs; continue the binary search in the remaining half based on the result until you locate the specific module.

Git bisect: Suitable for scenarios where “it used to work but broke after a certain commit”. The official complete command flow is given:

git bisect start
git bisect bad          # Current commit is broken
git bisect good <sha>   # This commit is still good
# Git checks out the intermediate version — test it
git bisect good         # Or git bisect bad
# Repeat until you find the first broken commit
git bisect reset        # Reset after completion

Isolate by layer: Strip away layers one by one from dimensions such as frontend/backend, database, API, individual components, etc. — check the Network panel, directly curl the interface, render components individually, and determine which layer the problem falls into.

3. Hypothesize

Require the Agent to form specific, testable hypotheses instead of vague conclusions. The Skill gives positive and negative examples:
- Bad: “The data seems to have problems”
- Good: “userId is null because the auth middleware was not executed on this route”

4. Test the Hypothesis

Use minimal experiments to prove or disprove the hypothesis:
- Add console.log or breakpoints at suspicious locations
- Check the actual values of suspected variables
- If the hypothesis is wrong, return to step 3; if the hypothesis is correct, you have found the root cause

5. Fix and Verify
- Make minimal changes to fix the root cause instead of covering up symptoms
- Confirm that the Bug has been fixed using the original reproduction steps
- Check if any regressions have been introduced
- Add a test case that can catch this type of Bug

Scenario-based Debugging Tool Cheat Sheet¶

The Skill also organizes a “scenario → tool” comparison table to help the Agent quickly select the right method:

Common Bug Pattern Checklist¶

The Skill lists typical patterns that the Agent should pay attention to first, including: Off-by-one errors, Null/undefined values, race conditions, React stale closure, type coercion (== vs ===), missing await, inconsistencies between local, CI, and production environments, etc. This is not a mystical checklist, but rather encodes human debugging experience into check items to reduce the Agent’s repeated detours into common pitfalls.

Four Golden Rules¶

• Never guess — always verify with evidence
• Fix the root cause, not the symptom
• Step back and re-isolate if no progress is made in 15 minutes
• Record the solutions you have tried to avoid repeating failed paths

user-invocable: true means that users can also explicitly call it via /systematic-debugging in the Agent conversation, forcing the Agent to follow this workflow.

Installation and Activation¶

All Skills in awesome-cursor-skills are “copy-and-use”: just put the SKILL.md into the corresponding tool’s skills directory, no additional dependencies or compilation required.

Installation in Cursor¶

Method 1: Manual copy (recommended, easy for team sharing)
1. Get the file from the official repository:
https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/systematic-debugging

2. Create a directory in the project root and place SKILL.md inside:

mkdir -p .cursor/skills/systematic-debugging
# Copy SKILL.md to .cursor/skills/systematic-debugging/SKILL.md

3. Restart Cursor or reopen the project, and the Agent will automatically discover this Skill.

According to the Cursor official Skills documentation, Cursor will scan for Skills from the following locations:

It is recommended that the folder name match the name in the frontmatter (lowercase, hyphenated), i.e. systematic-debugging.

Method 2: Import from GitHub
Cursor supports importing via Customize → Rules → Add Rule → Remote Rule (Github) by filling in the repository address; you can also use the built-in /migrate-to-skills to migrate old rules to the Skill format.

Usage in Claude Code / Codex CLI¶

These tools also recognize the universal SKILL.md format. Claude Code usually reads .claude/skills/ or .agents/skills/ under the project; Codex CLI reads directories such as .codex/skills/ (Cursor documentation also mentions that it will scan these paths for compatibility). Just copy the systematic-debugging directory to the skills root directory of the corresponding tool, please refer to the current documentation of each tool for details.

After installation, you can see the loaded Skill in the Cursor Settings → Rules → Agent Decides area; the description field will help the Agent judge when to enable it automatically.

Typical Usage Examples¶

Automatic Trigger¶

When you describe a Bug in the Agent conversation, for example:

After logging in and jumping to the personal page, the username displays as empty, but the data returned by the interface in Network is correct.

The Agent will automatically match and load systematic-debugging based on keywords such as reproduce, isolate, hypothesize, verify in the description, and proceed according to the five-step process: first let you confirm the reproduction steps and environment, then suggest checking the Network, isolating the frontend rendering layer, putting forward assumptions like “props not passed”, and verifying with minimal logs.

Explicit Call¶

If you want to force a structured workflow, enter the following in the Agent input box:

/systematic-debugging

Then describe the problem. user-invocable: true ensures that this Skill can be directly invoked as a slash command, which is suitable for scenarios where the Agent previously “made random changes” and you need it to restart the process according to the methodology.

Git bisect Collaboration Example¶

Suppose you know that v1.2.0 works normally and the current main branch is abnormal, you can let the Agent execute under the guidance of systematic-debugging:

git bisect start
git bisect bad HEAD
git bisect good v1.2.0-tag
# In each round: run the test or manually verify → git bisect good/bad
git bisect reset

The Skill requires the Agent to record each test result during the bisect process, and finally pinpoint the commit that introduced the regression, instead of blindly modifying code in a large diff range.

Cooperate with “Minimal Reproduction”¶

During the isolation phase, the Skill emphasizes constructing a minimal reproducible example — remove irrelevant dependencies and branches, only keep the necessary code that triggers the Bug. This is especially important for AI: the smaller the context, the less likely the Agent will be distracted by irrelevant files, and the easier it is to verify hypotheses.

Applicable Scenarios and Notes¶

Who and what scenarios it is suitable for:
- Developers who usually let AI help debug Bugs but are tired of “making ten changes and gambling on luck”
- Regression issues, sporadic problems, environment difference issues, requiring the Agent to reproduce first before taking action
- Teams that want to write debugging SOP into the repository, allowing new members and Agents to follow the same workflow
- Technical leaders who want to reduce the risk of silent regressions introduced by AI

Notes:
1. The Skill is a methodology, not a universal patch. It teaches the Agent how to investigate, not replaces your judgment on business logic; complex distributed systems may also need to be combined with distributed tracing, APM and other tools.
2. For Bugs with high reproduction costs (only in production, extremely low probability), the Skill will also suggest asking for details and environment comparisons. The Agent may still not be able to locate them in one go, requiring manual cooperation to provide logs and data.
3. Do not mix with “quick random changes”. If you also prompt “never mind, just change everything directly” in the same conversation, it may dilute the Skill’s constraints; using the explicit /systematic-debugging command will yield better results.
4. Update with the repository. awesome-cursor-skills is continuously maintained, it is recommended to regularly git pull or re-copy to get new Bug patterns or tool suggestions.
5. Team specifications can be extended secondarily. You can fork this Skill within the project, add team-specific logging specifications, test commands, or prohibited operations (such as “prohibit modifying production configurations before reproduction”).

Summary¶

Debugging capabilities cannot omit methodology just because it is executed by AI. systematic-debugging encodes the common sense of engineers such as reproduction, isolation, hypothesis, verification, and minimal repair into SKILL.md, allowing Agents to have rules to follow when troubleshooting, make fewer invalid changes, and leave more traceable evidence. For users of AI programming tools, this is a lightweight, zero-dependency, copy-and-use Workflow Skill, which is worth putting into .cursor/skills/ to try out.

Official Skill address:
https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/systematic-debugging

awesome-cursor-skills project homepage:
https://github.com/spencerpauly/awesome-cursor-skills