# Feishu PD Oncall Handbook to PD Skill-Family Mapping

This document records how the Feishu PD handbook content was normalized into the current `pd-*` skill family.

## Source Document

- `PD oncall handbook`
  - Feishu: <https://pingcap.feishu.cn/wiki/E5KkwI6VJiFA4nkcaVEcDhWonqu>
  - Role in skill family: source umbrella, not a single monolithic skill

## Target PD Skill Family

- `skills/diagnosis/pd-oncall-handbook/SKILL.md`
- `skills/diagnosis/pd-placement-rules/SKILL.md`
- `skills/diagnosis/pd-scheduling/SKILL.md`
- `skills/diagnosis/pd-resource-control/SKILL.md`
- `skills/diagnosis/pd-operations/SKILL.md`

## Mapping Rules Used

- Keep one entry skill: `pd-oncall-handbook`
- Split by operational symptom family, not by original handbook chapter
- Keep `SKILL.md` files short and routing-oriented
- Put multi-case detail into `references/*.md`
- Use English only for normalized skill content
- Keep the prefix consistent: all PD skills begin with `pd-`

## Coverage by Skill

### Routed to `pd-placement-rules`

- leader imbalance after large placement-rule changes
- placement-rule reset after PD leader transfer
- override interactions between PD placement rules and placement rules in SQL
- missing `SURVIVAL_PREFERENCES` and lost location-label inheritance
- placement-rule disable side effects during GC
- missing isolation labels allowing multiple replicas on one host

### Routed to `pd-scheduling`

- patrol-region time stays high after repair
- Lightning scatter failures because regions are not healthy
- inconsistent TiKV region-size or key config causing bad PD metrics
- rebalance storms after low-space recovery and disk expansion
- scatter-region conflicts with placement or isolation constraints
- scatter-range conflicts with global balancing
- evict-leader scheduler add or remove failures

### Routed to `pd-resource-control`

- RU throttling by request priority
- long `Time_queued_by_rc` despite sufficient apparent quota
- config changes not taking effect because of wrong API path
- uneven TiDB workload causing RU drops on hot instances
- query-limit action support gaps
- PD panic while listing resource groups

### Routed to `pd-operations`

- ETCD capacity exhaustion
- Dashboard HA limitation
- Dashboard `database is locked`
- Dashboard filling `/tmp`
- PD leader CPU and TSO pressure
- Prometheus scrape timeout on PD leader metrics
- TLS enable or expansion failures

## Intentionally Deferred

These topics are still only partially represented in the first PD family pass and may need follow-up references:

- merge-region principles and more detailed merge-specific failure modes
- balance-range-scheduler crash and `DISTRIBUTE TABLE` corner cases
- advanced resource-control cases such as runaway, token NaN, or default-group observability
- Dashboard certificate and common-name edge cases

## Completion Notes

This mapping is an operational coverage artifact, not a line-by-line mirror of the Feishu page.

Completion standard used here:

- the main PD incident families from the Feishu handbook are represented in `pd-*` skills
- the entry skill routes to the right specialized PD skill quickly
- longer case detail can be moved into references without bloating the entry documents