pr-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR & Issue

PR 与 Issue

Write the title and body Vim-style —

area: summary

, then labelled sections in template order.

Three words carry this skill. Symptom: every body opens with the thing a human noticed. Mechanism: the next paragraph names the exact code that misbehaves. Receipts: any output shown was really produced, never output that would plausibly have been produced — and a change to rendered output shows that output.

A PR is read once, in a hurry, by someone deciding whether to approve. An issue is read once, weeks later, by someone deciding whether to work on it — and again by whoever picks it up. Every sentence earns its place by moving that decision along.

以 Vim 风格编写标题和正文——采用

area: summary

，然后按照模板顺序填写带标签的各个部分。

三个词贯穿整个 skill：症状：每个正文都从人能够注意到的问题开始。机制：下一段指出行为异常的确切代码。证据：展示过的任何输出都确实由实际运行产生，绝不是看似可能产生的输出；而对渲染结果的修改必须展示该输出。

PR 通常只会被阅读一次，而且是在有人急于判断是否批准时阅读。Issue 可能几周后才会被阅读一次，阅读者要判断是否着手处理；之后接手的人还会再读一遍。每一个句子都必须发挥推进该决策的作用。

Which artifact

选择哪种产出物

A PR argues that a change should land. An issue argues that a change is needed. The title, the

Problem

section, and the style rules are shared; everything after them diverges.

	Pull request	Issue / ticket
Title mood	imperative — the change	indicative — the defect or the gap
Header block	none	`Labels:` / `Relates to:`
Body	Problem, Solution, Security Impact, Testing	Problem, Reproduction, Expected vs actual, Proposed solution
Evidence	commands you ran, output you copied	steps that reproduce, revision the line numbers pin to
Tone of the fix	decided	proposed, with the open questions named

Read one reference, now, before drafting. This file carries only what both artifacts share.

Writing a pull request →
```
pr.md
```
Writing an issue, ticket, or bug report →
```
issue.md
```

PR 论证的是某项变更应当合入；Issue 论证的是某项变更是必要的。标题、

Problem

部分和风格规则是二者共用的；从那之后，所有内容都各有不同。

	Pull request	Issue / ticket
标题语气	祈使式——描述变更	陈述式——描述缺陷或缺口
头部信息块	无	`Labels:` / `Relates to:`
正文	Problem, Solution, Security Impact, Testing	Problem, Reproduction, Expected vs actual, Proposed solution
证据	你运行过的命令、复制过来的输出	可复现的步骤、用于锁定具体行号的 revision
修复方案的语气	已确定	提议性，并明确列出尚未解决的问题

开始起草前，先阅读一份参考文档。 本文件只包含两类产出物共有的内容。

编写 pull request →
```
pr.md
```
编写 issue、ticket 或 bug report →
```
issue.md
```

Shared steps

共用步骤

Gather the ground truth in full. For a PR that is the diff (
```
git diff <base>...HEAD
```
), read until every changed file is accounted for, not until the shape is clear. For an issue it is the code path that fails, read until you can name the line that decides the wrong outcome.
One artifact, one problem. A diff spanning unrelated areas splits into two PRs; a report bundling two defects splits into two issues.
Draft the title from the area of the largest coherent change.
Follow the reference for the artifact — it owns the middle of the body.
Cut every clause that would not change what the reader does. Done when the body is under 400 words.

Open it with a heredoc, so the markdown survives the shell:

bash

gh pr create --title "statusline: show commit SHA on detached HEAD" --body "$(cat <<'EOF'
**Problem:**
...
EOF
)"

Done when all five hold, plus that artifact's own checks:

The title is
```
area: summary
```
, lowercase after the colon, no period, under 72 characters.
The body has that artifact's sections, in template order, and nothing else. No
```
Changes
```
, no
```
Checklist
```
, no
```
Related issues
```
prose, no emoji, and no
```
Generated with
```
footer beyond what the harness requires.
The body is under 400 words, and no section runs past two paragraphs of prose. Going over needs a reason the reader would agree with.
Every command shown was executed this session, and its pasted output was copied from a real result.
A change to rendered output is shown where the template puts it — or, where nothing could be published, the body never mentions media.

Never claim evidence that does not exist. This is the one hard guardrail in this skill: invented output is worse than no output, because the reader trusts it. When a command was not run or a failure was not reproduced, the receipt is a plain statement of that fact and of what was done instead.

Not tested — no local Stripe webhook fixture for this event type. Verified by inspection against the
charge.refunded
payload in the Stripe docs.

A visual change carries a visual receipt. Rendered output that changed — a component, a page, terminal output, a chart, a PDF — appears in the body; motion or a multi-step flow wants a GIF. A new feature has an after and no before. A change to a mechanism with no pixels to show — what re-renders, how data flows, a schema — carries a motion schematic instead: read

