PR Writing
A PR description, commit message, or review comment is read by a human
deciding whether to trust and merge the change. Write for that reader, not
as a record of the work session.
Style rules
- Brief. State the change and the reason. Skip the narrative of how you
got there.
- Info-dense, not verbose. Every sentence carries a fact. Cut sentences
that restate the diff, the title, or each other.
- Don't write what's inferable. A reviewer can read the diff — don't
describe what a line change does if the code already says so. State only
what the diff can't show: intent, a non-obvious constraint, a fact you
verified.
- Simplified Technical English. One claim per sentence. Concrete
subjects, active voice, present tense for current behavior. No hedging
("might", "could potentially", "it seems"), no filler ("simply",
"basically", "just"), no marketing language. Say "X fails when Y" — not
"there might be an issue where X could fail if Y happens."
- Write for a human, not an AI reviewer. No emoji, no "Generated by",
no restating the obvious for machine parsing. Plain prose a teammate
would send in Slack.
Pre-open checklist
- CI must pass before you ask for review. Run the project's checks
locally first — lint, tests, build. If a check is red after pushing, fix
it or say plainly in the PR why it's expected (a known, unrelated
flake), never leave it unexplained.
- One PR, one change. A second unrelated fix noticed along the way is a
separate PR, not scope creep on this one.
- State only what you verified. "Ran
X, confirmed Y" — never "this
should work" or "this probably fixes it." An unverified claim in a test
plan is itself a defect; a reviewer trusts it and later finds it was
false.
- Cite
file:line for claims about existing behavior. An uncited claim
is a hypothesis the reviewer has to re-derive themselves.
- Reference the issue it closes, if any (
Fixes #123), instead of
restating the issue's content.
Shape
- PR title:
<type>(<scope>): <summary>, imperative mood, under ~70
chars.
- PR description: 1-3 bullets — what changed, why. A test plan section
listing what you actually ran, not what should theoretically pass.
- Issue title: plain English a non-technical reader would say out
loud, not a commit-style
<type>(<scope>): <summary>. Name the
outcome, not the mechanism — "Improve how Hedgehog tracks and enforces
a project's architecture", not "feat(core): add pattern field".
- Comments: lead with the concrete finding, then (if needed) the fix
requested. No preamble.
Why/What for issues
An issue proposing a change — a feature, a fix worth explaining, a
roadmap item being picked up — states Why before What:
- Why: the problem, as a short list of plain-language facts. Each
bullet is one observation a reader can verify or disagree with, not a
justification wrapped in caveats. State the problem first, then (if
the fix isn't obvious from the problem) a short "to fix this" list of
intended outcomes.
- What: the change itself — the concrete steps, fields, or sub-issues.
Numbered if sequenced, bulleted if not.
Skip the Why section only when the title already states the problem in
full (a one-line bug report needs no restatement). Never skip What.
Fold deep reasoning under <details>
An issue or PR body written for a human reader stays short. Extended
reasoning — architecture rationale, alternatives considered, prior
decisions, anything aimed at an AI agent picking up the work or a reader
who wants the full trail — goes under a collapsed section, not inline:
<details>
<summary>Full reasoning (for AI agents and anyone who wants the detail)</summary>
...
</details>
Ask first whether that detail needs to exist in the issue at all — a
link to an existing doc or prior discussion is often enough. Only fold
in content that has no better home.
When NOT to apply
- Internal scratch notes, planning docs, or anything not read by another
person — write those however is fastest for you.
- The user asks for a different register explicitly (e.g. a detailed
design-doc-style PR description for an architectural change that needs
the extra context).
1---2name: pr-writing3description: Use whenever writing a PR title/description, a commit message body, a code review comment, or an issue — in Hedgehog's own repo or any consuming project. Triggers on "open a PR", "write the PR description", "comment on this PR", "file an issue". Covers writing style (terse, info-dense, Simplified Technical English), the Why/What shape, folding deep reasoning under `<details>`, and the pre-open checklist (CI status, scope, verified claims only).4metadata:5 source: https://skillmd.com/skills/skyf0xx/pr-writing6---78# PR Writing910A PR description, commit message, or review comment is read by a human11deciding whether to trust and merge the change. Write for that reader, not12as a record of the work session.1314## Style rules1516- **Brief.** State the change and the reason. Skip the narrative of how you17 got there.18- **Info-dense, not verbose.** Every sentence carries a fact. Cut sentences19 that restate the diff, the title, or each other.20- **Don't write what's inferable.** A reviewer can read the diff — don't21 describe what a line change does if the code already says so. State only22 what the diff can't show: intent, a non-obvious constraint, a fact you23 verified.24- **Simplified Technical English.** One claim per sentence. Concrete25 subjects, active voice, present tense for current behavior. No hedging26 ("might", "could potentially", "it seems"), no filler ("simply",27 "basically", "just"), no marketing language. Say "X fails when Y" — not28 "there might be an issue where X could fail if Y happens."29- **Write for a human, not an AI reviewer.** No emoji, no "Generated by",30 no restating the obvious for machine parsing. Plain prose a teammate31 would send in Slack.3233## Pre-open checklist3435- **CI must pass before you ask for review.** Run the project's checks36 locally first — lint, tests, build. If a check is red after pushing, fix37 it or say plainly in the PR why it's expected (a known, unrelated38 flake), never leave it unexplained.39- **One PR, one change.** A second unrelated fix noticed along the way is a40 separate PR, not scope creep on this one.41- **State only what you verified.** "Ran `X`, confirmed `Y`" — never "this42 should work" or "this probably fixes it." An unverified claim in a test43 plan is itself a defect; a reviewer trusts it and later finds it was44 false.45- **Cite `file:line` for claims about existing behavior.** An uncited claim46 is a hypothesis the reviewer has to re-derive themselves.47- **Reference the issue it closes**, if any (`Fixes #123`), instead of48 restating the issue's content.4950## Shape5152- **PR title**: `<type>(<scope>): <summary>`, imperative mood, under ~7053 chars.54- **PR description**: 1-3 bullets — what changed, why. A test plan section55 listing what you actually ran, not what should theoretically pass.56- **Issue title**: plain English a non-technical reader would say out57 loud, not a commit-style `<type>(<scope>): <summary>`. Name the58 outcome, not the mechanism — "Improve how Hedgehog tracks and enforces59 a project's architecture", not "feat(core): add pattern field".60- **Comments**: lead with the concrete finding, then (if needed) the fix61 requested. No preamble.6263## Why/What for issues6465An issue proposing a change — a feature, a fix worth explaining, a66roadmap item being picked up — states **Why** before **What**:6768- **Why**: the problem, as a short list of plain-language facts. Each69 bullet is one observation a reader can verify or disagree with, not a70 justification wrapped in caveats. State the problem first, then (if71 the fix isn't obvious from the problem) a short "to fix this" list of72 intended outcomes.73- **What**: the change itself — the concrete steps, fields, or sub-issues.74 Numbered if sequenced, bulleted if not.7576Skip the Why section only when the title already states the problem in77full (a one-line bug report needs no restatement). Never skip What.7879## Fold deep reasoning under `<details>`8081An issue or PR body written for a human reader stays short. Extended82reasoning — architecture rationale, alternatives considered, prior83decisions, anything aimed at an AI agent picking up the work or a reader84who wants the full trail — goes under a collapsed section, not inline:8586```markdown87<details>88<summary>Full reasoning (for AI agents and anyone who wants the detail)</summary>8990...91</details>92```9394Ask first whether that detail needs to exist in the issue at all — a95link to an existing doc or prior discussion is often enough. Only fold96in content that has no better home.9798## When NOT to apply99100- Internal scratch notes, planning docs, or anything not read by another101 person — write those however is fastest for you.102- The user asks for a different register explicitly (e.g. a detailed103 design-doc-style PR description for an architectural change that needs104 the extra context).