---
name: diag-cluster
description: |
  Read-only diagnosis for Dedicated Cluster CR lifecycle
  (Pending/Creating/Scaling/Unavailable, stuck create, scale status,
  dataplane TiDBCluster/Pods). Use when cluster_id is known and the issue is
  infra Cluster CR / APPBox dependency / DP workload readiness. Not for
  TiKV/PD deep performance.
---

# Action Type

`read-only`

# Path note

Resolve shared docs from the skill root (`dedicated-cloud-diag/`):
`references/method-*`, `references/patterns/*`, `references/evidence/*`,
`references/object-graph.md`. Domain-local docs live under this subskill as
`diag-cluster/references/` (cases and provider-* files).

# Data methods

- Default curated Cluster: `references/method-cluster-cr/METHOD.md` (skill root)
- CP/DP Kind Get/List: `references/method-k8s-resource/METHOD.md` (skill root)
- Read method files before first fetch of that kind.

# Required patterns

Before running: Entry already applied `entry-preflight` + `diag-trace`.
Also apply as named: `provider-branch`, `healthy-exit`, `fetch-retry-bypass`,
`skill-boundary-assist`. Object edges: `references/object-graph.md` (skill root).

# Inputs

| Input | Required |
|-------|----------|
| `cluster_id` | hard |
| `env` | optional (toolkit default) |
| symptom | optional |

# Quick Routing (ByCase)

| Signal | Open |
|--------|------|
| Phase Pending/Creating stuck; APPBox not ready | `diag-cluster/references/case-creating-stuck.md` |
| Phase Scaling / scale progress unclear | `diag-cluster/references/case-scale-status.md` |
| APPBox Active but TiDBCluster/Pods not Ready | `diag-cluster/references/case-tidbcluster-not-ready.md` |

If a case matches, follow it first; otherwise top-down below.

# Top-down Procedure

All intents: execute via bound methods. Mark Gate/checklist evidence **hard**
unless noted soft.

1. **Fetch cluster_cr** (hard)  
   Intent: evidence `cluster_cr` by `cluster_id`.  
   Focus: `status.phase`, `spec.networkName`, `spec.kubernetes.provider`.  
   Establish `provider` (`provider-branch`). If provider missing →
   `blocked-uncertain`.

2. **APPBox Gate** (hard)  
   Intent: Plane=`CONTROL_PLANE`, GK=`APPBox`, name/ns from
   `cluster_cr.spec.networkName` (object-graph).  
   Focus: `status.phase`, `status.reason`.  
   - If not `Active` (or missing when expected) → `judgment=handoff`
     `diag-appbox` with `cluster_id`, APPBox name/ns, phase/reason, summary.
     Stop deep DP dig in this domain until APPBox cleared.  
   - If `Active` → continue.

3. **Phase branch**  
   - `Pending` / `Creating` → early controller tasks (Guardian, provider
     config, namespace, storage, then TiDBCluster). Prefer case-creating-stuck
     + provider file.  
   - `Scaling` → case-scale-status.  
   - `Running` with symptom on pods/components → case-tidbcluster-not-ready.  
   - No symptom → Health checklist.

4. **Dataplane TiDBCluster** (hard when create/scale path needs it)  
   Intent: Plane=`DATA_PLANE`, GK=`TidbCluster` (or v2 equivalent), scoped by
   `cluster_id` routing; name/ns from cluster convention / prior evidence.  
   Focus: Ready/conditions. Soft: events via detail+events.

5. **Dataplane Pods** (soft unless sole criterion)  
   Intent: Plane=`DATA_PLANE`, GK=`Pod`, ListByLabel for cluster/component.  
   Focus: phase, container status.

6. **Provider-specific**  
   Read `diag-cluster/references/provider-{eks,gke,aks}.md` matching context provider for
   extra intents (nodegroup/nodepool, IAM, PSC, etc.).

7. **Deeper cause**  
   If anomaly located but why needs controller logic: if
   `infra-provider/cluster-controller` is in workspace → `agent-read-code`
   (start at `controllers/cluster/taskbuilder.go` and the stuck task package).
   If cloud CLI needed → `skill-boundary-assist` user-assist card.

# Health checklist

Run per `healthy-exit` when no symptom or symptom path green. All **hard**:

1. `cluster_cr.status.phase` is `Running` (or user-accepted terminal for the ask).
2. APPBox Gate: APPBox `Active`.
3. If create recently finished: TiDBCluster Ready (or equivalent) green.
4. No Failed/Unavailable phase without explained residual.

All green → `judgment=healthy`, `Conclusion=no_current_anomaly` with checklist
boundary listed.

# Handoff

- APPBox not ready → `diag-appbox`
- Mutation needed → `dedicated-cloud-ops` (not this skill)
- Out of product scope → Entry `out-of-scope` (already handled)

# Output

Obey `references/patterns/diag-trace.md`.