---
name: transaction-or-lock-contention
description: Diagnose lock contention, deadlocks, write conflicts, and transaction-path root causes from collected evidence.
---

# Use When

Use this family subskill when the primary mechanism is lock contention, transaction
conflict, stale/follower read anomaly, commit/prewrite/lock-resolution behavior, or
transaction backoff.

# Required Evidence

- Logs or metrics for deadlock, lock wait timeout, write conflict, pessimistic lock retry,
  `PessimisticLockNotFound`, or transaction backoff.
- Workload shape showing conflicting write/update/point-get patterns.
- Affected SQL/table/key/region scope when available.

# Classification

- `standard_root_cause_class`: `transaction_or_lock_contention`
- compatible `primary_class`: `lock_or_transaction_contention`
- common symptom tags: `lock_wait`, `slow_query`, `tikv_hotspot`
- specialist skills: `transaction-oncall-handbook`

# Specialist Loading Contract

When `transaction_or_lock_contention` is the selected primary class or any
task-selected route (including multi-branch Copilot), you must
load the cataloged `transaction-oncall-handbook` from:

```text
.opencode/.all-skills/nutshell-skills/diagnosis/transaction-oncall-handbook/SKILL.md
```

Load its root `SKILL.md` plus at most one reference that matches the confirmed
transaction mechanism. Choose the reference from evidence such as deadlock,
lock-wait timeout, write conflict, pessimistic-lock lifecycle, stale/follower
read, or commit/prewrite behavior; do not read every known case.

When this family is only an analyst-discovered contributing candidate, load the
handbook when confidence is at least `0.60` and its mechanism changes remediation.
An optional-skill budget must not drop a task-selected family's required specialist.

Use the handbook only to interpret existing evidence. It does not authorize
Clinic/O11Y collection, repository searches, or matching a known issue from
keywords alone. Record `transaction-oncall-handbook` in
`selected_diagnosis_skills` when it is loaded. If the cataloged path is absent,
record that limitation and continue with this family subskill; do not substitute
an unrelated specialist.

# Decision Rules

- Prefer this class over SQL plan when lock evidence explains tail latency better than scan
  or plan cost.
- Treat CDC `not_leader`, PD logs, or background scheduling as context unless they explain
  the lock path directly.
- Do not call lock contention primary from isolated deadlocks with no aligned latency or
  workload impact.

# Final Response Anchors

- Name the exact transaction signal: `deadlock`, `lock wait timeout`, `write conflict`,
  `pessimistic lock retry`, or `PessimisticLockNotFound`.
- Explain whether the issue is application contention, known transaction behavior, or a
  version-specific bug/workaround.