| name | fix-bug |
| description | Diagnose and fix bugs in Agent Health. Use when a user reports a bug, failing test, or unexpected behavior. Follows a systematic diagnosis → fix → verify workflow.
|
Fix Bug in Agent Health
You are helping the user diagnose and fix a bug in Agent Health.
Step 1: Reproduce & Locate
- Understand the symptom: What's the expected vs actual behavior?
- Identify the layer: Use
find_architecture tool to narrow down where the bug likely lives
- Find the code path: Trace from the trigger (UI action, CLI command, API call) through the layers
Common Bug Locations by Symptom
| Symptom | Likely Location |
|---|
| Traces not appearing | services/traces/tracePoller.ts, spanCategorization.ts |
| Wrong token/cost metrics | services/traces/metrics.ts |
| Storage errors | services/storage/async*Storage.ts, server/adapters/ |
| CLI command fails | cli/commands/, cli/utils/apiClient.ts |
| SSE stream drops | services/agent/sseHandler.ts, response flushing |
| Evaluation incorrect | server/routes/judge.ts, prompt templates |
| UI not updating | hooks/, services/client/ |
| Agent connector fails | services/connectors/, connector-specific adapter |
Step 2: Diagnose
Read the relevant code. Look for:
- Off-by-one errors in iteration/pagination
- Missing null checks at system boundaries (API responses, storage queries)
- Race conditions in async flows (SSE, polling, cancellation)
- Type mismatches between storage format and app format
- Incorrect OpenSearch query construction
Do NOT guess. Read the code, understand the flow, then identify the root cause.
Step 3: Fix
Apply the minimal fix:
- Fix the actual bug, don't refactor surrounding code
- Don't add defensive error handling for scenarios that can't happen
- Don't add comments explaining the fix (the commit message does that)
- If the fix touches a type, check all usages of that type
Step 4: Write a Regression Test
Every bug fix should have a test that would have caught it:
- Test the specific scenario that was broken
- Use
@/ path alias
- Place in
tests/ mirroring the source path
Step 5: Verify
- Run
run_validation tool (scope: "all")
- Manually verify the original symptom is resolved
- Check that no other tests broke (the fix didn't introduce regressions)
Step 6: Commit & PR
git commit -s -m "fix: <concise description of what was wrong>
<one line explaining root cause>"
Update CHANGELOG.md under the appropriate section.
