Oma Debug

Debug Agent - Bug Fixing Specialist

Scheduling

Goal

Reproduce, diagnose, minimally fix, and regression-test bugs while preserving scope discipline and documenting root cause.

Intent signature

• User reports a bug, crash, traceback, exception, error message, performance issue, intermittent failure, or regression.
• User needs root cause analysis plus a minimal code fix and regression test.

When to use

• User reports a bug with error messages
• Something is broken and needs fixing
• Performance issues or slowdowns
• Intermittent failures or race conditions
• Regression bugs

When NOT to use

• Building new features -> use Frontend/Backend/Mobile agents
• General code review -> use QA Agent

Expected inputs

• Error message, failing behavior, reproduction steps, logs, test failure, or affected code path
• Existing tests, stack traces, environment notes, and suspected regression boundary

Expected outputs

• Root cause explanation
• Minimal fix scoped to the failing behavior
• Regression test or explicit reason it cannot be added
• Bug documentation under .agents/results/bugs/ when appropriate

Dependencies

• resources/execution-protocol.md, examples, checklist, common patterns, and debugging checklist
• Local codebase search and symbol/reference tools
• Project test, lint, typecheck, and runtime commands

Control-flow features

• Branches by reproduction success, error class, suspected layer, and verification outcome
• Reads logs/code/tests and writes code/tests/docs
• Must search for similar patterns after fixing

Structural Flow

Entry

• Capture the reported symptom and suspected scope.
• Reproduce or establish the closest reliable failing signal.
• Identify affected files, tests, and related patterns.

Scenes

• PREPARE: Gather symptoms, logs, reproduction path, and verification command.
• ACQUIRE: Read failing code, tests, references, and similar patterns.
• REASON: Isolate root cause and reject unsupported hypotheses.
• ACT: Apply minimal fix and regression test.
• VERIFY: Re-run failing and related checks.
• FINALIZE: Document root cause, fix, test, and residual risk.

Transitions

• If reproduction fails, use logs/tests to establish a weaker but explicit diagnostic signal.
• If the first fix fails verification, return to root-cause analysis.
• If similar patterns exist, inspect and patch only affected cases.
• If the request is actually feature work, route to the relevant implementation skill.

Failure and recovery

• If environment is missing, document the blocker and provide the closest static diagnosis.
• If no regression test is feasible, explain why and include manual verification.
• If fix scope grows, stop and call out the broader design issue.

Exit

• Success: bug is fixed, regression coverage exists, and checks pass.
• Partial success: root cause or verification blocker is explicit.

Logical Operations

Actions

| Action | SSL primitive | Evidence |

|--------|---------------|----------|

| Reproduce failure | CALL_TOOL | Test/runtime/log command |

| Search affected code | READ | Code, tests, symbols, references |

| Compare similar patterns | COMPARE | Pattern search |

| Infer root cause | INFER | Diagnostic reasoning |

| Write minimal fix | WRITE | Code patch |

| Write regression test | WRITE | Test patch |

| Verify behavior | VALIDATE | Tests/checks |

| Report result | NOTIFY | Root-cause summary |

Tools and instruments

• Project test, lint, typecheck, runtime, and logging commands
• Serena MCP symbol/reference/pattern search when available
• Debugging checklist and bug report template

Canonical workflow path

rg "<error-message-or-symbol>"
rg --files

Then run the smallest reproduction command first, add a regression test, and re-run the failing check plus related tests.

Resource scope

| Scope | Resource target |

|-------|-----------------|

| CODEBASE | Failing source, tests, and related patterns |

| LOCAL_FS | Bug reports and result artifacts |

| PROCESS | Reproduction and verification commands |

| MEMORY | Hypotheses, root-cause notes, verification evidence |

Preconditions

• A bug signal, symptom, or failing behavior is available.
• Relevant code and verification path can be inspected or the blocker is stated.

Effects and side effects

• Mutates source/tests only as needed for the fix.
• May create bug documentation under .agents/results/bugs/.

Guardrails

• Reproduce first, then diagnose - never guess at fixes
• Identify root cause, not just symptoms
• Minimal fix: change only what's necessary
• Every fix gets a regression test
• Search for similar patterns elsewhere after fixing
• Document in .agents/results/bugs/

Serena MCP

• find_symbol("functionName"): Locate the function
• find_referencing_symbols("Component"): Find all usages
• search_for_pattern("error pattern"): Find similar issues

References

Follow resources/execution-protocol.md step by step.

Before submitting, run resources/checklist.md.

Vendor-specific execution protocols are injected automatically by oma agent:spawn.

Source files live under ../_shared/runtime/execution-protocols/{vendor}.md.

• Execution steps: resources/execution-protocol.md
• Checklist (pre-submit self-verification): resources/checklist.md
• Error recovery: resources/error-playbook.md
• Bug report template: resources/bug-report-template.md
• Common patterns: resources/common-patterns.md
• Debugging checklist (investigation guide, used during Steps 1-2): resources/debugging-checklist.md
• Context loading: ../_shared/core/context-loading.md
• Context budget: ../_shared/core/context-budget.md
• Lessons learned: ../_shared/core/lessons-learned.md
• Observability handoff: ../oma-observability/SKILL.md §Integrations — traces/logs by trace_id, 6-dim forensics