New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

TiDB Test Diff Triage

by pingcap in pingcap/tidb

Investigates TiDB plan or test-result diffs that the change does not explain, ruling out failpoint setup and merge effects before expected outputs are updated.

Apache-2.0Auto-check passedTesting & QA

Install TiDB Test Diff Triage

skills CLI
$ npx skills add pingcap/tidb --skill tidb-test-diff-triage -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install pingcap/tidb tidb-test-diff-triage --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/pingcap/tidb.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/tidb-test-diff-triage .claude/skills/tidb-test-diff-triage && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
tidb-test-diff-triage
GitHub stars
41k
Token cost
~498 tokens
SKILL.md length
239 words
Files
1
Skills in repo
9
Repo updated
First seen
Licence
Apache-2.0

At a glance

Investigates TiDB plan or test-result diffs that the change does not explain, ruling out failpoint setup and merge effects before expected outputs are updated.

  • Works in 3 steps: Reproduce with minimal target (-run… → Compare good/bad commits and bisect the… → Identify first bad commit before…
  • A TiDB test or plan diff appears that the PR's code changes do not explain
  • SKILL.md covers Trigger, Rule 1: rule out failpoint…, Rule 2: isolate merge impact and Rule 3: update testdata only…, plus 1 more section
  • Calls git and go

What it does

The workflow applies when a test diff shows up that the touched code cannot explain, when a single test and the full suite give different output, or when planner and executor testdata change after a merge or rebase. The first rule is to rule out failpoint setup: many TiDB tests depend on failpoint instrumentation, and the `intest,deadlock` build tags do not enable it. The agent checks the project's failpoint decision guide for the affected package and reruns with failpoints on and `-count=1`. If the diff disappears, it is an environment issue rather than a logic regression.

If failpoints are not the cause, the agent reproduces with a minimal `-run` target, compares good and bad commits and uses `git bisect` to find the first bad commit. Expected plans or results are updated only once the cause is proven, such as an intentional upstream optimizer change or a stale expectation with unchanged query semantics. Investigation notes follow a fixed set of headings: symptom, scope, failpoint check, first bad commit, conclusion and action.

When your agent uses it

  • A TiDB test or plan diff appears that the PR's code changes do not explain
  • A single test passes but the full suite produces different output
  • Planner or executor testdata changed after a merge or rebase

Example prompts

  • “This explain test now shows a different plan, but my PR only touched the executor. Triage the diff.”
  • “TestPlanCache passes alone but fails in the full suite. Check whether failpoints are the cause.”
  • “Bisect the merged range to find the first commit that changed the planner testdata.”

Requirements

  • A TiDB repository checkout with the Go toolchain
  • Git for bisecting

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. Reproduce with minimal target (-run -count=1).
  2. Compare good/bad commits and bisect the merged range.
  3. Identify first bad commit before updating expected outputs.

What it can do on your machine

Read from SKILL.md and the folder at commit 7a3dacb. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • git
    • go

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

TiDB Test Diff Triage loads about 498 tokens when it runs. Until then it costs about 36 tokens; SKILL.md has 239 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~36
When it runs · the whole SKILL.md, loaded when a task matches
~498

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from pingcap/tidb at commit 7a3dacb, republished under its Apache-2.0 licence (© pingcap). 239 words, ~498 tokens.

Download SKILL.mdSave it as .claude/skills/tidb-test-diff-triage/SKILL.md (or your agent's skills folder).
name
tidb-test-diff-triage
description
Investigate unexpected TiDB plan or test-result diffs unexplained by the change, including merge and environment effects.

TiDB Test Diff Triage

Trigger

Use this workflow when:

  • A test diff appears, but touched code in the PR does not explain that behavior change.
  • A single test run and full-suite run produce different outputs.
  • Planner/executor testdata changed unexpectedly after merge/rebase.

Rule 1: rule out failpoint setup first

In TiDB, many test behaviors rely on failpoint instrumentation. -tags=intest,deadlock does not enable failpoints.

  • Use docs/agents/testing-flow.md -> Failpoint decision for unit tests against the affected package.
  • If any hit exists, rerun with Failpoint-enabled run and add -count=1 to the go test command for reproducibility.
  • If the diff disappears after failpoint enable, classify it as an environment/setup issue instead of a logic regression.

Rule 2: isolate merge impact

If failpoint is not the cause:

  1. Reproduce with minimal target (-run <TestName> -count=1).
  2. Compare good/bad commits and bisect the merged range.
  3. Identify first bad commit before updating expected outputs.

Useful commands:

bash
git bisect start
git bisect bad <bad_commit>
git bisect good <good_commit>

Rule 3: update testdata only after the cause is proven

Only sync expected plan/result when one of these is true:

  • Upstream merge intentionally changed optimizer behavior.
  • Existing test expectation is stale but query semantics are unchanged.

Do not record/update testdata before root cause is identified.

Output format for investigation notes

  • Symptom: what diff changed.
  • Scope: single test vs full suite.
  • Failpoint check: commands and result.
  • First bad commit: hash and title (if bisected).
  • Conclusion: setup issue / upstream behavior change / local regression.
  • Action: rerun with failpoint, sync expected, or continue fixing code.

© pingcap, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/tidb-test-diff-triage of pingcap/tidb.

Open the folder on GitHubat commit 7a3dacb

Compare with similar skills

TiDB Test Diff Triage next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

TiDB Test Diff Triage compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
TiDB Test Diff Triage this skillpingcap/tidb41k—~498Automated safety check: PassApache-2.0
Regression Root Cause AnalyzerArabelaTso/Skills-4-SE253—~3.4kAutomated safety check: PassApache-2.0
Debugging and Error Recoveryaddyosmani/agent-skills102k1 repos~2.6kAutomated safety check: PassMIT
Debuggnomeria/usbtree688—~715Automated safety check: PassMIT
Investigateblueberrycongee/termcanvas406—~562Automated safety check: PassMIT
Targeted Emergency Bug FixVeryGoodOpenSource/vgv-wingspan108—~1.9kAutomated safety check: PassMIT

Similar skills

  • Regression Root Cause Analyzer

    ArabelaTso/Skills-4-SE

    Locate root causes of failing regression tests by analyzing code changes, error messages, and test dependencies.

    253 GitHub stars~3.4k tokensUpdated 1 mo ago
    Testing & QAAuto-check passed

  • Debugging and Error Recovery

    addyosmani/agent-skills

    Applies a stop-the-line rule and a step-by-step triage when tests fail, builds break or something stops working, aiming at the root cause instead of guesses.

    102k GitHub starsUsed in 1 repo~2.6k tokens
    DevelopmentAuto-check passed

  • Debug

    gnomeria/usbtree

    Systematic root-cause debugging — reproduce, isolate, fix at the source, prove the fix.

    688 GitHub stars~715 tokensUpdated 1 mo ago
    DevelopmentAuto-check passed

  • Investigate

    blueberrycongee/termcanvas

    Systematic debugging skill. An agent skill from blueberrycongee/termcanvas.

    406 GitHub stars~562 tokensUpdated 4 mo ago
    DevelopmentAuto-check passed

  • Targeted Emergency Bug Fix

    VeryGoodOpenSource/vgv-wingspan

    Applies a minimal fix to an emergency bug through triage, root-cause location, a hotfix branch and a blast-radius check, with tests and review still required.

    108 GitHub stars~1.9k tokensUpdated 7 days ago
    DevelopmentAuto-check passed

  • Flowfile Failure Archaeology

    Edwardvaneechoud/Flowfile

    Chronicles 25+ major incidents in Flowfile's git history (worker/kernel deadlocks and races, reverted or self-reverted branches, Electron/Tauri packaging breakage, codegen correctness bugs, CI…

    370 GitHub stars~7.5k tokensUpdated yesterday
    DevelopmentAuto-check passed

More from pingcap/tidb

All 9 skills in this repo

  • TiDB Bazel Prepare Gate

    pingcap/tidb

    Decides from local git changes whether make bazel_prepare must run in TiDB before build or test commands, and reports the evidence for the decision.

    41k GitHub stars~408 tokensUpdated today
    Auto-check passed

  • TiDB Failpoint Test Runner

    pingcap/tidb

    Use when running TiDB package tests and deciding whether failpoint enable/disable is required before and after the test command.

    41k GitHub stars~256 tokensUpdated today
    Auto-check passed

  • TiDB Integration Test Recorder

    pingcap/tidb

    Use when recording TiDB integration tests under tests/integrationtest and verifying regenerated result files stay minimal and correct.

    41k GitHub stars~260 tokensUpdated today
    Auto-check passed

  • TiDB RealTiKV Test Runner

    pingcap/tidb

    Use when running tests under tests/realtikvtest that require a local TiUP playground lifecycle with strict startup, readiness checks, and cleanup.

    41k GitHub stars~250 tokensUpdated today
    Auto-check passed

  • TiDB Change Instruction Critic

    pingcap/tidb

    Checks a fix proposed by a user or reviewer for intent, correctness and compatibility before the agent implements it in the TiDB codebase.

    41k GitHub stars~523 tokensUpdated today
    Auto-check passed

  • TiDB Issue Metadata Guard

    pingcap/tidb

    Keeps TiDB GitHub issues consistent by following the issue templates, writing reproducible reports, checking for duplicates and applying labels explicitly.

    41k GitHub stars~1k tokensUpdated today
    Auto-check passed

Works with

Categories

Questions about TiDB Test Diff Triage

What does TiDB Test Diff Triage do?

Investigates TiDB plan or test-result diffs that the change does not explain, ruling out failpoint setup and merge effects before expected outputs are updated. The workflow applies when a test diff shows up that the touched code cannot explain, when a single test and the full suite give different output, or when planner and executor testdata change after a merge or rebase. The first rule is to rule out failpoint setup: many TiDB tests depend on failpoint instrumentation, and the `intest,deadlock` build tags do not enable it.

When should I use TiDB Test Diff Triage?

TiDB Test Diff Triage fits situations like: A TiDB test or plan diff appears that the PR's code changes do not explain; A single test passes but the full suite produces different output; planner or executor testdata changed after a merge or rebase.

How do I install TiDB Test Diff Triage in Claude Code?

Run `npx skills add pingcap/tidb --skill tidb-test-diff-triage -a claude-code`. Or copy the skill folder (.agents/skills/tidb-test-diff-triage in pingcap/tidb) into .claude/skills/tidb-test-diff-triage in your project. Claude Code loads it when a task matches its description.

How do I install TiDB Test Diff Triage in Codex?

Run `npx skills add pingcap/tidb --skill tidb-test-diff-triage -a codex`. Or copy the skill folder (.agents/skills/tidb-test-diff-triage in pingcap/tidb) into .agents/skills/tidb-test-diff-triage in your project. Codex loads it when a task matches its description.

Can I use TiDB Test Diff Triage in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add pingcap/tidb --skill tidb-test-diff-triage -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/tidb-test-diff-triage, .gemini/skills/tidb-test-diff-triage, .github/skills/tidb-test-diff-triage and .opencode/skills/tidb-test-diff-triage in your project.

What does TiDB Test Diff Triage need to run?

Going by SKILL.md and its folder, TiDB Test Diff Triage needs the command-line tools its instructions call (git and go). Our summary lists: A TiDB repository checkout with the Go toolchain; Git for bisecting.

Does TiDB Test Diff Triage access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is TiDB Test Diff Triage safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does TiDB Test Diff Triage use?

TiDB Test Diff Triage is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does TiDB Test Diff Triage use?

About 498 tokens (SKILL.md is roughly 2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to TiDB Test Diff Triage?

Skills that share tags, products or a category with TiDB Test Diff Triage: Regression Root Cause Analyzer (ArabelaTso/Skills-4-SE, 253 stars), Debugging and Error Recovery (addyosmani/agent-skills, 102k stars), Debug (gnomeria/usbtree, 688 stars) and Investigate (blueberrycongee/termcanvas, 406 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains TiDB Test Diff Triage?

pingcap (a GitHub organization) maintains it in pingcap/tidb, which has 40,631 GitHub stars. The repository holds 9 skills in this directory. The repository was last updated on October 7, 2026.

Source: pingcap/tidb on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.