debug-assist

Files (1)

• SKILL.md

SKILL.md (first lines)

# Debug Assist

## Overview

A systematic debugging workflow for diagnosing issues and verifying fixes. Unlike `code-assist` which builds new features, this skill focuses on understanding and fixing existing broken behavior.

**When to use:**
- Something is broken and you need to understand why
- Tests are failing and root cause is unclear
- Production issue needs diagnosis
- Bug reports need investigation

**Difference from code-assist:**
- `code-assist` = "Build something new" (explore → plan → implement)
- `debug-assist` = "Fix something broken" (observe → hypothesize → test → fix)

## Parameters

- **issue_description** (required): What's broken? Error messages, unexpected behavior, symptoms
- **context** (optional): Codebase path, relevant files, recent changes
- **reproduction_steps** (optional): Known steps to reproduce the issue
- **logs_output** (optional): Relevant log output or error traces
- **mode** (optional, default: "interactive"): "interactive" (confirm each step) or "auto" (autonomous)

## Steps

### 1. Observe and Document

**Capture the symptoms:**
- What exactly is happening vs. what should happen?
- Error messages (full stack traces)
- When did it start? (recent changes, deployments)
- Who/what is affected?

**Constraints:**
- You MUST NOT jump to conclusions about the cause
- You MUST document the observed behavior before investigating
- You SHOULD capture screenshots/output for reference

### 2. Isolate the Problem

**Narrow down where the issue occurs:**
- Identify the minimal reproduction case
- Determine which component/layer is involved
- Check if it's environmental (works on my machine?)
- Binary search: comment out half the code, does it still break?

**Constraints:**
- You MUST test hypotheses one at a time
- You MUST keep a log of what you tried and the result
- You SHOULD use version control to checkpoint before experiments

### 3. Form Hypotheses

**Generate possible explanations:**
- What could cause this symptom?
- Rank by likelihood (Occam's razor: simplest first)
- Consider recent changes as prime suspects

**Common hypothesis categories:**
- Logic error (wrong condition, off-by-one)
- State issue (race condition, uninitialized variable)
- Data issue (corrupted input, schema mismatch)
- Environment issue (dependency version, config)
- Integration issue (API changed, contract broken)

### 4. Test Hypotheses

**Verify or falsify each hypothesis:**
- Design an experiment to test the hypothesis
- Make a minimal change to confirm/deny
- Use logging/debugging to inspect state
- Check assumptions (is this actually true?)

**Constraints:**
- You MUST change only one thing at a time
- You MUST predict the expected outcome before testing
- You MUST document results even if hypothesis is wrong
- You SHOULD use temporary debug logging liberally

### 5. Identify Root Cause

**Confirm the actual cause:**
- Which hypothesis was correct?
- Why did this happen? (not just what)
- What assumption was violated?

**Constraints:**
- You MUST verify the root cause produces the symptom
- You MUST understand why the fix will work
- You SHOULD check if this same issue exists elsewhere

### 6. Implement Fix

**Fix the root cause (not just the symptom):**
- Minimal change that fixes the issue
- Preserve existing behavior for non-broken cases
- Add regression test if possible

**Constraints:**
- You MUST NOT over-fix (address just this issue)
- You MUST verify the fix doesn't break other things
- You SHOULD clean up any debug logging added

### 7. Verify Fix

**Confirm the issue is resolved:**
- Reproduce the original scenario - does it work now?
- Run existing tests - all pass?
- Check edge cases - still handled?

**Constraints:**
- You MUST verify the specific reported issue is fixed
- You MUST run relevant test suites
- You SHOULD add a test that would have caught this bug

### 8. Document

**Record what was learned:**

From exoad/bibo-agent, Apache-2.0.

More from exoad/bibo-agent