---
name: tidb-knowledge-base
description: |
  TiDB Cloud knowledge base for diagnosis: tier data-plane architecture, metric routing
  (parent_id / keyspace_id), PingCAP doc topic index, and a catalogued list of known wrong
  conclusions (incorrect-conclusions.json, e.g. ANALYZE mis-attribution). Use for any TiDB Cloud
  cluster analysis, root-cause work, performance investigation, on-call triage, or Dedicated vs
  Starter/Essential vs Premium comparison. Always load alongside tidb-clinic-diagnosis (it does
  not replace clinic-api): its Step A (tier data + metric routing) and Step B (pitfall catalog)
  MUST be completed before collect_evidence.py or any metrics collection. Consult it before
  issuing TiKV/PD/TiFlash metric calls whenever cluster metadata or deploy type is known or
  about to be queried.
---

# TiDB Knowledge Base (`tidb-knowledge-base`)

## Why this skill exists

Wrong PromQL scope (e.g. Premium TiKV using `cluster_id` instead of `parent_id`) and shallow doc
claims produce confident but incorrect RCAs. This skill bundles **structured KB files** and a **fixed
order of consultation** so you align architecture and evidence before narrating mechanisms or final
causes. It complements `tidb-clinic-diagnosis` (evidence + gates) and `clinic-api` (data access); it
does not fetch metrics by itself.

## When to load it (checklist)

Load **early** in any TiDB Cloud / TiDB-X investigation if **any** of these apply:

- You are about to query **TiKV, PD, TiFlash, or node** metrics and you know or will know `cluster_type` / `cluster_type_v2` / `deployType`.
- The user mentions **Premium**, **parent**, **resource pool**, **keyspace**, **Starter**, **Essential**, **Dedicated**, or **metric routing**.
- You need to **ground** behavior (GC, locks, RU, planner, scheduling) in **official docs**.
- You are **starting performance diagnosis** after tier is known — load the pitfall catalog **before** interpreting TopSQL/SlowQuery or collecting evidence.

Skip only for pure application-code bugs with no database architecture angle.

### Pairing with `tidb-clinic-diagnosis`

**Step A** then **Step B** must run **before** `collect_evidence.py`: Step A — read `tier-architecture.json`, map metadata to the tier, and apply `metric_routing`. Step B — read `incorrect-conclusions.json` and internalize `corrective_checks` / `conclusion_rule` before evidence runs. See **`tidb-clinic-diagnosis`** SKILL for checkpoints.

---

## Path resolution (read tool)

Primary paths assume the skill lives under `builtin/` in the workspace skills tree:

| Asset | Primary path |
|-------|----------------|
| Tier + routing | `skills/builtin/tidb-knowledge-base/knowledge/tier-architecture.json` |
| Doc index (generated) | `skills/builtin/tidb-knowledge-base/knowledge/official-docs-index.json` |
| Doc index (source) | `skills/builtin/tidb-knowledge-base/knowledge/official-docs-index.sources.json` |
| Pitfall catalog | `skills/builtin/tidb-knowledge-base/knowledge/incorrect-conclusions.json` |

If `read` fails, try the same path under `.opencode/skills/builtin/tidb-knowledge-base/knowledge/`, or search the workspace for `tidb-knowledge-base/knowledge/*.json`.

---

## Workflow (mandatory order)

### Step A — Tier and metric scope (before cross-component metrics)

**Goal:** State which tier the cluster is and which ID to use for which component class.

1. Read `tier-architecture.json`.
2. Map metadata fields (`cluster_type`, `cluster_type_v2`, `deployType`, `parent_id`, `keyspace_id`) to the right `tiers.*` entry.
3. Apply that tier’s `metric_routing` before any TiKV/PD/TiFlash/node PromQL or metrics URL. For Premium, non-TiDB components use **`parent_id`** as the metrics scope where documented; for Starter/Essential, apply **`keyspace_id`** where PSC templates require it.

**Output you should produce in reasoning (brief):** tier name + one line on which ID applies to TiDB vs pool/TiKV.

Do not proceed with cross-component metric interpretation until this is explicit.

### Step B — Pitfall catalog (immediately after Step A, before evidence interpretation)

**Goal:** Avoid catalogued automation mistakes (e.g. mis-attributing ANALYZE in TopSQL/Slow Query) **while** you collect and interpret evidence — not only when drafting the final sentence.

1. Read `incorrect-conclusions.json` as soon as Step A is done and **before** `collect_evidence.py`, PromQL, or ranking TopSQL/SlowQuery suspects.
2. For each relevant `entries[]` item, note `wrong_pattern`, `tags`, `corrective_checks`, `correct_procedure`, and **`conclusion_rule`** (if present). Use them as **ongoing constraints** when reading TopSQL/SlowQuery (e.g. deprioritize ANALYZE rows first; do not name ANALYZE as the primary root cause unless `conclusion_rule` allows).
3. If you lack disambiguating evidence for a matching pitfall, gather it before committing to a causal chain.

**Output (brief, in reasoning):** Which entry ids you loaded and which rules apply to this investigation.

### Step C — Official docs (while explaining mechanisms, before strong claims)

**Goal:** Tie behavioral statements to PingCAP documentation topics when discussing internals or limits.

1. Read `official-docs-index.json`.
2. Match `topics[].keywords` to the symptom or question (use `category` if helpful).
3. Resolve URL: `doc_bases[base] + path` per `resolve_url`. Open or fetch the page when you need mechanism detail. If the path 404s, search the doc site for the keyword and use the best current page.

**Output:** Name the topic id(s) or doc URL(s) you used when stating non-obvious product behavior.

### Step D — Coordination with `tidb-clinic-diagnosis`

- Run **Step A** when tier is known, then **Step B** before evidence collection or TopSQL/SlowQuery attribution.
- Run **Step C** during component deep-dives (aligned with Nodes C–D).
- **Before finalizing:** if your thesis changed materially since Step B, re-read `incorrect-conclusions.json` and confirm you still satisfy `conclusion_rule` for any matched entry (same gate as Node E cross-checks).

---

## Maintainer notes (extending the KB)

- **incorrect-conclusions.json:** Append entries with stable `id`, rich `tags`, concrete `corrective_checks`. When the pitfall is about **how the written conclusion is phrased** (not only how to read metrics), add a **`conclusion_rule`** so Step B has an explicit constraint during analysis.
- **official-docs-index:** Edit `official-docs-index.sources.json`; regenerate:
  ```bash
  python3 agentkit/skills/builtin/tidb-knowledge-base/scripts/generate_official_docs_index.py
  ```
  Use `--no-check` for offline JSON only; `--strict` to fail on non-2xx URLs. Commit both `sources` and generated `official-docs-index.json`.
- **tier-architecture.json:** Update when TiDB Cloud routing or architecture semantics change; keep in sync with `system_prompt` metric routing where applicable.

Do not mirror full PingCAP documentation in-repo; keep indexes, structured tier data, and pitfall entries. Fetch long-form prose from the web when needed.

---

## Anti-patterns

- Querying **TiKV/PD** for **Premium** using the product `cluster_id` when the KB says to use **`parent_id`** for pool-scoped series.
- Writing a final RCA that cites **mechanisms** (GC, RU, locks) with **no** doc or KB grounding when `official-docs-index` has a matching topic.
- Skipping **Step B** and only "checking" `incorrect-conclusions.json` at the end — pitfall rules must shape analysis from the first TopSQL/SlowQuery read.
- Finalizing after matching a pitfall without having applied the listed **corrective_checks** (or after a material thesis change without re-reading the catalog).