Tidb Issue Metadata Guard

---
name: tidb-issue-metadata-guard
description: Use when creating or editing TiDB GitHub issues so issue templates, labels, issue titles, and issue descriptions stay consistent with repository workflow. Trigger on tasks involving issue creation, bug reports, enhancement tracking issues, label selection, or searching for existing issues and PRs before filing a new one.
---

# TiDB Issue Metadata Guard

## Overview

Use this skill for TiDB GitHub issue metadata updates.
The goal is to preserve issue-template structure, label hygiene, and searchable issue descriptions.

Before creating or editing an issue, read the matching file under `.github/ISSUE_TEMPLATE/`.

## Workflow

1. Write issue titles and descriptions in English.
2. Search existing issues and PRs first when the task is bug reporting or tracking an existing change.
3. When creating a new issue, start from the matching issue template instead of writing the body from scratch.
   - Follow the template and fill the required sections.
   - For bug reports, include minimal reproduction, expected behavior, actual behavior, and TiDB version information when available.
   - Fill issue fields with concrete values from the available artifacts instead of generic placeholders.
   - Keep the first screen readable: show the top-level repro summary, expected result, actual result, and version directly in the section body.
   - If a field is long, keep a short visible summary and put the full content in a `<details>` block.
     - Good candidates: full repro SQL, full schema, long logs, checksum diffs, execution plans, and plan replayer notes.
     - Do not hide the only reproduction steps or the top-level expected/actual conclusion inside `<details>`.
   - If supporting artifacts exist, mention them explicitly in the repro steps or attachments summary.
   - When adding an analysis section, keep it short and evidence-backed:
     - 1–3 likely causes at most
     - prefer evidence from SQL shape, plans, errors, or result diffs
4. When editing an existing issue, start from the current issue body instead of rewriting it from scratch.
   - Fetch the current title, body, and labels first.
   - Patch only the intended template sections and preserve untouched sections, metadata, and still-valid context.
   - Re-apply the same content rules used for new issues: concrete values, visible top-level summary, `<details>` for long raw artifacts, and short evidence-backed analysis when needed.
5. When applying labels, do it explicitly instead of assuming the UI or template will fill them in.
   - For new issues created with `gh issue create`, add labels explicitly when the GitHub UI would normally auto-apply them.
   - For existing issues, prefer `gh issue edit` so labels reflect the current state after the body update.
   - Add at least one `component/*` label.
   - For bug or regression issues, add `severity/*` and affected-version labels when appropriate.
   - Severity labeling rule:
     - Wrong-result bugs: use `severity/major`.
     - Query fails to execute on valid SQL, for example an internal planner or runtime error: use `severity/major`.
     - Complex-query or compatibility issues that are not confirmed wrong-result and are not execution-blocking: use `severity/moderate`.
   - If label permissions are missing, first add labels by commenting `/label <label name>`.
   - If label comments still do not work, add a separate comment with `Suggested labels: ...`.
6. Prefer file-based edits for GitHub metadata.
   - Materialize the intended issue body in a local Markdown file.
   - For new issues, review that file against the matching issue template before calling `gh`.
   - For existing issues, diff the patched body against the current issue body before calling `gh`.

## Quick Checks

- The issue title and body are in English.
- The issue still follows the matching template structure.
- Long raw artifacts are folded with `<details>` when needed, while the top-level summary remains visible.
- Existing issue edits preserve untouched sections and metadata outside the intended patch.
- The issue carries the expected labels, or a follow-up label comment / `Suggested labels: ...` comment is present when label permissions are missing.