---
name: cdc-or-replication-lag
description: Diagnose TiCDC replication lag, changefeed failure, owner/maintainer/dispatcher, and sink bottlenecks.
---

# Use When

Use this family subskill when the primary mechanism is TiCDC replication lag,
changefeed failure, owner/maintainer/dispatcher/scheduler bottleneck, sink bottleneck,
or downstream replication health.

# Required Evidence

- Changefeed identity and state from `clinic-cli ticdc list`; use `ticdc detail`
  only for the requested or abnormal kernel/internal changefeed ID.
- Checkpoint/resolved-ts lag, owner/maintainer metrics, processor or sink
  errors, dispatcher/scheduler metrics, downstream latency, or sink throughput evidence.
- Architecture classification for TiCDC new arch vs old arch when available.

# Classification

- `standard_root_cause_class`: `cdc_or_replication_lag`
- compatible `primary_class`: `service_unavailability_or_worker_failure` until schema is extended
- common symptom tags: `cdc_lag`, `network_latency`, `capacity_pressure`
- specialist skills: `ticdc-health-inspection`, `tikv-cdc`

# Specialist Loading Contract

When this family is a task-selected route (Copilot, Autopilot, or preferred
route), or an analyst-discovered primary class (including a classification
override from another route), load the cataloged `ticdc-health-inspection`
before synthesis:

```text
.opencode/.all-skills/nutshell-skills/diagnosis/ticdc-health-inspection/SKILL.md
```

Read its required `references/dashboard-mapping.md` and
`references/inspection-rules.md` together with the root. Apply the relevant
architecture and lag-stage rules to the existing incident evidence, not a new
30m/24h health sweep. A selected route is a hypothesis; the health verdict does
not by itself establish the incident root cause.

Load `tikv-cdc` additionally only when evidence points to the TiKV/CDC boundary
(upstream lock/state handling, endpoint or store identity changes, or CDC-related
TiKV failures). Resolve it at
`.opencode/.all-skills/nutshell-skills/diagnosis/tikv-cdc/SKILL.md` and read only
the reference matching the evidenced mechanism. Lag alone does not require it.

For an analyst-discovered contributing CDC candidate, load the health specialist
when its mechanism materially changes remediation. Keep all explicit task-selected
families; a per-dispatch optional-skill budget must not drop a selected branch.

Use these skills as read-only reasoning references: no direct data collection,
source searches, changes, or separate health-report workflow. Missing probes or
metadata go to `needs_more_evidence` with the exact gap; missing metrics do not
prove old architecture or no deployment. If a changefeed was expected but was
never deployed, preserve that incident as unresolved and examine creation/event
evidence rather than declaring it healthy from the health-audit rule alone.

Record actual loads in `selected_diagnosis_skills`. If a required catalog/path
is unavailable, record the loading gap explicitly; do not silently substitute
the general fallback or claim the specialist contract passed.

# Decision Rules

- Expect changefeed metadata collected through builtin `clinic-cli ticdc` in
  `evidences/queries.json`. As a read-only diagnosis skill, never execute Clinic
  yourself; when metadata is load-bearing and absent, request one supplemental
  evidence pass naming List and, if applicable, the exact Detail ID.
- Do not request DevOps merely to list changefeeds; use it only when a
  business/display ID must be mapped and Clinic metadata does not provide that
  mapping.
- Treat changefeed metadata as scope and state evidence, not as a complete root
  cause. Continue with the architecture-specific metric and log checks.
- Detail accepts the kernel/internal `id` returned by List, never `display_id`.
- Do not report missing TiCDC metrics as failure when metadata shows TiCDC is not deployed.
- Separate upstream TiKV/TiDB pressure from TiCDC owner/maintainer/sink bottleneck.
- For new arch, reason about maintainer/dispatcher/scheduler; for old arch, reason about
  owner lag and sink output.

# Final Response Anchors

- Name the changefeed, lag type, architecture, and bottleneck stage when available.
- State whether lag is upstream, TiCDC-internal, sink/downstream, or unknown.