systematic-debug

name	systematic-debug
description	name: arcanea-systematic-debug Use when this capability is needed.

---

name: arcanea-systematic-debug description: Systematic debugging methodology - scientific approach to finding and fixing bugs using hypothesis testing, isolation, and root cause analysis. Based on the Arcanean principle that understanding precedes execution. version: 2.0.0 author: Arcanea tags: [debugging, troubleshooting, development, problem-solving] triggers:

• bug
• error
• not working
• debug
• broken
• failing
• unexpected behavior

---

Systematic Debugging: The Arcanean Method

"Sophron teaches: Understanding precedes execution. Do not guess at the bug. Understand the system, and the bug reveals itself."

---

The Debugging Mindset

What Debugging Is NOT

❌ Random changes hoping something works
❌ Blaming the framework/library/language
❌ Assuming you know the cause without evidence
❌ Deleting and rewriting until it works

What Debugging IS

✓ Scientific investigation
✓ Hypothesis formation and testing
✓ Systematic isolation
✓ Understanding before fixing

---

The Scientific Method for Bugs

╭─────────────────────────────────────────────────────────╮
│                    THE DEBUG CYCLE                       │
├─────────────────────────────────────────────────────────┤
│                                                          │
│   1. OBSERVE    →  What exactly is happening?           │
│        ↓                                                 │
│   2. REPRODUCE  →  Can I make it happen reliably?       │
│        ↓                                                 │
│   3. HYPOTHESIZE→  What could cause this?               │
│        ↓                                                 │
│   4. TEST       →  Is my hypothesis correct?            │
│        ↓                                                 │
│   5. FIX        →  Address the root cause               │
│        ↓                                                 │
│   6. VERIFY     →  Is it actually fixed?                │
│        ↓                                                 │
│   7. PREVENT    →  How do we stop it happening again?   │
│                                                          │
╰─────────────────────────────────────────────────────────╯

---

Step 1: Observe

Gather the Facts

WHAT is happening?
- Exact error message (copy it!)
- Actual behavior vs. expected behavior
- What does "not working" mean specifically?

WHEN does it happen?
- Always, or intermittently?
- After a specific action?
- At a specific time?

WHERE does it happen?
- Which environment? (dev, staging, prod)
- Which browser/device/OS?
- Which user/account?

WHO does it affect?
- All users or specific users?
- New users or existing?
- Any pattern in affected users?

The Bug Report Template

## Bug: [Clear, specific title]

### Observed Behavior
[What actually happens]

### Expected Behavior
[What should happen]

### Steps to Reproduce
1. [Step 1]
2. [Step 2]
3. [Step 3]

### Environment
- Browser/Client:
- OS:
- Environment:
- User role:

### Error Messages
[Exact error text or screenshot]

### Frequency
[Always / Sometimes / Once]

### Impact
[Who is affected and how severely]

---

Step 2: Reproduce

The Reproduction Requirement

