Skip to content

Commit e1edcec

Browse files
JmPotatoJmPotato
committed
docs: expand repo skill documentation
Signed-off-by: JmPotato <github@ipotato.me>
1 parent 76ebf52 commit e1edcec

4 files changed

Lines changed: 136 additions & 13 deletions

File tree

‎.agents/skills/add-metrics/SKILL.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,45 @@ name: add-metrics
33
description: "Add or change Prometheus metrics — cache WithLabelValues, hot path, cleanup, avoid high cardinality, naming, MustRegister, backward compatibility. From tikv/pd metrics PRs."
44
---
55

6+
# Add Metrics
7+
8+
## Responsibility
9+
10+
Add or change Prometheus instrumentation in `tikv/pd` without regressing hot
11+
paths, exploding label cardinality, or silently breaking dashboards and alerts.
12+
13+
## Inputs
14+
15+
- target package, file, or code path to instrument
16+
- metric definition: namespace, subsystem, name, help text, type, unit, and
17+
labels
18+
- lifecycle context: where the entity is created, updated, and removed
19+
- rollout context: existing metrics, dashboards, alerts, or compatibility
20+
constraints that must remain stable
21+
22+
## Outputs
23+
24+
- a patch that updates metric definitions, registration, record sites, cleanup
25+
sites, and related tests or docs when needed
26+
- a short implementation note covering label choices, hot-path tradeoffs, and
27+
backward-compatibility or migration impact
28+
- if the requested metric is unsafe, a concrete alternative such as a lower
29+
cardinality design or background aggregation
30+
31+
## Constraints
32+
33+
- cache `WithLabelValues(...)` results instead of recomputing them in hot paths
34+
- avoid per-request or per-event metric creation on hot paths; prefer background
35+
aggregation when feasible
36+
- keep label cardinality bounded and add cleanup via `DeleteLabelValues(...)`
37+
when entities disappear
38+
- do not rename, remove, or change the type of an existing metric without an
39+
explicit migration or rollout plan
40+
- use `prometheus.MustRegister(...)` and keep dashboards, alerts, and docs
41+
aligned with the final metric semantics
42+
- if a metric is expensive, noisy, or experimental, prefer an existing toggle or
43+
rollout gate instead of unconditional always-on instrumentation
44+
645
## Principles (checklist + detail)
746

847
Before adding or changing metrics, ensure:
@@ -32,3 +71,15 @@ Before adding or changing metrics, ensure:
3271
12. **Fix wrong metrics and document semantics** — If a metric measures the wrong thing (e.g. “processing time” including network), fix the measurement or add a new metric/version; do not silently change semantics.
3372

3473
13. **Instrument full lifecycle** — For gRPC streams or long-lived resources, add metrics for the full lifecycle and reflect cleanup/end so dashboards don’t show stuck or misleading series.
74+
75+
## Usage Examples
76+
77+
- Add a counter or histogram in a scheduler or API path, but cache
78+
`WithLabelValues(...)` during init and only record the fast-path value in the
79+
request handler.
80+
- Add a gauge vector for long-lived resources such as streams, stores, or
81+
groups, and pair creation with `DeleteLabelValues(...)` on teardown so old
82+
series disappear.
83+
- Replace or supplement an incorrect metric by introducing a new metric with the
84+
right semantics while keeping the old metric stable until dashboards and
85+
alerts have migrated.

‎.agents/skills/create-pr/SKILL.md‎

Lines changed: 43 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,50 @@ description: Push the current branch and create a pull request on tikv/pd follow
44
compatibility: Requires gh CLI authenticated with tikv/pd repo access. Must have local commits on a non-master branch.
55
---
66

7-
# Persona & Goal
7+
# Create PR
88

9-
PD contributor assistant. Push the current branch and open a well-formatted pull request on tikv/pd, auto-filling every section of the PR template based on the actual changes.
9+
## Responsibility
10+
11+
Push the current branch and open a pull request on `tikv/pd` that matches the
12+
repository template and review expectations.
13+
14+
## Inputs
15+
16+
- current branch name, base branch, and committed diff to be submitted
17+
- issue references and whether they should be `Close` or `ref`
18+
- `.github/pull_request_template.md` plus
19+
`references/pr-template.md` for the exact PR structure
20+
- optional head repository or remote details when the PR comes from a fork
21+
22+
## Outputs
23+
24+
- a validated PR title and body draft shown to the user before submission
25+
- a pushed branch with upstream tracking information
26+
- a created PR URL, or a blocking error if push/auth/template validation fails
27+
28+
## Implementation Details
29+
30+
- Validation commands are `git status`, `git branch --show-current`,
31+
`git log --oneline master..HEAD`, `git diff master...HEAD --stat`, and
32+
`git diff master...HEAD`.
33+
- PR content must be rendered from `.github/pull_request_template.md` and
34+
`references/pr-template.md`, not improvised from memory.
35+
- Push with `git push -u origin <branch-name>` unless the user specifies a
36+
different remote or head repo.
37+
- Create the PR with `gh pr create --repo tikv/pd ... --body-file -` so the
38+
template formatting survives.
39+
- Do not bypass local hooks with `--no-verify`; if a push hook or auth check
40+
blocks the operation, surface the error instead of silently skipping it.
41+
42+
## Constraints
43+
44+
- Never force-push without user confirmation.
45+
- Always show the PR content before submitting. User approval is required.
46+
- Use `gh` for GitHub operations. Do not guess API URLs.
47+
- Follow PD commit conventions when deriving the PR title.
48+
- Ask for the issue number when it is unknown.
49+
- Do not invent issue references.
50+
- Do not modify code or rewrite commits as part of this skill.
1051

