---
name: trade-bot-root-cause-debugging
description: Use when diagnosing failing CI, runtime exceptions, regressions, incorrect outputs, dependency/API errors, concurrency bugs, or incomplete PR checks in Trade-Bot.
---

# Root-cause debugging

1. Capture exact branch and HEAD SHA. Read only evidence permitted by repository policy. For CI, run `python3 scripts/local_checks.py prepare` and accept only its single notice with a hidden SHA marker matching the current HEAD.
2. Classify the observation: assertion/test failure, lint/format, coverage, architecture/security gate, runtime exception, timeout, cancelled/skipped workflow, or unavailable diagnostic evidence. A skipped or cancelled job is not a successful check and is not necessarily a code defect.
3. Trace the failing operation to its real inputs, caller, state mutations, external dependency, exception handler, and expected outcome. Distinguish verified facts from hypotheses. Do not infer a root cause from a job name or a prior agent's summary.
4. Reproduce the failure in a regression test at the correct boundary when feasible. Under Trade-Bot's policy, author the regression locally but let GitHub Actions execute it; do not run test or check commands locally.
5. Fix the cause, not the symptom. Do not lower coverage thresholds, loosen schemas, broaden exception swallowing, update snapshots blindly, accept cancelled checks, bypass a gate, or add sleeps to hide races.
6. Error handling must classify transient versus permanent errors. Bound retry count and elapsed time; use backoff/jitter for retryable idempotent requests; respect provider retry guidance; do not blindly retry order submission, non-idempotent writes, or partially completed state transitions.
7. Preserve original error context without logging secrets. Emit stable error codes and useful correlation IDs where existing contracts allow them. Verify recovery, cleanup, and idempotency as well as the first exception.
8. Push only task-scoped fixes on the existing authorized PR branch. After CI publishes a notice, run the approved preparation command and fix only the actionable finding for that exact SHA. Never use direct workflow/job logs, artifacts, bulk comments, or a live CI watcher.
9. Do not configure SonarQube for this project unless the user explicitly changes that instruction. Report when required evidence is unavailable instead of substituting guesses.

## Escalation rule

If the permitted notice does not contain enough evidence, first inspect source, tests, workflow definitions, and public commit metadata. Do not widen CI-log access; record the remaining evidence gap and request an approved diagnostic path only if needed.