motion.md

. Publish it anywhere a reader loads without credentials:

gh --attach

uploads to GitHub, and a file committed to a branch or a release asset renders inline from

raw.githubusercontent.com

, in a repo you own.

Where nothing can be published, the media and every mention of it are absent — no placeholder, no broken link, no note. Unlike

Testing

, this gap goes unnamed: a stranger learns nothing from it.

完整收集事实依据。对于 PR，事实依据是 diff（
```
git diff <base>...HEAD
```
）；要一直阅读，直到每个变更文件都被纳入考虑，而不是只看懂变更的大致形态。对于 Issue，事实依据是失败的代码路径；要一直阅读，直到你能指出决定错误结果的代码行。
一个产出物只处理一个问题。diff 如果横跨互不相关的领域，应拆成两个 PR；报告如果捆绑了两个缺陷，应拆成两个 Issue。
根据范围最大且内聚的变更所属领域起草标题。
按照产出物的参考文档执行——正文中间部分由该文档决定。
删去所有不会改变读者行动的从句。正文少于 400 个单词时即可完成。

通过 heredoc 提交内容，让 markdown 完整保留，不被 shell 改写：

bash

gh pr create --title "statusline: show commit SHA on detached HEAD" --body "$(cat <<'EOF'
**Problem:**
...
EOF
)"

当以下五项全部满足，并且通过该产出物自身的检查时，即可完成：

标题为
```
area: summary
```
，冒号后小写，无句号，少于 72 个字符。
正文包含该产出物规定的各个部分，顺序与模板一致，且不包含其他内容。不要写
```
Changes
```
，不要写
```
Checklist
```
，不要写
```
Related issues
```
说明文字，不要使用 emoji，也不要添加 harness 要求之外的
```
Generated with
```
页脚。
正文少于 400 个单词，且任何部分都不得超过两段文字。超出时需要给出一个读者会认可的理由。
展示的每条命令都已在本次会话中执行，粘贴的输出也均复制自真实结果。
对渲染输出的修改，应在模板指定的位置展示；或者，如果无法发布任何媒体，正文中就完全不要提及媒体。

绝不可声称不存在的证据。 这是本 skill 唯一不可违背的硬性护栏：虚构的输出比没有输出更糟，因为读者会相信它。如果某条命令未运行，或某个失败未复现，就应如实说明，并说明改用了什么方式来完成验证。

未测试——本地没有适用于此事件类型的 Stripe webhook fixture。已通过对照 Stripe 文档中的
charge.refunded
payload 进行检查验证。

可视化变更必须带有可视化证据。 凡是渲染输出发生变化——无论是组件、页面、终端输出、图表还是 PDF——都应出现在正文中；涉及动效或多步骤流程时，则需要 GIF。新功能只展示变更后的效果，不展示变更前。某些机制变更没有像素可供展示——例如什么会重新渲染、数据如何流动、schema 发生了什么——这类变更应改为附上动态示意图：阅读

motion.md

。应将图示发布到读者无需凭据即可加载的位置：

gh --attach

可上传到 GitHub，提交到分支的文件或 release asset 则可通过

raw.githubusercontent.com

内联渲染，前提是你拥有相应仓库。

如果无法发布媒体，就完全省略媒体及其所有提及——不要放占位符、失效链接或说明文字。与

Testing

不同，这一空缺无需命名：陌生读者不会从中获得任何信息。

Title

标题

area

is the subsystem touched — a component, module, file stem, or feature. Lowercase, one word where possible.

A PR summary is imperative and describes the change:

statusline: show commit SHA on detached HEAD
auth: reject expired refresh tokens on rotation
db: index orders on (artist_id, created_at)

An issue summary is indicative and describes the defect, specific enough to be recognised again by someone who hit it:

auth: scope-insufficient 403 collapses into connection_rejected
statusline: branch segment is blank on detached HEAD

Compare the same artifacts titled badly:

Fix statusline bug

names the symptom without the mechanism,

Update auth.ts

names the file,

fixes #12

names nothing.

area

表示被触及的子系统——可以是组件、模块、文件名词干或功能。尽量使用一个词，并采用小写形式。

PR 的摘要应使用祈使语气，并描述所做的变更：

statusline: show commit SHA on detached HEAD
auth: reject expired refresh tokens on rotation
db: index orders on (artist_id, created_at)

Issue 的摘要应使用陈述语气并描述缺陷，具体程度要足以让曾经遇到该问题的人再次认出它：

auth: scope-insufficient 403 collapses into connection_rejected
statusline: branch segment is blank on detached HEAD

对比同一批产出物的糟糕标题：

Fix statusline bug

只指出了症状而没有说明机制，

Update auth.ts

指出了文件，

fixes #12

则什么都没有说明。

Problem

Both artifacts open with this section, and it is written the same way in each.

