TrackerJo/pr-description

Plain-English PR descriptions

Write for a maintainer who needs to understand the change quickly. A good description answers three questions in its first screen:

1. What was wrong or missing?
2. Why did it need to change?
3. What is true now?

Read the actual diff, current PR body, commits, tests, and PR state before writing. The old body and commit titles describe intent, not proof. Do not claim manual testing, deployment, or production behavior unless the author confirmed it.

Required opening: What Changed and Why

Every PR description must begin with a contributor-owned ## What Changed and Why section, immediately after the monitor-owned ## Status when Status is present. This is required, not optional formatting.

Use three short labeled paragraphs, in this order:

• Issue: the actual user or operator failure, or missing behavior.
• Why this change was necessary: why that failure mattered and why the chosen boundary is needed.
• New status quo: the concrete behavior after this PR.

Keep each labeled paragraph to one or two sentences. A maintainer must be able to answer “what happened in this PR?” from this section alone. Do not begin with implementation mechanics, a deleted design, or rewrite history.

When reviewing an inadequate opening, give a concrete replacement or a concise three-paragraph outline tailored to the actual diff. Do not merely say it is verbose, unclear, or needs a better explanation.

Use this shape for most PRs:

## What Changed and Why

**Issue:** [The actual user or operator failure, or missing behavior.]

**Why this change was necessary:** [Why it mattered and why this boundary is needed.]

**New status quo:** [The concrete behavior after this PR.]

## After merge

[Only the real operator or reviewer actions that remain. Omit this section if
there are none.]

## Verification

[State only confirmed manual checks and genuinely post-merge checks.]

Start with the substance. Do not restate the PR title, add an introduction, or write a summary that repeats the next paragraph.

What to keep

• One clear end state per material change. A reader scanning the first sentence of each paragraph or bullet should understand what changes after merge.
• Real decisions. Name a rejected alternative only when it affects product behavior, risk, or a meaningful cost. Say what was chosen and why in one sentence. Do not manufacture a "Key decision" label.
• Operational facts. Mention migrations, backfills, scheduled jobs, integrations, secrets, deploy order, and failure behavior when a reviewer or operator needs to act on them.
• Honest verification. Separate what someone actually checked by hand from work that truly must wait until after merge. Do not list lint, build, CI, or test commands. Tests can be mentioned in plain English when they cover a meaningful behavior.
• Open calls. Include only unresolved decisions the reviewer must make. Put the question first, then a recommendation and its cost. Omit the section when there is nothing to decide.

Required evidence for changed systems

A description is incomplete when it changes a user-facing system, a material operator workflow, or its configuration and does not show the reviewer how to inspect it.

• Screenshots or short videos: Put visual evidence in its own ## Visual evidence section. Include screenshots for a changed screen or short videos for a changed interaction or multi-step flow. Embed the media or link to a stable PR attachment. Captions must say what changed and what the reviewer is looking at. Do not substitute a screenshot of source code, a test report, or an unchanged screen. Put required phone evidence before laptop evidence for public and event surfaces, and identify each viewport and tested state. Follow the visual-proof skill for capture, upload, and latest-commit verification. Omit this section only when the PR has no visual or interactive surface.
• Configuration, environment, and migrations: Put only real added, removed, renamed, or behavior-changing environment variables, secrets, dashboard settings, and database migrations in ## Configuration. Lead with the one action an operator needs to take; keep ordinary external setup to one short sentence, for example: Set up a monitor at <URL> and point it to https://buildpurdue.org/api/health. No internal changes. Do not pad the section with polling details, rationale already explained elsewhere, or links to duplicated runbooks. For each real migration, name its committed supabase/migrations/ path, summarize the schema/data/policy change, state compatibility or backfill requirements, and give the confirmed npm run db:verify replay result. Never print secret values. Omit the section when there are no configuration or migration changes.
• Changed flows: Use Mermaid flowcharts for material flows that change. A flow is material when it has multiple steps, branches, retries, a handoff between systems, or a failure path. Show the changed path and its important failure behavior, using plain labels that a reviewer can read. Add one diagram for each distinct changed flow. Do not use a diagram for a one-step rename or a trivial local calculation.

These are separate from the main explanation. The explanation says why the change exists; evidence, configuration, and diagrams let a reviewer inspect it.

Keep it readable

• Default to 250 words or fewer. A description can be longer when the operator needs a short checklist, but every sentence must earn its place.
• Use short paragraphs. Use bullets only for a real list, such as remaining setup steps. Do not turn every sentence into a labeled bullet.
• Put the issue, why, and new status quo in normal English. Say who does what.
• Avoid raw code, queries, config fragments, status codes as nouns, jargon, metaphors, hype, and em dashes.
• Do not explain every mechanism. Keep the behavior the reviewer needs to know.
• Do not repeat a fact in a later section. If a sentence can disappear without losing information, remove it.

Status is monitor-owned

Contributors own every part of the PR description except ## Status. Do not add, remove, or edit that section yourself. The BuildPurdue PR monitor owns it and keeps it aligned with the current review state.

When it changes Status, the monitor also posts a matching Status update: PR comment. It uses one plain-English sentence: a concrete pre-merge next action when work remains, or No more remaining work. when nothing remains. Status never belongs in a contributor-facing description-review comment.

Do not use Status for optional future ideas, historical notes, post-merge-only work, or work tracked separately that does not block this PR.

When more structure is justified

Add a focused section only when it carries information that does not fit in the main explanation:

• Database / migrations: what must run, whether existing data remains compatible, and whether a backfill is needed.
• Operational behavior: what runs, when it runs, how failures are visible, and what an operator must configure.
• Verification: confirmed manual checks and truly post-merge checks.
• Open calls: unresolved product or risk choices.

A small bug fix can simply use:

## Root cause

## Fix

## Verification

Before publishing

1. Check that every claim traces to the current diff, tests, PR state, or a command you ran.
2. Read the first screen by itself. It must clearly say the issue, why the change was necessary, and the new status quo.
3. Remove historical narration, changelog-style implementation logs, repeated explanations, and unrelated work.
4. Confirm any migration, deployment, secret, dashboard, or post-merge action is explicit and actionable.
5. Re-read it aloud. It should sound like a person explaining the change to a teammate, not an audit report.
6. On every push, compare the body with the new diff and update it when the behavior, remaining setup, or verification status changed.

Source

Edit this copy under .agents/skills/. The pre-commit hook mirrors it into .claude/skills/pr-description/; do not edit the mirror directly.