---
name: tidb-code-context
description: Read a fixed-SHA TiDB or TiKV source context through backend-controlled bare Git mirrors.
---

# TiDB / TiKV code context

Use this only when the main investigator explicitly delegates a code-mechanism
question with a full 40-character SHA for the selected TiDB or TiKV repository. It is not a Git client and it never
downloads code.

Run only the permitted helper:

```bash
/app/.venv/bin/python .opencode/skills/builtin/tidb-code-context/scripts/code_context.py prepare --repo <pingcap/tidb|pingcap/tikv> --sha <SHA>
/app/.venv/bin/python .opencode/skills/builtin/tidb-code-context/scripts/code_context.py inspect --context <CONTEXT_ID> --anchor 'CPUTimeMs' --anchor 'getReportRecords' --path-hint pkg/util/topsql
```

The helper returns source lines annotated as `path:line`; the top-level
`context_id` is the fixed-SHA provenance. The backend reads Git objects on
demand from its shared bare mirror; it does not create a checkout, worktree, or
per-SHA snapshot. The source context includes the complete selected commit,
including test files and testdata. Do not expose an absolute cache path, run `git`, fetch,
clone, or use arbitrary shell commands.
Do not append pipes, redirects, `head`, `sed`, or other shell syntax to helper
commands: the helper itself enforces output limits.

For normal source analysis, use exactly two helper calls: `prepare` once, then
`inspect` once. `inspect` is the bounded, script-owned analysis loop: it finds
the semantic anchors, ranks optional path hints, deduplicates and merges nearby
matches, and returns up to eight source windows in one response. It reports
whether its bounded context was truncated. `refinement_available` is a bounded
state transition: when the initial `inspect` returns `true`, call
`inspect-refine` once before submitting the artifact. A second and final
`inspect-refine` is allowed only if the first refinement leaves a specific
unanswered source question. Each refinement must add at least one semantic
anchor not used by the preceding inspection, or at least one path hint not used
by the preceding inspection; never repeat the same anchors and path hints.
After the second refinement, submit the artifact. When `refinement_available`
is `false`, do not call `inspect-refine`. Do not call `discover`, `search`, or
`read-many`; they remain
compatibility commands for non-agent maintenance only. Anchors are literal
source identifiers or stable strings, not natural-language combinations;
path hints only rank results and may be absent or stale. An
`inspect-refine` result with `matched=false` and
`error="no source matches for semantic anchors"` is a recoverable miss, not a
broken context: retain the previous successful ranges and retry only with
literal identifiers observed in them, or proceed with the existing evidence.
The `prepare` result includes SHA-derived `navigation` data (language, build
manifests, and top-level directories). Treat that result, rather than any
static repository-path assumption, as the layout guide for this commit.

The backend validates the final artifact against the immutable source commit in
the bare mirror before persisting it. Do not use local artifact-validation helpers:
backend persistence is the only delivery check.

Return exactly the raw JSON object specified by the `code-investigator` agent
prompt. Do not add a marker, XML wrapper, markdown fence, commentary, or any
text before or after the object. The backend validates that exact Task result
and atomically writes the fixed handoff path. Do not use generic file-writing,
submit, or validation commands. The result proves only source behavior at that
SHA. Return runtime predictions and falsifiers to the main investigator, which
must corroborate them with logs, metrics, profiles, configuration or incident
evidence.

## Read-only source history

For a bounded question about a regression, introduction, ownership, or prior
implementation, use the same selected workspace repository's history views:

```bash
/app/.venv/bin/python .opencode/skills/builtin/tidb-code-context/scripts/code_context.py history-log --context <CONTEXT_ID> --path pkg/util/topsql
/app/.venv/bin/python .opencode/skills/builtin/tidb-code-context/scripts/code_context.py history-blame --context <CONTEXT_ID> --path pkg/util/topsql/foo.go --start 40 --end 70
/app/.venv/bin/python .opencode/skills/builtin/tidb-code-context/scripts/code_context.py history-show --context <CONTEXT_ID> --commit <40-CHAR-ANCESTOR-SHA>
/app/.venv/bin/python .opencode/skills/builtin/tidb-code-context/scripts/code_context.py history-diff --context <CONTEXT_ID> --from <OLDER-40-CHAR-SHA> --to <NEWER-40-CHAR-SHA>
```

`history-log` returns at most 30 first-parent commits; `history-blame` accepts
at most 200 lines. `history-show` and `history-diff` accept only full commits
reachable from the selected SHA; diff commits must be ordered ancestors. Their
output is capped. Do not run more than one log, one blame, and one show or diff
per diagnosis unless the first result names a specific unresolved historical
question. Never use history to claim that a production incident occurred.