fix-bug

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

1. Understand the symptom: What's the expected vs actual behavior?
2. Identify the layer: Use find_architecture tool to narrow down where the bug likely lives
3. 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

1. Run run_validation tool (scope: "all")
2. Manually verify the original symptom is resolved
3. 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.