---
name: tidb-clinic-diagnosis
description: |
  TiDB Cloud diagnosis routing and evidence-tool entry point. Classify collected
  evidence through the family subskills and load their required specialists.
  General diagnostic methods are an on-demand fallback, not a default workflow.
---

# TiDB Clinic Diagnosis

This directory contains classification families, evidence tools, and optional
general diagnostic methods. Using a script or a family subskill does not require
reading this entry point or the general diagnosis reference.

## Default Diagnosis Path

1. Read the public reasoning contract in `diagnosis-overview` and the
   `tidb-knowledge-base` tier architecture and incorrect-conclusion guardrails.
2. Read [SUBSKILLS_INDEX.md](SUBSKILLS_INDEX.md) and
   [root-cause-classification/SUBSKILL.md](root-cause-classification/SUBSKILL.md).
3. Read each selected family subskill and execute its Specialist Loading Contract.
   Resolve specialist paths through `.opencode/investibook/SKILL_CATALOG.md`.
4. Compare the selected hypotheses against the evidence. A selected branch is
   not a conclusion. If the final class changes, load its family and required
   specialist before final synthesis.

This path is identical for Copilot and Autopilot; only the route-selection
checkpoint differs. A family without an external specialist is a valid diagnosis
path. Do not read every family or the general fallback by default.

## Agent Boundaries

- **Investigator** reads the classification table and selected families only to
  build the analyst's required skill list. It does not execute specialist diagnosis.
- **Evidence agent** uses `scripts/collect_evidence.py` for sweep mode or data-access
  skills for targeted collection, following its own agent prompt. It does not
  read diagnosis methods. No script paths or collection semantics change here.
- **Diagnosis analyst** reasons over existing evidence using the selected families
  and specialists. It uses `scripts/read_raw_evidence.py` for bounded raw-metric
  reads and `scripts/write_analyst_report.py` for its output contract.
  Missing evidence goes back to evidence-agent; reading a method grants no
  data-access, collection, or source-code execution permission.

## Common Reasoning

Claim Verification and Evidence-Weighing Principles live in `diagnosis-overview`.
Tier routing and pitfall checks live in `tidb-knowledge-base`. These shared
contracts remain required even when no general fallback is read.

## On-demand References

- [General diagnosis fallback](references/general-diagnosis-fallback.md):
  analyst-only, relevant sections only, when no applicable specialist covers a
  concrete reasoning question. Record the uncovered question and loaded section
  in `quality_checks`; record the reference path in `selected_diagnosis_skills`.
  It never overrides the role, canonical window, evidence gates, specialist
  contract, or report schema. Low confidence or missing data alone is not a
  reason to read it.
- [Collection reference](references/evidence-collection.md):
  standalone collection examples and artifact descriptions, not an extra
  prerequisite for the multi-agent collector path.

An expected specialist missing from the catalog or filesystem is a loading gap,
not proof that no specialist applies. Record its name/path and failure in
`quality_checks` and the output limitations. Continue bounded analysis with the
available family if useful, but do not silently replace the missing specialist
with general advice or declare the specialist contract complete.