---
mode: agent
description: Systematic debugging to isolate and fix software defects
tools:
  - read_file
  - grep_search
  - semantic_search
  - run_in_terminal
  - get_errors
---

# Debug

Systematically isolate and fix the reported issue.

## Your Task

Read the skill file at `.ao/skills/ao-debugging/SKILL.md` and follow its systematic process.

## Quick Process

1. **Root Cause Investigation**: Read errors, reproduce, check recent changes, trace data flow
2. **Pattern Analysis**: Find working examples, compare, identify differences, understand dependencies
3. **Hypothesis and Testing**: Form single hypothesis, test minimally, verify before proceeding
4. **Implementation**: Create failing test, implement fix, verify, question architecture if 3+ attempts fail

## Key Questions

- Can you consistently reproduce?
- What changed recently?
- What does the error message actually say?
- Where does the code path diverge from expected?

## Remember

- **One variable at a time** — don't change multiple things
- **Root cause, not symptoms** — don't just add error handling
- **Evidence over assumptions** — verify, don't guess
- **Add failing test FIRST** — create test that reproduces bug before fixing
- **Track fix attempts** — if 3+ attempts fail, question architecture
- **MANDATORY**: Failing test required before any bug fix

## Output

Update `.agent/ops/focus.json` with:
- Hypotheses tested and results
- Evidence gathered
- Root cause identified
- Fix applied and verified
