writing-pull-requests

name	writing-pull-requests
description	Write a GAIA pull request description someone can read cold — how to fill the template in .github/pull_request_template.md, and the habits (session narration, commit lists, "CI is green", missing screenshots, missing deploy steps, a fix with no real root cause) that make our PRs unreadable. Use when opening a PR, rewriting a PR body, or judging whether a description is good enough.

Writing Pull Requests

Who you are writing for

An engineer who has never seen this branch, was not in the session that produced it, and is reading it cold — in review, or a year later while bisecting a regression into it. They already have the diff and the commit log. What they don't have is why this exists, what it does for a user, how to see it working, and what breaks if it's wrong. That's the whole job of the body.

Two tests for every line:

• Will this still be true after merge? "CI is green", "all tests pass", "94 pre-existing lint errors on master", "merge this after the other PR" — false or pointless within a week.
• Does it only exist because of the session that wrote it? "Then I tried X instead", "18 commits of small fixes", session links, "please confirm this commit is yours". Never attribute the work to a tool either — no "generated with" footer, no co-author trailer, in the body or the commits. Open questions get resolved before review or posted as a comment, not parked in the body.

How it should read

Explain it the way you would to a teammate at your desk: plain sentences, in order, with the reasoning connecting them. Two ways that goes wrong — the wall of prose nobody finishes, and clipped fragments that list everything and explain nothing. "Saved logins, lifecycle rule, recap nav" says nothing; "logins are saved per user and encrypted at rest, so a repeat task on the same site skips the sign-in" says what happened and why it matters.

Length follows content. A one-line fix gets a paragraph; a feature across five surfaces gets a page. Neither gets padding, and neither gets a lab notebook — round-by-round investigation notes belong in an issue. Skip internal shorthand or gloss it once; acronyms and service names are invisible walls to anyone outside the thread that invented them. And say things the plain way: "this was broken for every user on mobile", not "a regression manifested in the mobile render path".