people-first-pr-descriptions
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.
- License 许可
- MIT
- 最近更新
- 2026-11-05
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- people-first-pr-descriptions
- description
- 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.
03 SKILL.md 正文
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 changedandWhy 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.
04 同仓库更多 Skills
writing-waterfall-requirements-documents
Write a waterfall requirements document: elicit, structure and review testable, traceable requirements, then baseline the specification before design.
writing-vision-and-values-statements
Write a V2MOM vision a reader can test and a ranked list of values that settles real tradeoffs, so the rest of the document has a clear anchor.
writing-system-prompts-for-claude
Write Claude prompts and CLAUDE.md files that supply exact inputs, scope the task, and define done so the first attempt can be checked.
writing-page-specific-website-copy
Website copywriting by page type: write homepage, landing page, pricing page and feature page copy that fits each page's visitor and single job.
writing-internal-press-releases
How to write an internal press release: the one-page working backwards press release that opens a PR/FAQ document before anything is built.
writing-email-sequences-that-sell
Email sequence copywriting for nurture and sales: give each email one job, write clear subject lines, and close with one specific call to action.