Symptom first, mechanism second. The opening sentence says what a user or operator sees; only then does the paragraph descend into the code. Name the command, flag, function, or expression that misbehaves, and say what it does instead of what it should do. A reader who has never opened the code should understand the failure without opening the diff.

The status line shows a blank name whenever the repo is on a detached HEAD.
git branch --show-current
prints nothing and exits 0 in that state, so the
|| echo "detached"
fallback — which only runs on a non-zero exit — never fires and
$branch
stays empty.

A reader who stops after that first sentence still learned the bug. Opening instead at

git branch --show-current

makes them assemble the consequence themselves.

For a feature, the symptom is what a user cannot do today, and the mechanism is the gap the feature closes.

Each reference says how far its

Problem

runs past this shape: a PR's is short and cedes detail to the diff, an issue's carries the code excerpts.

PR 与 Issue 都以这一部分开头，而且二者的写法相同。

先写症状，再写机制。开头句说明用户或运维人员看到什么；只有之后，段落才深入代码。指出行为异常的 command、flag、function 或 expression，并说明它实际做了什么，而不是它本应做什么。即使读者从未打开过代码，也应当在不查看 diff 的情况下理解故障。

当仓库处于 detached HEAD 状态时，状态栏会显示空白名称。在这种状态下，
git branch --show-current
不输出任何内容并以 0 退出，因此
|| echo "detached"
fallback（只在非零退出时运行）永远不会触发，
$branch
会一直保持为空。

只读完第一句的读者也已经了解了 bug。若从

git branch --show-current

开始写，则需要读者自行推断后果。

对于功能，症状是用户目前无法完成什么，而机制是该功能所填补的缺口。

每份参考文档都会说明其

Problem

部分应在上述结构之外延伸多远：PR 的这一部分应简短，把细节交给 diff；Issue 的这一部分则应包含代码摘录。

Style

风格

These rules are this skill applied to PRs and issues; the general form is the

agent-to-human

skill, which is their source of truth. This section stands on its own, so

pr-issue

works whether or not that skill is installed.

Omit needless words. Everything below is that rule, made mechanical.

One sentence, one idea. A sentence carrying three clauses joined by semicolons and em-dashes is three sentences wearing a trenchcoat. Split it. If a sentence runs past about thirty words, it has more than one idea in it.

Backtick what a reader would grep for. Identifiers, commands, paths, flags, literal values — but only on the mention that matters, not on every recurrence, and never so densely that the prose becomes a symbol table. Three backticked identifiers before the first verb means the sentence started in the wrong place.

Prose, with bullets earned. Prose is the default and carries any argument. Bullets are permitted for three or more genuinely parallel items, one line each — a list of removed call sites, say. The numbered steps in an issue's

Reproduction

are the one list a template asks for. A bulleted list that is really a changelog of the diff is a PR that wants splitting; a bulleted list that is really a paragraph with dashes in front of it is a paragraph.

Present tense, about the change. The sentences describe behaviour, not authorship.

Name a thing once. Having written

DeliveryTbd{arrangedBy:'partner'}

, write "the partner case" thereafter. Full ceremonial restatement of a symbol on each mention is how a body doubles in length while saying nothing new.

这些规则是本 skill 应用于 PR 和 Issue 后的具体形式；其通用版本是

agent-to-human

skill，后者是前者的权威依据。本节可独立使用，因此无论是否安装该 skill，

pr-issue

都能正常工作。

删去不必要的词语。 以下内容都是将这条规则机械化后的具体要求。

一个句子只表达一个想法。 如果一个句子用分号和破折号连接了三个分句，那就像三个句子穿着同一件风衣。把它拆开。如果一个句子超过大约三十个词，它承载的想法就不止一个。

读者会搜索的内容要用反引号标出。 标识符、命令、路径、flag 和字面值都应如此处理——但只标注真正关键的那次提及，而不是每次重复都标注，也不要密集到让正文变成一张符号表。如果第一个动词之前就出现了三个用反引号标出的标识符，说明句子的起点选错了。

以段落为主，只在确有必要时使用项目符号。 默认使用段落来承载论证。只有存在三个或更多真正平行的项目时，才可以使用项目符号，每个项目占一行——例如，列出被移除的调用点。Issue 的

Reproduction

中的编号步骤，是模板唯一明确要求的列表。如果一个项目符号列表实际上只是 diff 的变更日志，就说明这个 PR 应该拆分；如果它实际上只是一个加了破折号的段落，那它就还是段落。

使用现在时，描述变更本身。 句子应描述行为，而不是作者身份或撰写过程。

同一事物只完整命名一次。 写出

DeliveryTbd{arrangedBy:'partner'}

后，此后应写作“partner 场景”。每次提及都完整、郑重地复述一个符号，只会让正文篇幅翻倍，却没有任何新信息。