gracefullight 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 functionfind_referencing_symbols("Component"): Find all usagessearch_for_pattern("error pattern"): Find similar issues
References
Follow resources/execution-protocol.md step by step.
See resources/examples.md for input/output examples.
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 - Code examples:
resources/examples.md - Checklist:
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:
resources/debugging-checklist.md - Context loading:
../_shared/core/context-loading.md - Reasoning templates:
../_shared/core/reasoning-templates.md - Context budget:
../_shared/core/context-budget.md - Lessons learned:
../_shared/core/lessons-learned.md - Observability handoff:
../oma-observability/SKILL.md§Integrations — traces/logs bytrace_id, 6-dim forensics