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. Both readers are cold: switching in from other work, often not the author, often new to this corner of the codebase. Every sentence earns its place by moving that decision along.

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.

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
• Writing a stack of pull requests → pr.md, then stack.md

The repo's own template

A repo's own template outranks this skill. This skill's templates are the default for repos with none.

Find it before drafting:

find . -maxdepth 3 -path ./node_modules -prune -o \( -iname '*pull_request_template*' -o -iname '*issue_template*' -o -iname 'contributing.md' \) -print

When that finds nothing, GitHub falls back to the owner's public .github repo: look in its root, .github/, and docs/ with gh api repos/<owner>/.github/contents/<dir>.

When a template exists, keep its headings, order, checkboxes, and title convention. Each rule it or CONTRIBUTING.md sets replaces the matching rule in this skill, including the checks under Shared steps. The style rules and the guardrail still apply inside its sections, and a checkbox is ticked only for work done. Then place this skill's content:

• A matching section takes it: Problem under their "Motivation", Evidence under their "How was this tested?".
• A near home absorbs it with no new heading: in a Problem / Solution template, the evidence closes their Solution.
• Content with no home gets this skill's section, after all of theirs: a template with no place for risks ends with *Risks:*.

Shared steps

1. Find the repo's own template, above.
2. Gather the ground truth in full. For a PR that is the diff (git diff --stat <base>...HEAD, then git diff <base>...HEAD -- <file> per file), 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.
3. One artifact, one problem. A diff spanning unrelated areas splits into two PRs; a report bundling two defects splits into two issues.
4. Draft the title from the area of the largest coherent change.
5. Follow the reference for the artifact — it owns the middle of the body.
6. Cut every clause that would not change what the reader does. Done when the body has under 400 words of prose.

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

   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 has under 400 words of prose, and no section runs past two paragraphs. Tables, images, diagrams, and code blocks do not count. Going over needs a reason the reader would agree with.
• Every command, number, and result shown came from a run this session.
• 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 video or GIF walkthrough. A new feature has an after and no before. A change to a mechanism — what re-renders, how data flows — shows a real capture where one exists (react-scan outlines, a profiler trace, a table of numbers).

A change in shape carries an illustration, so a cold reader sees the structure before reading about it. A static shape — components, call order, who owns what — is a mermaid diagram, before and after side by side. Motion that no real capture shows — what re-runs, what flows where over time — is a motion schematic: 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 a test not run, this gap goes unnamed: a stranger learns nothing from it.

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.

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.

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.

Tables for comparisons. Results that compare — main against branch, before against after, option against option — go in a table, with a Δ column for numbers. A list of results goes in bullets. A code block holds only text whose exact characters are the point: a changed CLI output, an error message, a command to copy.

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.