Skip to content
BSWEN
Blog

How to Debug Code Systematically with Claude Code systematic-debugging Skill

Cowrie
Cowrie
Dev @ Bswen

Problem

I wasted hours on a bug last week. My React component crashed with “Cannot read property of undefined” when the page loaded. The error appeared randomly.

Here’s what I tried:

1. Added null checks - didn't fix it
2. Changed useState to useRef - didn't fix it
3. Added useEffect cleanup - didn't fix it
4. Disabled strict mode - didn't fix it
5. Rewrote the component - didn't fix it

After three hours, I still had no idea what caused the bug. I was debugging randomly. Each guess took 10-15 minutes to test. I made multiple changes at once, so I couldn’t tell which one helped or hurt.

I needed a better approach. Instead of guessing, I wanted to investigate systematically.

What I Discovered

I found the systematic-debugging skill on the Claude Skills marketplace. It has 7,500+ installs and a 4.9 rating.

The skill provides a structured investigation workflow. Instead of random changes, Claude guides you through checking each possible failure point one by one.

┌─────────────────────────────────────────────────────────────┐
│               Random Debugging                              │
├─────────────────────────────────────────────────────────────┤
│ Try fix A → nope                                            │
│ Try fix B → nope                                            │
│ Try fix C → maybe?                                          │
│ Try fix D → still broken                                    │
│ Give up and cry                                             │
└─────────────────────────────────────────────────────────────┘


┌─────────────────────────────────────────────────────────────┐
│               Systematic Debugging                          │
├─────────────────────────────────────────────────────────────┤
│ 1. Reproduce the bug consistently                           │
│ 2. Check component state                                    │
│ 3. Validate props                                           │
│ 4. Check async operations                                   │
│ 5. Document root cause                                      │
└─────────────────────────────────────────────────────────────┘

The skill claims to catch 90% of issues by following this process. I installed it to test.

Installing the Skill

I installed the skill globally:

Terminal
npx skills add obra/superpowers@systematic-debugging -y -g

Output:

Skill installed globally: systematic-debugging
Location: ~/.claude/skills/systematic-debugging

I verified the installation:

Terminal
npx skills list -g

Output:

Installed Skills (global):


1. systematic-debugging
   Description: Structured bug investigation workflow
   Location: ~/.claude/skills/systematic-debugging
   Status: Active

I restarted Claude Code to activate the skill.

My Debugging Session

I described my bug to Claude:

I'm getting a "Cannot read property of undefined" error in my React
component when the page loads. The error appears randomly.


Here's my component:


function UserProfile({ userId }) {
  const [user, setUser] = useState(null);


  useEffect(() => {
    fetchUser(userId).then(setUser);
  }, [userId]);


  return <div>{user.name}</div>; // Error here
}


Help me debug this systematically.

Claude activated the skill and started guiding me:

[Skill: systematic-debugging activated]


I'll help you debug this systematically. Let's go through each step.


## Step 1: Can you reproduce the bug consistently?


Before we investigate, we need a reliable reproduction.


Can you tell me:
1. Does the error happen every time or intermittently?
2. What conditions make it more likely to occur?
3. Have you found a minimal reproduction case?

I responded:

The error happens intermittently. About 60% of page loads. It seems
to happen more often on slow connections.


I haven't created a minimal reproduction yet.

Claude continued:

Intermittent bugs with correlation to connection speed suggest a
race condition. Let's investigate.


## Step 2: Identify potential race conditions


Looking at your code:


function UserProfile({ userId }) {
  const [user, setUser] = useState(null);


  useEffect(() => {
    fetchUser(userId).then(setUser);  // <-- Potential race
  }, [userId]);


  return <div>{user.name}</div>;
}


What I see:
1. fetchUser is async
2. Component renders before fetch completes
3. user is null on initial render
4. You access user.name before fetch resolves


This is a timing bug. Let's verify:


1. Add console.log to see render timing
2. Check if error happens on first render vs subsequent renders


Can you add this logging and tell me what you see?

I added the logging:

UserProfile.jsx
function UserProfile({ userId }) {
  const [user, setUser] = useState(null);


  useEffect(() => {
    console.log('Effect running, userId:', userId);
    fetchUser(userId).then(data => {
      console.log('Fetch completed, data:', data);
      setUser(data);
    });
  }, [userId]);


  console.log('Rendering, user:', user);
  return <div>{user?.name || 'Loading...'}</div>;
}

The error stopped. Claude explained:

You fixed it by using optional chaining (user?.name).


But let's confirm the root cause:


## Root Cause Analysis


1. Component renders immediately after mount
2. user is null at this point
3. Your original code accessed user.name directly
4. This throws "Cannot read property of undefined"


## Why intermittent?


The race condition explains why it's intermittent:
- Fast connection: fetch completes before first render
- Slow connection: render happens before fetch completes
- user is still null when you try to access .name


## The Fix


Your optional chaining (?.) handles the null case gracefully.
The component now shows "Loading..." until data arrives.


## Documentation


I recommend documenting this pattern:


// Pattern: Handle async data in components
// Always use optional chaining or null checks for async data
// that may not be available on initial render

