git:20260313.dc96c00 to git:20260402.b298d60
13 added, 6 removed. Audit A to A.
# TiDB Query Tuning Agent Notes
Use this skill directory for two different knowledge sources:
- curated topic references under `references/`
- GitHub issue-derived field experience generated into markdown files
## When to mine issue experience
Use GitHub issue mining when:
- the local references do not cover a customer-facing symptom well enough
- you need a recent field precedent instead of a general tuning rule
- you want fix PRs, merge timestamps, and open issue reminders
- - you want to build or refresh a local corpus of customer-driven planner or stats bugs
+ - you want to build or refresh a local corpus of planner or stats bugs, with `report/customer` issues preferred when they exist
Do not start from issue mining if a stable reference under `references/` already answers the question. Use the issue corpus to complement the topic docs, not replace them.
## Default workflow
1. Start with the local references in `references/`.
2. Search `references/optimizer-oncall-experiences-redacted/` for a symptom match.
3. Search `references/tidb-customer-planner-issues/` if you need linked PRs, merge times, or still-open customer gaps.
- 4. If the local corpora are still missing the pattern, mine GitHub issues with the script in `scripts/`.
- 5. Review the generated files, then fold reusable learnings back into the relevant reference docs when appropriate.
+ 4. If the most relevant recent planner issue does not carry `report/customer`, do not exclude it for that reason alone. Broaden the GitHub query and inspect it directly.
+ 5. If the local corpora are still missing the pattern, mine GitHub issues with the script in `scripts/`.
+ 6. Review the generated files, then fold reusable learnings back into the relevant reference docs when appropriate.
## Issue mining script
Use:
`scripts/generate_tidb_issue_experiences.py`
The script:
- searches GitHub issues with a provided query
- follows issue timeline cross-references and explicit fix comments
- collects linked PR metadata and changed files
- writes one markdown file per issue
- writes an index `README.md` into the output directory
The current checked-in issue corpus lives under:
- `references/tidb-customer-planner-issues/`
## Recommended query patterns
- For customer-driven planner issues:
+ Preferred query for customer-driven planner issues:
```text
repo:pingcap/tidb is:issue label:"report/customer" label:"sig/planner" created:>=2024-01-01
```
- For stats-heavy issue mining:
+ Fallback query for recent planner issues when `report/customer` is missing but the issue is still highly relevant:
```text
+ repo:pingcap/tidb is:issue label:"sig/planner" created:>=2024-01-01
+ ```
+
+ Preferred query for stats-heavy issue mining:
+
+ ```text
repo:pingcap/tidb is:issue label:"report/customer" (label:"sig/planner" OR label:"sig/execution") stats created:>=2024-01-01
```
- Adjust the query rather than hardcoding different behaviors into the script.
+ Adjust the query rather than hardcoding different behaviors into the script. `report/customer` is a prioritization signal, not a hard requirement.
## Usage example
```bash
python3 skills/tidb-query-tuning/scripts/generate_tidb_issue_experiences.py \
--query 'repo:pingcap/tidb is:issue label:"report/customer" label:"sig/planner" created:>=2024-01-01' \
--out-dir outputs/tidb-customer-planner-issues
```
## What to keep from generated issue files
Keep and reuse:
- customer-facing symptom descriptions
- investigation clues
- linked fix PRs
- merge timestamps
- affected modules
- open issues that should remain on the reminder list
Do not treat every generated issue as a mature tuning rule. Generated files are raw field precedents. Promote them into `references/` only after the pattern is stable and reusable.
## Tooling assumptions
- `gh` CLI must be installed and authenticated
- network access to GitHub must be available
- the output directory should be treated as generated content
## Editing guidance
- Keep curated docs in `references/` concise and topic-oriented.
- Keep generated issue corpora outside the hand-written topic docs unless they are intentionally promoted.
- If you regenerate a corpus, prefer writing into a fresh output directory or knowingly replacing the previous generated set.