People-first pull-request descriptions
Write PR descriptions for readers who need to understand the change before they need to inspect the code: product, support, QA, designers, leadership, and reviewers outside the subsystem.
Required companion workflow
Before opening a pull request or marking one ready for review, complete Hamster Pre-PR Review. It makes this people-first description mandatory and verifies the branch, diff, blockers, and quality gates.
Ground the description first
Before writing or updating a PR body:
- Read the current PR body, diff, review feedback, and validation evidence.
- Identify the user-visible or operational problem in one plain sentence.
- Distinguish confirmed behavior from pending validation, limits, and follow-up work.
- Preserve an existing Hamster brief link/path and any facts that remain accurate.
Do not claim a test, CI run, deployment, live canary, migration, or user outcome unless it was actually observed.
Default structure
Use this order unless the PR is truly trivial:
## What changed
One or two plain-language sentences about the capability or behavior.
## Why it matters
Describe the prior user, customer, operator, or maintainer problem. Use a concrete failure mode when useful.
## How it works
Explain the approach at a conceptual level. Prefer short bullets for steps, guarantees, and safeguards.
## User impact
State what a person can now do, what stays the same, and what they will see when a limit or error occurs.
## Scope, limits, and follow-up
State deliberate exclusions, unsupported providers, preview limits, rollout dependencies, or remaining live validation. Do not bury these caveats.
## Validation
List only executed checks and their outcome.
## Technical details
Optional. Include only details that help a reviewer navigate a non-obvious implementation.
## Brief
Preserve the exact linked brief when one exists.
Omit empty sections. For a small bug fix, combine How it works and User impact; do not force a long template onto a two-line change.
Writing rules
- Lead with behavior and consequences, not filenames, classes, APIs, or implementation verbs.
- Translate jargon on first use: for example, say “reads every page of Jira results” before “pagination.”
- Explain safeguards as outcomes: “does not report a final count when the read is incomplete,” not only “fails closed.”
- Be specific about the before/after flow when it clarifies the value.
- Put filenames, internal tool names, commits, architecture, schemas, and test mechanics after the people-first explanation.
- Use short paragraphs, ordinary words, active voice, and scannable bullets.
- Do not oversell. Name material limitations plainly.
- Never replace a technical truth with a vague product claim.
Update workflow
When the user asks to update an existing PR:
- Preserve correct historical context and the brief.
- Re-check every validation claim against the current HEAD. Rerun a relevant check when the change could affect it; otherwise label the result as predating the latest commit.
- Replace stale implementation-first prose with the people-first structure.
- Keep user-impact claims proportional to what the current branch actually changes.
- Verify the published body after updating it.
Quality check
Before publishing, ask:
- Can a non-engineer explain the problem and outcome after reading only
What changed and Why it matters?
- Can a reviewer identify the important safety behavior without reading code?
- Are limits and pending validation explicit?
- Are technical details present only after the human explanation?
If any answer is no, revise the description before publishing.
1---2name: people-first-pr-descriptions3description: "Write and update pull-request titles and descriptions for technical work. Use whenever creating, revising, or reviewing a PR body, release-style PR summary, or reviewer-facing change explanation—even if the user only says “open a PR,” “update the PR,” “make this understandable,” or provides technical notes. Put people, user outcomes, and why first; move implementation detail and validation after the plain-language explanation."4metadata:5 source: https://skillmd.com/skills/gethamster/people-first-pr-descriptions6---78# People-first pull-request descriptions910Write PR descriptions for readers who need to understand the change before they need to inspect the code: product, support, QA, designers, leadership, and reviewers outside the subsystem.1112## Required companion workflow1314Before opening a pull request or marking one ready for review, complete [Hamster Pre-PR Review](../hamster-pre-pr-review/SKILL.md). It makes this people-first description mandatory and verifies the branch, diff, blockers, and quality gates.1516## Ground the description first1718Before writing or updating a PR body:19201. Read the current PR body, diff, review feedback, and validation evidence.212. Identify the user-visible or operational problem in one plain sentence.223. Distinguish confirmed behavior from pending validation, limits, and follow-up work.234. Preserve an existing Hamster brief link/path and any facts that remain accurate.2425Do not claim a test, CI run, deployment, live canary, migration, or user outcome unless it was actually observed.2627## Default structure2829Use this order unless the PR is truly trivial:3031```markdown32## What changed33One or two plain-language sentences about the capability or behavior.3435## Why it matters36Describe the prior user, customer, operator, or maintainer problem. Use a concrete failure mode when useful.3738## How it works39Explain the approach at a conceptual level. Prefer short bullets for steps, guarantees, and safeguards.4041## User impact42State what a person can now do, what stays the same, and what they will see when a limit or error occurs.4344## Scope, limits, and follow-up45State deliberate exclusions, unsupported providers, preview limits, rollout dependencies, or remaining live validation. Do not bury these caveats.4647## Validation48List only executed checks and their outcome.4950## Technical details51Optional. Include only details that help a reviewer navigate a non-obvious implementation.5253## Brief54Preserve the exact linked brief when one exists.55```5657Omit empty sections. For a small bug fix, combine `How it works` and `User impact`; do not force a long template onto a two-line change.5859## Writing rules6061- Lead with behavior and consequences, not filenames, classes, APIs, or implementation verbs.62- Translate jargon on first use: for example, say “reads every page of Jira results” before “pagination.”63- Explain safeguards as outcomes: “does not report a final count when the read is incomplete,” not only “fails closed.”64- Be specific about the before/after flow when it clarifies the value.65- Put filenames, internal tool names, commits, architecture, schemas, and test mechanics after the people-first explanation.66- Use short paragraphs, ordinary words, active voice, and scannable bullets.67- Do not oversell. Name material limitations plainly.68- Never replace a technical truth with a vague product claim.6970## Update workflow7172When the user asks to update an existing PR:73741. Preserve correct historical context and the brief.752. Re-check every validation claim against the current HEAD. Rerun a relevant check when the change could affect it; otherwise label the result as predating the latest commit.763. Replace stale implementation-first prose with the people-first structure.774. Keep user-impact claims proportional to what the current branch actually changes.785. Verify the published body after updating it.7980## Quality check8182Before publishing, ask:8384- Can a non-engineer explain the problem and outcome after reading only `What changed` and `Why it matters`?85- Can a reviewer identify the important safety behavior without reading code?86- Are limits and pending validation explicit?87- Are technical details present only after the human explanation?8889If any answer is no, revise the description before publishing.