1152
# Reference Files
1253

@@ -61,12 +102,3 @@ If the push or PR creation fails:
61102
- **Push rejected**: Check if the remote branch exists; suggest force-push only if user confirms.
62103
- **PR already exists**: Show the existing PR URL; offer to update it instead.
63104
- **Auth failure**: Remind user to authenticate with `gh auth login`.
64-
65-
# Agent Constraints
66-
67-
- **Never force-push without user confirmation.**
68-
- **Always show the PR content before submitting.** User must approve title and body.
69-
- **Use `gh` CLI for GitHub operations.** Do not guess API URLs.
70-
- **Follow PD commit conventions.** `pkg: message` format for title.
71-
- **Do not modify code.** This skill only pushes and creates PRs.
72-
- **Ask for issue number if unknown.** Do not invent issue references.

‎.agents/skills/fix-cherry-pick-pr/SKILL.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,33 @@ description: Repair cherry-pick pull requests in tikv/pd when automated cherry-p
1010
Repair and verify cherry-pick PRs in `tikv/pd`.
1111
Compare the source PR and the cherry-pick PR first, then fix the cherry-pick branch without losing release-branch-only code.
1212

13+
## Inputs
14+
15+
- source PR number, or a cherry-pick PR that points back to the source PR
16+
- cherry-pick PR number, head branch, and the remote that owns that branch
17+
- touched files or packages that need parity and targeted verification
18+
- release branch context that may contain branch-only APIs, helpers, or tests
19+
20+
## Outputs
21+
22+
- a repaired cherry-pick branch or PR with committed conflict markers removed
23+
- a semantic parity report against the source PR, including any intentional
24+
release-branch-only differences
25+
- targeted verification commands and results, especially for failpoint-sensitive
26+
code paths
27+
28+
## Implementation Details
29+
30+
- Preserve release-branch-only behavior by comparing the final aggregate patch,
31+
not raw commit count or GitHub mergeability state.
32+
- When conflict markers land beside release-only APIs or helpers, keep the
33+
release-branch code and insert the source PR behavior in the correct final
34+
location instead of deleting branch-only code.
35+
- Validate failpoint-sensitive diffs with the repo's explicit failpoint flow:
36+
`make failpoint-enable`, targeted `go test`, then `make failpoint-disable`.
37+
- Core commands in this workflow are `gh pr view`, `gh pr diff`, `diff -u`,
38+
`rg -n '<<<<<<<|=======|>>>>>>>'`, `git diff`, `git status`, and `git push`.
39+
1340
## 1. Identify the PR pair
1441

1542
- Inspect the cherry-pick PR with `gh pr view <pr> --repo tikv/pd --json number,title,body,baseRefName,headRefName,headRepositoryOwner,url,commits`.

‎AGENTS.md‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,5 +71,18 @@
7171

7272
## Repo-Specific Skills
7373
- Reusable agent workflows live in `.agents/skills/`.
74-
- `fix-cherry-pick-pr`: repairs PD cherry-pick PRs while preserving release-branch-only behavior and validating failpoint-sensitive diffs.
75-
- `create-pr`: pushes the current branch and opens a PR that matches the PD template.
74+
- [`add-metrics`](.agents/skills/add-metrics/SKILL.md): adds or changes PD
75+
Prometheus instrumentation. Inputs: target package or file plus metric name,
76+
type, labels, and rollout context. Outputs: metric patch and migration notes.
77+
Constraints: cache `WithLabelValues`, avoid hot-path instrumentation, control
78+
cardinality, and keep existing metrics backward compatible.
79+
- [`fix-cherry-pick-pr`](.agents/skills/fix-cherry-pick-pr/SKILL.md): repairs
80+
release-branch cherry-pick PRs. Inputs: source PR, cherry-pick PR or branch,
81+
and touched files or tests. Outputs: repaired branch plus parity and
82+
verification report. Constraints: preserve release-branch-only behavior,
83+
compare final aggregate diffs, and follow PD failpoint discipline.
84+
- [`create-pr`](.agents/skills/create-pr/SKILL.md): pushes the current branch
85+
and opens a PR that matches the PD template. Inputs: current branch,
86+
committed diff, issue refs, and template context. Outputs: reviewed title and
87+
body draft, pushed branch, and PR URL. Constraints: show the draft before
88+
submission, use `gh`, and never force-push without approval.

0 commit comments

Comments
 (0)