Pull Request Writing
Write the PR for a reviewer who has not read the agent conversation. The title and body must carry the whole story: what behavior changes, why, and what evidence backs it.
The recipe
- Title names the concrete behavior and component. Follow this repository's title convention (check CI: conventional-commit title, allowed type, scope rules). Name what changes and where: the behavior plus the component or area. Leave out worker IDs, hashes, acceptance labels, vague verbs ("fix", "update"), and praise.
- Lead the body with problem then behavior. First paragraph: the trigger or failure in plain words. Second: what now happens instead. Add one concrete before/after or trigger example when the change is hard to picture without it. If the repository ships a PR template, fill its sections rather than replacing them; fit the recipe into the template's shape, and keep any required checklist honest rather than ticking it by default.
- Describe the implementation briefly, scaled to the change. A small change gets one or two sentences plus rationale. A larger change gets one short paragraph per part: what changed, what it connects to, and why this shape was chosen.
- State the validation honestly. Name the checks actually run (build, tests, linters, repo-specific scanners), their scope, and their outcome. Name material limits, risks, and dependencies too. Keep delivered source separate from deployed proof: a merged change is not the same as a verified running system.
- Keep links and receipts compact. Put issue and spec links plus required review evidence in one short validation section. Link to operational output (logs, run pages, dashboards) instead of pasting it inline.
- Rewrite the title and body when the scope changes. A title that fit the first diff but not the final one misleads every later reader.
- Describe the entire final diff, not the last fix. Review the whole PR against its base including every inherited commit. A correction-only diff is not the PR scope: the title and body must name all material final changes, the hosted validation actually run on the final head, and remaining limits — never only the last one-line fix. A narrower follow-up description that omits inherited scope contradicts this rule; keep every inherited change in scope.
For a stacked PR, compare against its immediate parent's branch. Describe
that complete incremental diff and link the prerequisite and stack; do not
present lower layers as new changes in every child. Separately name
cumulative integration checks, their tested heads/bases, and the intended
merge prefix. Refresh the description and evidence after restacking.
- Keep lasting norms in the canonical spec package. Requirements, behavior, architecture decisions, and normative tool or quality rationale belong in the existing spec structure (spec, plan, contracts, tasks), updated in place. Do not publish standalone rationale reports, selection notes, parallel design documents, or status histories beside it. This is not authority for blanket deletion: preserve legitimate user, API, and reference docs. Before publication, verify each new normative document belongs to the canonical structure and its links resolve. Attempt details, run pages, and review receipts stay linked from the PR, not duplicated into lasting docs. Use generic examples only; keep private project names, paths, and receipts out of public prose.
Mechanics
- Write readable Markdown with real newlines. Build API calls with structured arguments or a body file (
gh --body-file); never interpolate free text into a shell string.
- After saving, read back the rendered title and body and confirm they show what was intended.
- Review the description alongside the code before merge, the same as the diff itself.
Short example
Title: fix(auth): reject expired session tokens at the API boundary
Body:
Expired sessions returned a generic 500 from deep in the request handler.
They now fail fast with 401 at the API boundary, so clients refresh the
session instead of retrying a doomed request.
Changed `session.py` to validate expiry before dispatch; expiry checks live
in one place so future handlers inherit the behavior.
## Validation
- `pytest tests/test_session.py -q`: 24 passed.
- `ruff check src/`: clean.
- Limit: covers API sessions only; web-cookie expiry is unchanged and tracked
in #412.
Complex example
Title: feat(sync): retry failed uploads with backoff and keep local order
Body:
Uploads failed permanently on the first transient network error, and retries
— when added by hand — reordered the local queue, so users saw items arrive
out of order after a flaky connection.
Uploads now retry up to 5 times with exponential backoff, and the queue keeps
its original order across retries. A retry that exhausts its budget surfaces
as a failed item with its error attached instead of blocking the queue.
The retry loop lives in the upload worker; ordering is preserved by holding
each item's slot until it resolves. Backoff caps the extra load; the
failed-item state keeps one bad upload from stalling the rest.
## Validation
- `pytest tests/test_upload_retry.py tests/test_queue_order.py -q`: 61 passed.
- Load check `scripts/replay_flaky.py --seed 7`: order held across 200 injected faults.
- Limit: worst-case delivery delay grows under sustained faults; follow-up in #418.
- Spec: #402.
Pairs with
radical-brevity: make a final meaning-preserving cut after the required context and evidence are in place.
gate-before-push: run the repository's own gates locally first so the described validation is already green.
github-pr-shepherding: classify the PR from GitHub state and drive it to merged or explicitly blocked.
stacked-diff-discipline: keep each layer small, document its parent and native stack, and distinguish incremental review from cumulative validation.
evidence-claim-boundaries: decide what a given piece of evidence actually supports before you claim it in the validation section.
DONE means
A reviewer who never saw the agent conversation can state the behavior change, the rationale, and the validation from the title and body alone; the title satisfies the repository's title check; and the validation section names the checks run, their outcome, and material limits — without pasted operational output or claims beyond what was verified.
Sources: repository title/commit gating practice; conventional-commit release gating; shift-left test evidence.
1---2name: pull-request-writing3description: Use when opening or updating a pull request title and description so a reviewer who has not read the agent conversation can understand and verify the change.4metadata:5 source: https://skillmd.com/skills/selamy-labs/pull-request-writing6---78# Pull Request Writing910Write the PR for a reviewer who has not read the agent conversation. The title and body must carry the whole story: what behavior changes, why, and what evidence backs it.1112## The recipe13141. **Title names the concrete behavior and component.** Follow this repository's title convention (check CI: conventional-commit title, allowed type, scope rules). Name what changes and where: the behavior plus the component or area. Leave out worker IDs, hashes, acceptance labels, vague verbs ("fix", "update"), and praise.152. **Lead the body with problem then behavior.** First paragraph: the trigger or failure in plain words. Second: what now happens instead. Add one concrete before/after or trigger example when the change is hard to picture without it. If the repository ships a PR template, fill its sections rather than replacing them; fit the recipe into the template's shape, and keep any required checklist honest rather than ticking it by default.163. **Describe the implementation briefly, scaled to the change.** A small change gets one or two sentences plus rationale. A larger change gets one short paragraph per part: what changed, what it connects to, and why this shape was chosen.174. **State the validation honestly.** Name the checks actually run (build, tests, linters, repo-specific scanners), their scope, and their outcome. Name material limits, risks, and dependencies too. Keep delivered source separate from deployed proof: a merged change is not the same as a verified running system.185. **Keep links and receipts compact.** Put issue and spec links plus required review evidence in one short validation section. Link to operational output (logs, run pages, dashboards) instead of pasting it inline.196. **Rewrite the title and body when the scope changes.** A title that fit the first diff but not the final one misleads every later reader.207. **Describe the entire final diff, not the last fix.** Review the whole PR against its base including every inherited commit. A correction-only diff is not the PR scope: the title and body must name all material final changes, the hosted validation actually run on the final head, and remaining limits — never only the last one-line fix. A narrower follow-up description that omits inherited scope contradicts this rule; keep every inherited change in scope.21 For a stacked PR, compare against its immediate parent's branch. Describe22 that complete incremental diff and link the prerequisite and stack; do not23 present lower layers as new changes in every child. Separately name24 cumulative integration checks, their tested heads/bases, and the intended25 merge prefix. Refresh the description and evidence after restacking.268. **Keep lasting norms in the canonical spec package.** Requirements, behavior, architecture decisions, and normative tool or quality rationale belong in the existing spec structure (spec, plan, contracts, tasks), updated in place. Do not publish standalone rationale reports, selection notes, parallel design documents, or status histories beside it. This is not authority for blanket deletion: preserve legitimate user, API, and reference docs. Before publication, verify each new normative document belongs to the canonical structure and its links resolve. Attempt details, run pages, and review receipts stay linked from the PR, not duplicated into lasting docs. Use generic examples only; keep private project names, paths, and receipts out of public prose.2728## Mechanics2930- Write readable Markdown with real newlines. Build API calls with structured arguments or a body file (`gh --body-file`); never interpolate free text into a shell string.31- After saving, read back the rendered title and body and confirm they show what was intended.32- Review the description alongside the code before merge, the same as the diff itself.3334## Short example3536Title: `fix(auth): reject expired session tokens at the API boundary`3738Body:3940```markdown41Expired sessions returned a generic 500 from deep in the request handler.4243They now fail fast with 401 at the API boundary, so clients refresh the44session instead of retrying a doomed request.4546Changed `session.py` to validate expiry before dispatch; expiry checks live47in one place so future handlers inherit the behavior.4849## Validation5051- `pytest tests/test_session.py -q`: 24 passed.52- `ruff check src/`: clean.53- Limit: covers API sessions only; web-cookie expiry is unchanged and tracked54 in #412.55```5657## Complex example5859Title: `feat(sync): retry failed uploads with backoff and keep local order`6061Body:6263```markdown64Uploads failed permanently on the first transient network error, and retries65— when added by hand — reordered the local queue, so users saw items arrive66out of order after a flaky connection.6768Uploads now retry up to 5 times with exponential backoff, and the queue keeps69its original order across retries. A retry that exhausts its budget surfaces70as a failed item with its error attached instead of blocking the queue.7172The retry loop lives in the upload worker; ordering is preserved by holding73each item's slot until it resolves. Backoff caps the extra load; the74failed-item state keeps one bad upload from stalling the rest.7576## Validation7778- `pytest tests/test_upload_retry.py tests/test_queue_order.py -q`: 61 passed.79- Load check `scripts/replay_flaky.py --seed 7`: order held across 200 injected faults.80- Limit: worst-case delivery delay grows under sustained faults; follow-up in #418.81- Spec: #402.82```8384## Pairs with8586- `radical-brevity`: make a final meaning-preserving cut after the required context and evidence are in place.87- `gate-before-push`: run the repository's own gates locally first so the described validation is already green.88- `github-pr-shepherding`: classify the PR from GitHub state and drive it to merged or explicitly blocked.89- `stacked-diff-discipline`: keep each layer small, document its parent and native stack, and distinguish incremental review from cumulative validation.90- `evidence-claim-boundaries`: decide what a given piece of evidence actually supports before you claim it in the validation section.9192## DONE means9394A reviewer who never saw the agent conversation can state the behavior change, the rationale, and the validation from the title and body alone; the title satisfies the repository's title check; and the validation section names the checks run, their outcome, and material limits — without pasted operational output or claims beyond what was verified.9596Sources: repository title/commit gating practice; conventional-commit release gating; shift-left test evidence.