# Debugging Systematic

> Systematic debugging methodology — binary search isolation, hypothesis-driven debugging, reproducing issues, and root cause analysis. Use when debugging errors, unexpected behavior, or test failures.

- **Type:** Skill
- **Install:** `agentstack add skill-claude-code-community-ireland-claude-code-resources-debugging-systematic`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Claude-Code-Community-Ireland](https://agentstack.voostack.com/s/claude-code-community-ireland)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Claude-Code-Community-Ireland](https://github.com/Claude-Code-Community-Ireland)
- **Source:** https://github.com/Claude-Code-Community-Ireland/claude-code-resources/tree/main/plugins/vibeworks-library/skills/debugging-systematic

## Install

```sh
agentstack add skill-claude-code-community-ireland-claude-code-resources-debugging-systematic
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Systematic Debugging Methodology

## Core Principle

Debugging is not guessing. It is a scientific process: observe the symptom, form a hypothesis, predict the outcome of a test, and run the test. Repeat until the root cause is found.

---

## The Scientific Debugging Method

### Step 1: OBSERVE — Gather Evidence

Before changing anything, collect all available information.

**Checklist:**
- [ ] Read the FULL error message, not just the first line.
- [ ] Read the FULL stack trace. Identify the frame in YOUR code (skip framework internals).
- [ ] Note the exact input / request / action that triggered the bug.
- [ ] Note the expected behavior vs. the actual behavior.
- [ ] Check logs (application logs, server logs, browser console).
- [ ] Note the environment (OS, runtime version, dependency versions, config).
- [ ] Check if the bug is reproducible. If not, note the frequency and conditions.

**Key question:** Can I reproduce this bug reliably? If not, gathering more observations is the priority.

### Step 2: HYPOTHESIZE — Form a Theory

Based on the evidence, propose a specific, falsifiable explanation.

**Good hypothesis format:**
> "The crash occurs because `user.profile` is null when the user has not completed onboarding, and line 47 accesses `user.profile.name` without a null check."

**Bad hypothesis:**
> "Something is wrong with the user object."

**Rules:**
- The hypothesis must explain ALL observed symptoms.
- If it only explains some symptoms, it is incomplete — keep refining.
- Generate multiple competing hypotheses and rank by likelihood.

### Step 3: PREDICT — Design an Experiment

Before touching the code, predict what you will see IF your hypothesis is correct.

**Examples:**
- "If the null profile hypothesis is correct, then logging `user.profile` on line 45 will print `null` for users created after January 1."
- "If the race condition hypothesis is correct, then adding a 500ms delay before the second call will make the bug disappear."

### Step 4: TEST — Run the Experiment

Execute one change at a time. Observe whether the prediction matches.

**Rules:**
- Change ONE thing at a time. Multiple changes make it impossible to attribute cause.
- Revert experiments that did not help. Do not accumulate random changes.
- Use version control: commit or stash working state before experimenting.

### Step 5: CONCLUDE

- If the prediction matched, you have likely found the cause. Write a fix and a regression test.
- If the prediction did not match, your hypothesis was wrong. Return to Step 2 with new information.

---

## Binary Search Isolation

When you have no idea where the bug lives, use binary search to narrow it down.

### In Code
1. Identify the entry point and the crash / wrong output point.
2. Add a log or assertion at the MIDPOINT of the code path.
3. Is the state correct at the midpoint?
   - YES -> The bug is in the second half. Move your probe to the 75% point.
   - NO -> The bug is in the first half. Move your probe to the 25% point.
4. Repeat until you have isolated the exact line or function.

### In Time (git bisect)
```bash
git bisect start
git bisect bad              # Current commit is broken
git bisect good     # This commit was known to work
# Git checks out the midpoint. Test it.
git bisect good  # or  git bisect bad
# Repeat until git identifies the first bad commit.
git bisect reset
```

### In Data
1. Take the failing input dataset.
2. Remove half the data.
3. Does the bug still occur?
   - YES -> The bug is in the remaining half, or is independent of the removed data.
   - NO -> The trigger is in the removed half. Restore it and remove the other half.
4. Repeat until you find the minimum failing input.

---

## Reading Stack Traces

### Anatomy of a Stack Trace

```
Error: Cannot read properties of null (reading 'name')      Detailed variable dumps (temporary, remove after fixing)
INFO   -> Flow markers ("entered function X", "querying database")
WARN   -> Unexpected but handled conditions ("retrying after timeout")
ERROR  -> Unhandled exceptions and failures
```

### Temporary Debug Logging Pattern

```python
# Add a unique tag so you can find and remove all debug logs later
print("[DEBUG-ISSUE-123] user_id:", user_id, "profile:", profile)
```

When done, search for `[DEBUG-ISSUE-123]` and remove all instances.

---

## Common Bug Categories

### 1. Off-by-One Errors
- **Symptoms:** Missing first/last element; array index out of bounds; fence-post errors.
- **Check:** Loop bounds (` It is in the uncommented half.
   - NO -> It is in the commented half.
3. Repeat until isolated.

---

## Key Principles

1. **Reproduce first.** If you cannot reproduce it, you cannot verify your fix.
2. **One change at a time.** Multiple changes destroy your ability to reason about cause and effect.
3. **Read before you write.** Spend more time reading code and logs than writing fixes.
4. **Trust nothing.** Verify your assumptions. Print the value. Check the type. Read the documentation.
5. **The bug is in your code.** It is almost never the compiler, the OS, or the framework. Check your code first.
6. **Write the regression test.** A bug without a test is a bug that will return.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Claude-Code-Community-Ireland](https://github.com/Claude-Code-Community-Ireland)
- **Source:** [Claude-Code-Community-Ireland/claude-code-resources](https://github.com/Claude-Code-Community-Ireland/claude-code-resources)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-claude-code-community-ireland-claude-code-resources-debugging-systematic
- Seller: https://agentstack.voostack.com/s/claude-code-community-ireland
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.