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
- Configured code-intelligence symbol/reference/pattern search with native fallback
- Debugging checklist and bug report template
Canonical workflow path
Use the configured code-intelligence provider to locate files and inspect symbols
or content. For Serena, use find_file, search_for_pattern,
get_symbols_overview, and find_symbol. Native search is limited to the
provider exclusions and non-code paths permitted by the project's search policy.
Then run the smallest reproduction command first, establish the causal mechanism, and follow resources/execution-protocol.md for the diagnosis record when an OMA workflow is active. Add the 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/
Code intelligence
Use the configured provider to locate the failing function, find callers, and search similar error patterns. Native search and scoped reads are supported fallbacks; see the shared capability contract.
References
Local code tools: ../_shared/core/code-intelligence.md (code search/navigation)
Execution steps (follow for the selected task): 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 (matching prior failure or requested retrospective)
Observability handoff: ../oma-observability/SKILL.md §Integrations — traces/logs by trace_id, 6-dim forensics
1---2name: oma-debug3description: Diagnose a reproducible failure, fix its cause, and verify the4 regression. Use for crashes, incorrect behavior, and failing tests.5metadata:6 source: https://skillmd.com/skills/tuyv/oma-debug7---89# Debug Agent - Bug Fixing Specialist1011## Scheduling1213### Goal14Reproduce, diagnose, minimally fix, and regression-test bugs while preserving scope discipline and documenting root cause.1516### Intent signature17- User reports a bug, crash, traceback, exception, error message, performance issue, intermittent failure, or regression.18- User needs root cause analysis plus a minimal code fix and regression test.1920### When to use21- User reports a bug with error messages22- Something is broken and needs fixing23- Performance issues or slowdowns24- Intermittent failures or race conditions25- Regression bugs2627### When NOT to use28- Building new features -> use Frontend/Backend/Mobile agents29- General code review -> use QA Agent3031### Expected inputs32- Error message, failing behavior, reproduction steps, logs, test failure, or affected code path33- Existing tests, stack traces, environment notes, and suspected regression boundary3435### Expected outputs36- Root cause explanation37- Minimal fix scoped to the failing behavior38- Regression test or explicit reason it cannot be added39- Bug documentation under `.agents/results/bugs/` when appropriate4041### Dependencies42- `resources/execution-protocol.md`, examples, checklist, common patterns, and debugging checklist43- Local codebase search and symbol/reference tools44- Project test, lint, typecheck, and runtime commands4546### Control-flow features47- Branches by reproduction success, error class, suspected layer, and verification outcome48- Reads logs/code/tests and writes code/tests/docs49- Must search for similar patterns after fixing5051## Structural Flow5253### Entry541. Capture the reported symptom and suspected scope.552. Reproduce or establish the closest reliable failing signal.563. Identify affected files, tests, and related patterns.5758### Scenes591. **PREPARE**: Gather symptoms, logs, reproduction path, and verification command.602. **ACQUIRE**: Read failing code, tests, references, and similar patterns.613. **REASON**: Isolate root cause and reject unsupported hypotheses.624. **ACT**: Apply minimal fix and regression test.635. **VERIFY**: Re-run failing and related checks.646. **FINALIZE**: Document root cause, fix, test, and residual risk.6566### Transitions67- If reproduction fails, use logs/tests to establish a weaker but explicit diagnostic signal.68- If the first fix fails verification, return to root-cause analysis.69- If similar patterns exist, inspect and patch only affected cases.70- If the request is actually feature work, route to the relevant implementation skill.7172### Failure and recovery73- If environment is missing, document the blocker and provide the closest static diagnosis.74- If no regression test is feasible, explain why and include manual verification.75- If fix scope grows, stop and call out the broader design issue.7677### Exit78- Success: bug is fixed, regression coverage exists, and checks pass.79- Partial success: root cause or verification blocker is explicit.8081## Logical Operations8283### Actions84| Action | SSL primitive | Evidence |85|--------|---------------|----------|86| Reproduce failure | `CALL_TOOL` | Test/runtime/log command |87| Search affected code | `READ` | Code, tests, symbols, references |88| Compare similar patterns | `COMPARE` | Pattern search |89| Infer root cause | `INFER` | Diagnostic reasoning |90| Write minimal fix | `WRITE` | Code patch |91| Write regression test | `WRITE` | Test patch |92| Verify behavior | `VALIDATE` | Tests/checks |93| Report result | `NOTIFY` | Root-cause summary |9495### Tools and instruments96- Project test, lint, typecheck, runtime, and logging commands97- Configured code-intelligence symbol/reference/pattern search with native fallback98- Debugging checklist and bug report template99100### Canonical workflow path101Use the configured code-intelligence provider to locate files and inspect symbols102or content. For Serena, use `find_file`, `search_for_pattern`,103`get_symbols_overview`, and `find_symbol`. Native search is limited to the104provider exclusions and non-code paths permitted by the project's search policy.105106107Then run the smallest reproduction command first, establish the causal mechanism, and follow `resources/execution-protocol.md` for the diagnosis record when an OMA workflow is active. Add the regression test and re-run the failing check plus related tests.108109### Resource scope110| Scope | Resource target |111|-------|-----------------|112| `CODEBASE` | Failing source, tests, and related patterns |113| `LOCAL_FS` | Bug reports and result artifacts |114| `PROCESS` | Reproduction and verification commands |115| `MEMORY` | Hypotheses, root-cause notes, verification evidence |116117### Preconditions118- A bug signal, symptom, or failing behavior is available.119- Relevant code and verification path can be inspected or the blocker is stated.120121### Effects and side effects122- Mutates source/tests only as needed for the fix.123- May create bug documentation under `.agents/results/bugs/`.124125### Guardrails1261. Reproduce first, then diagnose - never guess at fixes1272. Identify root cause, not just symptoms1283. Minimal fix: change only what's necessary1294. Every fix gets a regression test1305. Search for similar patterns elsewhere after fixing1316. Document in `.agents/results/bugs/`132133### Code intelligence134Use the configured provider to locate the failing function, find callers, and search similar error patterns. Native search and scoped reads are supported fallbacks; see the shared capability contract.135136## References137- Local code tools: `../_shared/core/code-intelligence.md` (code search/navigation)138139- Execution steps (follow for the selected task): `resources/execution-protocol.md`140- Checklist (pre-submit self-verification): `resources/checklist.md`141- Error recovery: `resources/error-playbook.md`142- Bug report template: `resources/bug-report-template.md`143- Common patterns: `resources/common-patterns.md`144- Debugging checklist (investigation guide, used during Steps 1-2): `resources/debugging-checklist.md`145- Context loading: `../_shared/core/context-loading.md`146- Context budget: `../_shared/core/context-budget.md`147- Lessons learned: `../_shared/core/lessons-learned.md` (matching prior failure or requested retrospective)148- Observability handoff: `../oma-observability/SKILL.md` §Integrations — traces/logs by `trace_id`, 6-dim forensics