# Debug

> Systematic debugging workflow: reproduce, isolate, fix, and verify.

- Skill: `coreindustries/debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add coreindustries/debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/coreindustries/debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: coreindustries (https://skillmd.com/u/coreindustries)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/coreindustries/debug

---


# /debug

Systematic debugging workflow: reproduce, isolate, fix, and verify.

## Usage

```
/debug <issue> [--logs <path>] [--trace]
```

## Arguments

- `issue`: Description of the bug, error message, or issue number
- `--logs <path>`: Path to relevant log files
- `--trace`: Enable verbose tracing during investigation

## Instructions

When this skill is invoked:

### Agent Behavior

**Autonomy:**
- Complete the full debug cycle end-to-end
- Make reasonable hypotheses based on error patterns
- Implement and verify fixes without prompting

**Thoroughness:**
- Exhaust all likely causes before asking for help
- Document findings as you investigate
- Create regression tests for fixed bugs

**Methodology:**
- Follow scientific method: hypothesize → test → conclude
- Never change multiple things at once
- Always verify the fix resolves the original issue

### Debug Process

#### Phase 1: Understand

1. **Gather information**:
   - Read error message/stack trace carefully
   - Identify the failing component
   - Note when the issue started (if known)

2. **Read relevant code** in parallel:
   - File where error occurs
   - Related files (imports, dependencies)
   - Recent changes to affected area

3. **Check logs** if available:
   ```bash
   # Recent logs
   tail -100 {log_path}

   # Search for errors
   grep -i "error\|exception\|fail" {log_path}
   ```

#### Phase 2: Reproduce

1. **Create minimal reproduction**:
   - Identify exact steps to trigger the bug
   - Reduce to smallest failing case
   - Document reproduction steps

2. **Write a failing test**:
   ```bash
   # Create test that captures the bug
   {test_command} tests/unit/test_bug_reproduction.py -v
   ```

3. **Verify test fails** for the right reason

#### Phase 3: Isolate

1. **Form hypotheses** (list 3-5 likely causes):
   - Hypothesis 1: [Most likely cause]
   - Hypothesis 2: [Second most likely]
   - Hypothesis 3: [Edge case possibility]

2. **Test each hypothesis**:
   - Add logging/print statements
   - Use debugger breakpoints
   - Check variable states

3. **Binary search** if issue location unclear:
   - Comment out half the code
   - Determine which half contains the bug
   - Repeat until isolated

4. **Check common causes**:
   - Null/undefined values
   - Off-by-one errors
   - Race conditions
   - Type mismatches
   - Missing error handling
   - Configuration issues

#### Phase 4: Fix

1. **Implement minimal fix**:
   - Change only what's necessary
   - Don't refactor during bug fix
   - Keep the fix focused

2. **Verify fix**:
   ```bash
   # Run the failing test
   {test_command} tests/unit/test_bug_reproduction.py -v

   # Run related tests
   {test_command} tests/unit/test_{module}.py -v

   # Run full test suite
   {test_command} tests/ -v
   ```

3. **Add regression test** if not already covered

#### Phase 5: Document

1. **Update issue/ticket** with:
   - Root cause analysis
   - Fix description
   - Prevention measures

2. **Create commit** with clear message:
   ```
   fix(scope): description of what was fixed

   Root cause: [explanation]
   Solution: [what was changed]

   Closes #issue_number
   ```

### Capture Knowledge

If this fix took more than 15 minutes to diagnose, or the root cause was non-obvious, run `/compound` to capture the solution. This prevents future re-discovery of the same problem and builds the project's knowledge base in `docs/solutions/`.

### Debug Checklist

- [ ] Error message understood
- [ ] Issue reproduced locally
- [ ] Failing test written
- [ ] Root cause identified
- [ ] Minimal fix implemented
- [ ] All tests pass
- [ ] Regression test added
- [ ] Fix documented
- [ ] Knowledge captured with `/compound` (if non-trivial fix)

### Common Debug Patterns

**Null Reference:**
```
# Symptom: "Cannot read property X of undefined"
# Check: Is the object initialized? Is it returned from async?
```

**Race Condition:**
```
# Symptom: Intermittent failures, works sometimes
# Check: Async operations, shared state, missing awaits
```

**Type Error:**
```
# Symptom: "Expected X but got Y"
# Check: API response shape, serialization, type coercion
```

**Configuration:**
```
# Symptom: Works locally, fails in CI/prod
# Check: Environment variables, file paths, permissions
```

## Example Output

```
$ /debug "TypeError: Cannot read property 'id' of undefined in UserService"

====== Phase 1: Understand ======

Error: TypeError: Cannot read property 'id' of undefined
Location: src/services/user.py:45
Stack trace points to: getUserById() method

Reading relevant files...
- src/services/user.py
- src/api/users.py
- tests/unit/test_user.py

====== Phase 2: Reproduce ======

Reproduction steps:
1. Call GET /api/users/999 (non-existent ID)
2. Service returns undefined instead of null
3. Caller tries to access .id property

Writing failing test...
Created: tests/unit/test_user_not_found.py

Test result: FAILED (as expected)

====== Phase 3: Isolate ======

Hypotheses:
1. getUserById returns undefined for missing users
2. Database query doesn't handle empty results
3. Null check missing in API layer

Testing hypothesis 1...
Confirmed: getUserById returns undefined, not null

Root cause: Missing null check after database query

====== Phase 4: Fix ======

Fix: Add explicit null return when user not found

src/services/user.py:45
- return result
+ return result if result else None

Running tests...
- test_user_not_found: PASSED
- test_user_service: PASSED (15/15)
- Full suite: PASSED (142/142)

====== Phase 5: Document ======

Root cause: Database query returned undefined for missing records,
but callers expected null. This caused a TypeError when accessing
properties on the undefined value.

Fix: Added explicit null return with proper type hints.

Ready to commit:
fix(user): handle missing user in getUserById

Closes #789
```