// 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.
| 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. |
You are helping the user diagnose and fix a bug in Agent Health.
find_architecture tool to narrow down where the bug likely lives| 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 |
Read the relevant code. Look for:
Do NOT guess. Read the code, understand the flow, then identify the root cause.
Apply the minimal fix:
Every bug fix should have a test that would have caught it:
@/ path aliastests/ mirroring the source pathrun_validation tool (scope: "all")git commit -s -m "fix: <concise description of what was wrong>
<one line explaining root cause>"
Update CHANGELOG.md under the appropriate section.
Create a pull request for Agent Health following all compliance requirements. Use after implementing a feature or fix. Handles SPDX headers, DCO signoff, CHANGELOG, and the PR template.
Guided feature implementation for Agent Health. Use when a user wants to add a new capability, endpoint, CLI command, or UI component to the Agent Health project. Ensures correct architecture layer, coding conventions, test coverage, and PR readiness.
Add OpenTelemetry instrumentation to an AI agent for Agent Health observability. Use when a user wants to make their agent's traces visible in Agent Health dashboards, or when debugging why traces aren't appearing. Covers span structure, Gen AI semantic conventions, required attributes, and OTLP exporter setup.
Set up an OpenTelemetry collector or OSIS pipeline to route traces from an agent to OpenSearch for Agent Health consumption. Covers OSIS, OTel Collector, and direct export configurations.
Write tests for Agent Health following project conventions. Use when adding tests for new features, bug fixes, or improving coverage. Covers Jest setup, mocking patterns, path aliases, and coverage thresholds.
Use when working on config loading, authentication, AWS profiles, or data source resolution. Explains the two config systems (TS vs JSON), auth priority, and multi-profile setup.