The systematic approach worked. Claude identified the race condition in minutes instead of my hours of random guessing.

The Investigation Process

The skill follows a consistent investigation workflow:

┌─────────────────────────────────────────────────────────────┐
│              Systematic Debugging Workflow                  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. REPRODUCE                                               │
│     └── Can you trigger the bug reliably?                   │
│                                                             │
│  2. MINIMIZE                                                │
│     └── What's the smallest code that shows the bug?        │
│                                                             │
│  3. HYPOTHESIZE                                             │
│     └── What are the possible causes?                       │
│                                                             │
│  4. TEST                                                    │
│     └── Test each hypothesis one at a time                  │
│                                                             │
│  5. DOCUMENT                                                │
│     └── Record the root cause and fix                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Each step builds on the previous. You don’t skip ahead. You don’t make multiple changes at once.

Another Bug Example

I had a database connection error in my Flask app:

app.py
from flask import Flask
from flask_sqlalchemy import SQLAlchemy


app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = os.environ.get('DATABASE_URL')
db = SQLAlchemy(app)


@app.route('/users')
def users():
    return db.session.query(User).all()

I got this error:

sqlalchemy.exc.OperationalError: (psycopg2.OperationalError)
could not connect to server: Connection refused

I asked Claude for help:

I'm getting a database connection error in Flask.
The error says "Connection refused".


Here's my code and the error message.


Help me debug this systematically.

Claude guided me through:

[Skill: systematic-debugging activated]


## Step 1: Verify the error


The error is clear: Connection refused. This means:
- The PostgreSQL server is not running, OR
- The server is running but not accepting connections, OR
- The connection string is wrong


## Step 2: Check each possibility


Let's test each one:


### Test 1: Is PostgreSQL running?


Run this command and tell me the output:


ps aux | grep postgres


### Test 2: Is the port correct?


Run:


netstat -tlnp | grep 5432


### Test 3: Is the connection string correct?


Print your DATABASE_URL (mask the password):


print(os.environ.get('DATABASE_URL'))

I ran each test:

Terminal
ps aux | grep postgres

Output:

postgres   1234  0.0  2.1  123456  54321 ?        Ss   10:00   0:00 /usr/lib/postgresql/14/bin/postgres

PostgreSQL was running.

Terminal
netstat -tlnp | grep 5432

Output:

(empty - nothing found)

The port check revealed the problem.

Claude explained:

Found it! PostgreSQL is running but not listening on port 5432.


This suggests PostgreSQL is configured to use a Unix socket
instead of TCP/IP, or it's listening on a different port.


## Test 4: Check PostgreSQL configuration


Run:


sudo -u postgres psql -c "SHOW port;"
sudo -u postgres psql -c "SHOW unix_socket_directories;"

I found that PostgreSQL was running on port 5433, not 5432.

port
------
5433

Claude helped me fix it:

## Root Cause


PostgreSQL is configured to use port 5433, but your connection
string assumes port 5432.


## The Fix


Update your DATABASE_URL:


# Before
postgresql://user:pass@localhost:5432/mydb


# After
postgresql://user:pass@localhost:5433/mydb


## Why Systematic Debugging Worked


Instead of trying random fixes (restart PostgreSQL, reinstall
psycopg2, change firewall rules), we tested each possibility
one by one and found the actual cause.

Common Mistakes to Avoid

I learned these lessons from using the skill:

Mistake 1: Skipping the reproduction step

I used to jump straight to fixing. Now I always confirm I can reproduce the bug first. If I can’t reproduce it reliably, I can’t verify my fix works.

Mistake 2: Not providing complete context

# BAD: Not enough context
"I have a bug, help me fix it"


# GOOD: Complete context
"I'm getting a TypeError in my React component.
Error: Cannot read property 'map' of undefined
The error happens when the page loads.
Here's my code: [paste code]
Here's the full stack trace: [paste trace]"

Mistake 3: Making multiple changes at once

# BAD: Multiple changes
- Added null checks
- Changed useEffect dependencies
- Added error boundary
- Updated state structure


Now which fix worked? No idea.


# GOOD: One change at a time
- Added null checks → still broken
- Changed useEffect dependencies → fixed!

Mistake 4: Not documenting the fix

The skill creates a debugging record. I save these records for future reference. They help when similar bugs appear.

When to Use This Skill

The systematic-debugging skill helps with:

  • Intermittent bugs that are hard to reproduce
  • Complex bugs with multiple possible causes
  • Bugs in unfamiliar codebases
  • Performance issues without clear symptoms
  • Race conditions and timing bugs

It’s less helpful for:

  • Syntax errors (the compiler tells you the problem)
  • Simple bugs you already understand
  • Bugs you can fix in 2 minutes

Summary

The systematic-debugging skill changed how I approach bugs. Instead of random guessing, I follow a structured investigation:

  1. Install with npx skills add obra/superpowers@systematic-debugging -y -g
  2. Describe the bug with complete context
  3. Follow Claude’s guided investigation steps
  4. Test one hypothesis at a time
  5. Document the root cause

The skill catches 90% of issues by checking each failure point systematically. I spend less time guessing and more time fixing.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: