# Debug

> Systematic debug workflow: research → orchestrate agents → escalate. Suggest when: stuck after 2-3 attempts, unfamiliar tooling, tempted to "try random things", or errors don't match documentation.

- Skill: `ohdearquant/debug` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add ohdearquant/debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ohdearquant/debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: ohdearquant (https://skillmd.com/u/ohdearquant)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/ohdearquant/debug

---


# Debug

Systematic approach to difficult debugging. Research → Orchestrate → Escalate.

## Activation Triggers

- Stuck on error after 2-3 failed fix attempts
- Unfamiliar library or dependency version
- Tempted to "try things randomly"
- Complex multi-system interactions
- Error messages that don't match documentation

## Anti-Patterns

- **Random flailing**: Trying fixes without understanding the problem
- **Editing generated files**: Modifying auto-generated output instead of fixing the source
- **Shallow fixes**: Adding workarounds without understanding root cause
- **Silent struggling**: Not asking for help when clearly stuck
- **Cheating through**: Disabling features or tests instead of fixing them

## Workflow Summary

| Phase | Action | Gate |
|-------|--------|------|
| **1. Research** | Check prior runs, search codebase, spawn researcher agent | 2-3 focused queries before any fix attempt |
| **2. Orchestrate** | Parallel diagnostic agents via `fanout.submit`, or a focused agent via `agent.submit` | Agent must produce actionable insight |
| **3. Escalate** | Generate consultation request with full evidence | Must demonstrate exhaustive research first |
| **4. Document** | Write fix to `./notes/debug-log.md` | Only after resolution |

See [research-protocol.md](research-protocol.md) for detailed methodology, agent selection
table, phase-by-phase MCP calls, and escalation template.

## Key Principles

- **Research before action**: Never try fixes without understanding the problem
- **Be specific**: Vague queries yield vague answers
- **Document attempts**: Track what was tried and what happened
- **Ask early**: Better to ask for help than waste time flailing
- **Store the fix**: Future sessions will thank present you

## Relevant Source Files

These are the CLI-side entry points; read them if you're working inside a lionagi
checkout. A plugin install has no access to them — it only sees the MCP server.

- `lionhub/src/lionhub/serve/cli/agent.py` — `li agent`, the CLI counterpart of `agent.submit`
- `lionhub/src/lionhub/serve/cli/orchestrate/fanout.py` — `li o fanout`, the CLI counterpart of `fanout.submit`
- `lionhub/src/lionhub/orchestration/runs.py` — run persistence at `~/.lionagi/runs/`, also readable
  through `job.status` / `job.output`