IF YOU CAN'T REPRODUCE IT, YOU CAN'T FIX IT
(Or at least, you can't verify the fix)

Creating a Minimal Reproduction

1. Start with the full scenario
2. Remove one element at a time
3. Does the bug still occur?
4. Continue until you have the smallest case

The minimal reproduction reveals the cause.

When You Can't Reproduce

Consider:
- Environment differences
- Timing/race conditions
- State dependencies
- User-specific data
- Cached vs. fresh state
- Network conditions

---

Step 3: Hypothesize

Generate Hypotheses

List possible causes without judgment:

"The bug could be caused by:"
1. [Hypothesis A]
2. [Hypothesis B]
3. [Hypothesis C]

Rank by:
- Likelihood (most to least likely)
- Testability (easiest to hardest to test)

Common Bug Categories

STATE BUGS
- Wrong initial state
- State not updated
- State updated incorrectly
- Stale state (caching)

LOGIC BUGS
- Wrong condition
- Off-by-one
- Wrong operator
- Missing case

DATA BUGS
- Wrong type
- Null/undefined
- Malformed data
- Encoding issues

TIMING BUGS
- Race condition
- Wrong order
- Timeout too short/long
- Async not awaited

INTEGRATION BUGS
- API contract mismatch
- Environment difference
- Missing dependency
- Version mismatch

EDGE CASES
- Empty input
- Maximum input
- Invalid input
- Concurrent access

---

Step 4: Test Hypotheses

Isolation Techniques

Binary Search Debugging

If you don't know where the bug is:

1. Find the midpoint of the suspicious code
2. Add a log/breakpoint there
3. Is the state correct at that point?
4. If yes: bug is after that point
5. If no: bug is before that point
6. Repeat until found

This finds any bug in O(log n) checks.

Diff Debugging

If the code used to work:

1. Find last known working version (git bisect)
2. Compare with current version
3. What changed?
4. The bug is in the diff

git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>
git bisect run npm test

Rubber Duck Debugging

Explain the code line by line to:
- A rubber duck
- A colleague
- Yourself out loud

The act of explaining often reveals the bug.

Diagnostic Tools

LOGGING
- Add strategic console.log/print statements
- Log inputs, outputs, intermediate state
- Remove logs after debugging

BREAKPOINTS
- Pause execution at specific lines
- Inspect variable state
- Step through execution

ASSERTIONS
- Add runtime checks for assumptions
- assert(value !== null, 'value should exist')
- Fail fast when assumptions break

PROFILERS
- For performance bugs
- Identify slow functions
- Find memory leaks

---

Step 5: Fix

The Fix Principles

FIX THE ROOT CAUSE, NOT THE SYMPTOM

Symptom: "Users get 500 error on profile page"
Surface fix: Catch the error, show generic message
Root cause fix: Prevent the null pointer in user data

Surface fixes hide bugs. Root cause fixes eliminate them.

Before Fixing

□ I understand WHY the bug occurs
□ I can explain the fix to someone else
□ The fix addresses root cause, not symptom
□ The fix won't introduce new bugs
□ The fix is the simplest solution

The Minimal Fix

Change as little as possible.
One bug = one fix.
Don't refactor while fixing bugs.
Don't add features while fixing bugs.

---

Step 6: Verify

Verification Checklist

□ Original bug is fixed
□ Bug cannot be reproduced anymore
□ All existing tests still pass
□ New test written for this bug
□ Related functionality still works
□ Fix works in all affected environments

The Regression Test

Write a test that:
1. Failed before the fix
2. Passes after the fix
3. Prevents this bug from returning

This is the most important test you can write.

---

Step 7: Prevent

Post-Mortem Questions

1. Why did this bug exist?
   - Missing test?
   - Unclear requirement?
   - Complex code?
   - Communication failure?

2. Why wasn't it caught earlier?
   - Code review missed it?
   - Tests didn't cover it?
   - QA didn't test this flow?

3. How can we prevent similar bugs?
   - Add tests?
   - Improve code review?
   - Simplify code?
   - Better tooling?

Prevention Strategies

ADD TESTS
- Unit test for this specific bug
- Integration test for this flow
- Edge case tests

IMPROVE CODE
- Simplify complex logic
- Add defensive checks
- Improve error messages

IMPROVE PROCESS
- Update code review checklist
- Add to QA test cases
- Document the gotcha

---

Debugging Specific Bug Types

Null Pointer / Undefined

1. Find the null value
2. Trace backward: where should it have been set?
3. Why wasn't it set?
   - Never initialized
   - Initialization failed
   - Set then cleared
   - Wrong variable

Race Condition

1. Identify the shared resource
2. What operations are racing?
3. What's the problematic order?
4. Add proper synchronization:
   - Locks/mutexes
   - Atomic operations
   - Message queues

Performance Bug

1. Profile: where is time spent?
2. Is it algorithmic? (O(n²) vs O(n))
3. Is it I/O? (database, network)
4. Is it memory? (garbage collection)
5. Fix the biggest bottleneck first

Memory Leak

1. Take memory snapshots over time
2. What objects are growing?
3. Why aren't they being collected?
   - Event listeners not removed
   - Closures holding references
   - Global references
   - Caching without limits

---

Quick Reference

The Debug Checklist

□ Exact error message captured
□ Steps to reproduce documented
□ Minimal reproduction created
□ Hypotheses listed
□ Most likely hypothesis tested first
□ Root cause identified
□ Minimal fix applied
□ Fix verified
□ Regression test written
□ Prevention documented

Debug Commands

// Quick state logging
console.log('State:', JSON.stringify(state, null, 2));

// Trace function calls
console.trace('Called from:');

// Measure timing
console.time('operation');
// ... operation ...
console.timeEnd('operation');

// Assert assumptions
console.assert(condition, 'This should be true');

// Group related logs
console.group('Processing user');
console.log('id:', user.id);
console.log('status:', user.status);
console.groupEnd();

When You're Stuck

1. Take a break (fresh eyes find bugs)
2. Explain it to someone else
3. Question your assumptions
4. Look at what changed recently
5. Search for similar issues online
6. Add more logging
7. Reduce to minimal case
8. Sleep on it (seriously)

---

"The bug exists in the gap between what you think the code does and what it actually does. Close that gap with understanding."

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.