# Diagnostic Scenario Catalog

Route by observed symptom and direct artifact. Select at most three scenarios
and load only their referenced files.

| Scenario ID | Enter when | Reference |
|---|---|---|
| `service-availability-impact` | active node/service loss, scrape loss, connection or request disappearance, business QPS/error impact | `scenario-service-availability-impact.md` |
| `connection-network-path` | connect/RPC timeout, disconnect, backoff, network latency, bandwidth, LB/backend suspicion | `scenario-connection-network-path.md` |
| `pd-tso-control-plane` | StartTS/TSO wait, PD request latency, PD/etcd leadership or control-plane symptom | `scenario-pd-tso-control-plane.md` |
| `tikv-storage-io` | one slow TiKV, disk jitter/throttle, RocksDB stall, compaction, snapshot/ingest wait | `scenario-tikv-storage-io.md` |
| `write-path-contention` | Commit/Prewrite latency, scheduler latch wait, lock/backoff, write conflict | `scenario-write-path-contention.md` |
| `memory-oom` | memory growth, OOM/restart, heap/coprocessor/backlog suspicion | `scenario-memory-oom.md` |
| `single-query` | diagnosis and optimization of a selected SQL, Digest, plan or identified request, including repeated executions or engine comparisons | `scenario-single-query.md` |
| `cluster-query-latency` | overall or multi-query runtime/P99/P999 latency increase, or symptom-led discovery without a selected SQL target | `scenario-cluster-query-latency.md` |
| `workload-hotspot` | CPU/RU/QPS/scan hotspot or the independent hotspot alternative for a latency symptom | `scenario-workload-hotspot.md` |
| `query-execution` | compatibility-only legacy route; new routes use single-query, cluster-query-latency and/or workload-hotspot | `scenario-query-execution.md` |
| `transaction-lock-retry` | pessimistic/optimistic retry, deadlock, lock wait, write conflict, transaction-flow question | `scenario-transaction-lock-retry.md` |
| `kill-cancel-stuck` | query does not stop after kill/cancel/timeout, cancellation propagation or tracking gap | `scenario-kill-cancel-stuck.md` |
| `tikv-leader-loss` | leader count drops, TiKV unavailable, slow-store or raft/gRPC failure suspicion | `scenario-tikv-leader-loss.md` |
| `region-movement-scale` | TiKV scale-out/in, snapshot/apply/ingest, add learner, peer movement stall | `scenario-region-movement-scale.md` |
| `region-merge-scheduling` | merge-region count/stall, PD checker rejection, operator generation/consumption gap | `scenario-region-merge-scheduling.md` |
| `follower-read-zone-imbalance` | zone-local read hotspot with follower read and connection distribution clues | `scenario-follower-read-zone-imbalance.md` |
| `ticdc-deployment-topology` | TiCDC version/build, new/classic kernel architecture, dedicated/shared deployment, exact changefeed target | `scenario-ticdc-deployment-topology.md` |
| `ticdc-changefeed-control-plane` | changefeed create/update/delete/list/status/config effective state or stuck lifecycle transition | `scenario-ticdc-changefeed-control-plane.md` |
| `ticdc-replication-progress` | checkpoint/resolved-ts lag, scan/puller/Event Service/Event Store/dispatcher/sink progress | `scenario-ticdc-replication-progress.md` |
| `ticdc-replication-correctness` | missing data/table, DDL/schema/filter/rename/syncpoint consistency and recovery safety | `scenario-ticdc-replication-correctness.md` |
| `ticdc-checkpoint-lag` | compatibility-only legacy route; new routes use one of the four TiCDC scenarios above | `scenario-ticdc-checkpoint-lag.md` |
| `tiflash-io-apply` | TiFlash IO jitter, raft apply/wait-index/append-log latency | `scenario-tiflash-io-apply.md` |
| `capacity-resource-pressure` | sustained CPU/memory/disk/region capacity, throttling, resource-control queue, autoscaling symptom | `scenario-capacity-resource-pressure.md` |

## Routing Precedence

- Add `service-availability-impact` for active service impact even if another
  scenario is the likely trigger.
- Use `connection-network-path` for transport boundaries; use
  `pd-tso-control-plane` when client/server TSO comparison points to PD or
  etcd.
- Use `tikv-storage-io` for storage/raft apply/engine paths and
  `write-path-contention` for scheduler latch, transaction lock, or Commit /
  Prewrite contention. Both may run when evidence supports independent paths.
- Keep `write-path-contention` primary when TopSQL, Statements, or Slow Query
  are used to map a generic Commit/Prewrite wrapper to its originating write
  DML and transaction.
- Select `single-query` for a customer-selected SQL or request, including
  diagnosis, plan-choice explanation and optimization advice. Multiple records,
  plans or engine comparisons of that target do not make it an overall incident.
  A supplied SQL that is only a suspected cause of an overall incident does
  not select this Scenario by itself.
- For an overall runtime/P99/P999 latency or duration increase, always select
  both `cluster-query-latency` and `workload-hotspot`. The former owns distribution
  and representative execution/wait attribution; the latter independently
  checks CPU, RU, QPS, scan and TopSQL concentration. Neither broad list needs
  SQL text or plans. One branch may not use absence in the other as negative
  evidence.
- Do not automatically add `workload-hotspot` for `single-query`; require an
  independent resource signal or resource-attribution question. Select both
  query Scenarios only for independent target-SQL and overall-latency questions.
- For CPU/RU/QPS/scan hotspot without a latency symptom, select only
  `workload-hotspot`. Do not select compatibility-only `query-execution` for a
  new route. Route detailed SQL tuning to the bundled `tidb-query-tuning` skill
  after a causal digest or plan is established.
- Use `capacity-resource-pressure` only when saturation is a candidate
  mechanism or an enforced resource/headroom limit was actually reached or
  exceeded, not merely because a resource metric is available. A direct memory
  limit breach may keep `memory-oom` primary while adding
  `capacity-resource-pressure` as the capacity-mitigation boundary.
- Keep TiCDC version, deployment topology, and kernel architecture independent.
  Do not infer the TiCDC version from the source TiDB version, new/classic from
  a version number, or new architecture from a dedicated deployment. Use the
  topology Scenario only when that identity is itself the question; every
  other TiCDC Scenario acquires the strongest available provider facts to
  choose the correct architecture-specific evidence branch. Cloud may use
  sanitized TiCDC metadata; Wetech OP uses its runtime metrics, logs, and
  supplied task context and never treats absent Cloud Dataflow metadata as a
  gap.
- For lag, compare same-changefeed ResolvedTS and CheckpointTS first. Rising
  ResolvedTS and CheckpointTS lag localizes upstream; normal ResolvedTS with a
  rising CheckpointTS lag localizes downstream. Do not mix classic and new
  architecture metric families in one conclusion.