| name | debug |
| description | 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.
|
| allowed-tools | ["Bash","Read","Grep","Glob","WebSearch","WebFetch"] |
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 li o fanout or focused analyst | 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 for detailed methodology, agent selection
table, phase-by-phase commands, 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
lionagi/cli/agent.py — li agent one-shot and resumed turn entry pointlionagi/cli/orchestrate/fanout.py — li o fanout parallel workerslionagi/cli/_runs.py — run persistence at ~/.lionagi/runs/
