A reviewer leaves one comment on your pull request: "why did you do it this way?" You open the diff, read your own change, and realise you can describe what it does but not how you arrived at it. The decision happened in a chat window two days ago, somewhere between the third and fourth attempt, and it is gone. That gap is the whole problem with an AI-assisted PR description: the code review question is almost always about reasoning, and the reasoning is the one thing an assistant does not commit.
The usual response is to write more from memory. You reconstruct a plausible justification, it sounds confident, and nobody can tell that you are reverse-engineering your own intent. That works until the reviewer pushes on a detail you no longer hold.
There is a better order of operations, and most of it happens before you open the PR form.
The diff shows what changed, never why
A diff is a complete record of outcome and a terrible record of intent. It shows that maxRetries moved from 5 to 3 and that the backoff became exponential. It cannot show that you tried a fixed 200ms delay first, watched it hammer a rate-limited endpoint in exactly the failure mode you were trying to avoid, and switched. Neither can the commit message, if the commit message says "fix retry logic".
With AI-assisted work the gap widens, because the ratio shifts. When you write a change by hand, you carry a lot of the reasoning in your head by default: you considered the alternatives one at a time, slowly, and the slowness is what made them stick. When an assistant proposes three approaches in forty seconds and you pick one, you have made a real decision but you have barely encoded it. You recognise the right answer without rehearsing why.
Your memory of the reasoning is already thinner than you think
Try this on your last merged PR. Without reopening anything, write down the alternative you rejected and the reason. Most people can produce the alternative and not the reason, or a reason that turns out to be the second one rather than the one that actually decided it.
The reason decays faster than the decision because it was never the thing you were paying attention to. You were paying attention to whether the tests passed. So the practical rule is to capture the why at the moment it is cheap, which is while the session is still open, and not at the moment a reviewer asks, which is when it is expensive and unreliable.
Two lines at the end of a session are usually enough:
### 2026-09-29 Exponential backoff on the webhook sender
Decision: Exponential backoff starting at 500ms, 3 attempts.
Why: The provider rate-limits per minute; fixed short retries
burned the budget on the first failure and made recovery slower.
Rejected: Fixed 200ms x5 (first attempt, made throttling worse).
Consequence: Worst-case delivery latency is now ~4s. Acceptable.
That is the raw material for the PR description, written while you still know the answer. The longer format and what counts as a decision worth recording are covered in lightweight decision records for AI-assisted projects.
What an AI-assisted PR description owes a reviewer that a commit message does not
A commit message explains a change to the future, briefly, in the context of a history someone can scroll. A PR description explains a change to a specific person who has to form an opinion about it today, and who will ask questions if it does not. Those are different jobs, and the PR description carries three things the commit message is not expected to:
- The alternatives you did not take. Half of review friction is a reviewer discovering an approach you already considered and silently dismissed. Naming it closes the loop before it opens.
- Your own confidence, honestly split. Which parts did you verify properly, and which parts do you believe because the tests are green? When an assistant wrote the change, this is the most useful paragraph in the whole description, and the one reviewers quietly wish for. If you are not sure what to check first, reviewing assistant changes before you hit commit is a reasonable checklist.
- A route to the full reasoning. Not the reasoning itself, in full. A route.
Lift the decision record, don't rewrite it
If you wrote the note above, the "why this approach" section of your PR is already drafted. Paste the decision and the rejected option, trim the project-internal shorthand, and link to the record for anything you cut. You are copying four lines, not reconstructing an argument.
This also fixes a duplication problem. A decision record for a pull request and a PR description tend to contain the same content written twice, drifting apart afterwards, with the version in the PR being the one nobody can find again in six months. Keep the record in the repository as the thing that persists, and let the PR description be the summary plus a pointer.
Link the session for the reviewer who wants the path
Some reviewers want the destination. Some want the path, especially on an unfamiliar subsystem or when the change looks stranger than the problem seems to warrant. For the second group, the AI coding session context is genuinely the best artifact you have: it contains the failed attempt, the error output that redirected you, and the moment you corrected the assistant's first instinct.
Not every transcript deserves to be kept, and a 900-message session where you mostly renamed variables helps nobody. The filter is roughly: keep the ones where a decision got made or a dead end got properly explored. Which sessions are worth keeping goes through that in more detail.
The mechanical problem is that a session lives on your machine, and a reviewer is not on your machine. This is where PrjLab fits the workflow: a repository holds your files together with .prjcontext/memory/ and .prjcontext/sessions/, so after prj push the decision record and the transcript exist as an immutable version your reviewer can open in the browser or clone. You paste that link into the PR instead of pasting 400 lines of conversation, and anyone who does not need the detail can ignore it. Sharing AI coding context with your team covers what to check before you share a session, since transcripts pick up more than you expect.
A template you can keep in the repo
Put this in .github/pull_request_template.md or just in your notes. The point of a PR description template here is to make the reasoning sections unskippable, not to add ceremony.
## What changed
One or two sentences. The reviewer can read the diff.
## Why this approach
Lifted from the decision record. Include the alternative
you rejected and what decided it.
## What I checked myself
Be specific: the edge case you ran by hand, the query you
read, the test you distrust.
## Where to look closely
The part you are least sure about.
## Context
- Decision: .prjcontext/memory/decisions/0012-webhook-backoff.md
- Session: <link to the pushed version>
Four of those five sections take under a minute if you captured the decision while the session was open. If you did not, they take fifteen minutes of archaeology and the result is less accurate. That difference is the entire argument for writing the note first.
If you want the storage side of this set up, the getting-started guide walks through prj init and your first push, including what prj status will show you before anything leaves the machine.
