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