---
name: tidb-fast-diagnosis
description: Run a fast first-pass TiDB Cloud performance diagnosis that scans the request path broadly, ranks up to three evidence-backed investigation directions, and deepens only when useful. Use only when the user explicitly asks for fast diagnosis, quick diagnosis, first-pass diagnosis, or this skill by name. Interaction is conditional, not mandatory.
---

# TiDB Fast Diagnosis

Produce a useful first diagnosis quickly. This is a separate mode from the full RCA workflow. Do not silently enter it for an ordinary diagnosis request.

Persist each transition to `evidences/fast-diagnosis-state.json`, validated against `.opencode/investibook/schemas/fast-diagnosis-state.schema.json`. This file carries the ranked candidates across interactive turns. Numeric confidence belongs only in this file.

## State machine

### 1. Fast survey

Reuse covering fast/full evidence when available. Otherwise dispatch `evidence-agent` in **Fast Sweep** mode with the exact cluster and timezone-bearing window. It runs:

```bash
PYTHONPATH=.opencode/skills/builtin/clinic-cli/scripts \
python3 <collect_evidence.py> <cluster_id> <start_time> <end_time> \
  --profile fast [--parent-id <parent_id>]
```

Read the compact handoff and summary, not the raw evidence directory. Survey the end-to-end request path:

- entry/load: QPS, connections, errors, statement rate and affected rows;
- TiDB time: token wait, parse, compile, execute/KV request, backoff and TSO wait;
- storage path: TiKV gRPC by type, coprocessor/scheduler/latch, storage async, Raft and compaction;
- placement/analytics: PD and TiFlash signals when present;
- resources and health: CPU, memory, I/O, network, throttling, instance count, restart/OOM and peer skew;
- workload: TopSQL CPU and statement-pattern changes; query other TopSQL resource dimensions such as network only when available and useful for a selected direction.

Do not fetch decoded plans, full SlowQuery detail, hotspot-instance TopSQL, TiKV thread CPU, source code, GitHub, Jira history, or known cases during the survey.

### 2. Rank directions

Build at most three candidates. Rank them internally using timeline fit, affected-layer fit, peer/baseline differential, independent evidence, and contradictions. Keep numeric confidence internal; never display it.

Separate a workload trigger, pressure concentration, terminal bottleneck, downstream symptom, and competing explanation. A direction is not a confirmed root cause.

Each user-facing direction contains:

1. component or request-path layer;
2. strongest supporting evidence;
3. important contradiction or uncertainty when present;
4. the exact metric, log, TopSQL, Statement, SlowQuery, or plan check that best distinguishes it.

Weak evidence still produces concrete monitoring directions. Never force an RCA.

### 3. Decide whether to interact

Ask one concise question only when the answer can materially change the top direction or avoid an expensive deep dive, for example:

- the fault window or timezone is missing;
- deployment, scaling, migration, upgrade, or new workload context would distinguish close candidates;
- the user must choose between two expensive deep dives;
- the user explicitly wants to participate.

Otherwise continue automatically with the first direction when the user requested a completed diagnosis. In automated/evaluation runs, never pause.

### 4. Point verification

Run at most one targeted evidence round for the selected direction. Name the hypothesis, entity, exact window, comparison, and evidence source. Load only the matching family subskill from `tidb-clinic-diagnosis` when component internals are needed.

Use expensive evidence only after its direction is selected:

- SQL/workload: Statement + TopSQL first; SlowQuery/plan history only to distinguish volume, per-execution cost, and plan change.
- TiKV hotspot: hotspot-instance TopSQL and thread CPU, then the implicated read/write-path metrics.
- component failure: bounded logs, restart/OOM evidence, then source/known-case lookup only for a concrete signature.

High TiDB CPU always requires Go GC metrics for affected instances. If abnormal, report it and recommend continuous profiling.

### 5. Wide synthesis

Put the point result back into the full request path and timeline, then reorder the same top-three set. Prefer the terminal mechanism over a concurrent symptom. Preserve plausible alternatives and say what remains unverified.

## First response

Return no more than three numbered directions, ordered most useful first. Do not show confidence numbers. Keep evidence values and timestamps concise. End with either the automatic next check performed, one high-value question, or the exact monitor/log/query the user should inspect next.

If the user requires a strict machine-readable schema or exact output format, that format overrides the numbered prose presentation only. Still run Fast Sweep with `--profile fast`, keep the same evidence and ranking discipline internally, and emit exactly the requested fields with no surrounding explanation. Use the single targeted round when the broad artifacts do not contain a specifically requested ranking, mapping, or comparison.

## Boundaries

- Preserve existing evidence schemas and relative workspace paths.
- Never bulk-read `evidences/raw/`.
- Do not produce a full RCA report during the survey.
- Escalate to the existing full diagnosis workflow when candidates remain conflicting after one targeted round, the user requests an RCA, or remediation requires the full conclusion contract.