pr-writing git:20260827.2afaea6A

Immutable. This exact content is served forever at /api/v1/blob/b1a371d98a135dba.

---
name: pr-writing
description: 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) and the pre-open checklist (CI status, scope, verified claims only).
---

# 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

- **Title**: `<type>(<scope>): <summary>`, imperative mood, under ~70
  chars.
- **Description**: 1-3 bullets — what changed, why. A test plan section
  listing what you actually ran, not what should theoretically pass.
- **Comments**: lead with the concrete finding, then (if needed) the fix
  requested. No preamble.

## 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).