pr-writing
Write or review clear commit messages, PR titles, and PR descriptions that explain what changed and why. Use before writing git history or when asked to improve it. Not for code comments, chat replies, or docs pages.
- License 许可
- MIT
- 最近更新
- 2026-10-21
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- pr-writing
- license
- MIT
- metadata
- { "version": "1.0.0" }
- description
- Write or review clear commit messages, PR titles, and PR descriptions that explain what changed and why. Use before writing git history or when asked to improve it. Not for code comments, chat replies, or docs pages.
02 资源文件 3
- 参考文档EXAMPLES.md5.7 KB
- 参考文档METHODOLOGY.md10.6 KB
- 参考文档RESPONSE.md1.4 KB
03 SKILL.md 正文
PR writing
Full rules: METHODOLOGY.md. Before/after: EXAMPLES.md. Chat shape: RESPONSE.md.
These are requirements, not preferences. A message that breaks one gets rewritten, not shipped.
Operating order
1. Read the diff first
git diff main...HEAD --stat then the real hunks. You cannot state why from a file list.
2. Write the subject (§1)
Under 50 characters. Capitalized. No period. Imperative mood.
Test every subject: "If applied, this commit will ___." If the sentence breaks, the subject is wrong.
Add retry guard to the token refresh path
Banned first words: Added, Adding, Adds, Fixed, Fixes, Updated, Changes, WIP, Misc, Various. Banned anywhere in a subject: emoji, ticket IDs, [tags], trailing ..
3. Blank line, then body wrapped at 72 (§1)
No exceptions — rebase, format-patch, and git log all break without the blank line, and the default pager does not wrap.
4. Body says what and why, never how (§2)
The diff already says how. The body says: the problem that existed, why this solution, what you rejected, what it costs.
5. Apply the language contract (§3–4)
Every sentence, in commits and PR bodies both:
| Rule | Source | Test |
|---|---|---|
| Active voice, present tense | Who does it? Name them. | |
| ≤20 words per instruction, ≤25 per statement | STE | Count it. |
| One instruction per sentence | STE | Two verbs → two sentences. |
| One word, one meaning, everywhere | STE | Same thing, same noun. No synonyms. |
Keep articles (the, a) |
STE | Telegraph style is a defect. |
| ≤3 words per noun cluster | STE | user account creation failure → rewrite. |
Second person you, never we |
we refactored → this change refactors. |
|
| Conditions before instructions | If X, do Y — never Do Y if X. |
|
| Sentence case headings, serial commas | — | |
| Code font for identifiers, paths, flags | — | |
ISO dates (2026-08-12) |
Never 08/12/26. |
Banned words: simply, just, easily, obviously, please, leverage, utilize, in order to, various improvements, under the hood, out of the box, low-hanging fruit. Banned opener: This PR ... — do not pre-announce.
6. Fill the PR body template (§5)
## What changed
<1–3 sentences. Active voice, present tense.>
## Why
<The problem. The reason for this solution. What you rejected.>
## How to verify
1. <One action per step.>
2. <Expected result, stated concretely.>
## Risk
<What breaks if this is wrong. How to roll it back.>
Closes ABC-123
Drop a section only when it is genuinely empty, and say so: Risk: none — docs only.
7. Gate before you push
bash scripts/pr-lint.sh
Exit non-zero → fix the message. Do not run gh pr create on a failing message.
Non-negotiables
- Never
git commit -mfor a change that needs a body. Use a message file or a heredoc. - The PR title obeys the subject rules exactly — 50 characters, imperative, no period.
- A squash-merge message is a commit message. Same rules.
- Never let a template heading survive with placeholder text under it.
- If you cannot state the why, you do not understand the change yet. Go read the diff again.
04 同仓库更多 Skills
use-garden
Consulting garden, the separately installed guidance command this repository's owner enabled, when an open engineering choice the repository does not settle, made in a change or only recommended, would be informed by published guidance. Use for a choice between approaches, a pattern or pitfall for a technology or concern the work touches, or a unit a repository decision names; not for a question about this repository's own facts or a change whose choices are already settled.
use-garden
Consulting garden, the separately installed guidance command this repository's owner enabled, when an open engineering choice the repository does not settle, made in a change or only recommended, would be informed by published guidance. Use for a choice between approaches, a pattern or pitfall for a technology or concern the work touches, or a unit a repository decision names; not for a question about this repository's own facts or a change whose choices are already settled.
what-to-build
Propose what this product could do next at three altitudes: sharpen a shipped slice, extend one, or open ground the product does not stand on yet. Use for 'what should we build next', 'any ideas for this app', 'what's missing', 'is this done or is there more in it', and quick-win hunts. Not for refactors, which belong to the architecture survey.
wayfinder
Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets in a plan directory's map.md, and resolve them one at a time until the way to the destination is clear.
verify
Prove a change's claims with fresh evidence: restate each item of its acceptance so it can fail, capture a baseline and a treatment with the same command, compare the raw artifacts, and return VERIFIED, NOT VERIFIED or INCONCLUSIVE for each, at the depth the change's mode gives the verify step. Use when the mode reaches verify, or when the owner says "verify this", "prove it works" or "did this fix it".
tdd
Test-first development at any step: discover the repository's own test commands, name the break a test catches, watch it fail for the intended reason, make it pass with the smallest change, and add a new test only where it catches a realistic failure the existing ones would miss. Use when writing or changing a test, building a feature or fixing a bug test-first, or deciding whether a change needs a new test; also on 'red-green-refactor' and integration tests.