Skip to main content
A reviewer reads the diff and wonders why. The sessions that made the change already know: what was decided, what was tried and dropped, what is still open. orchestra pr describe writes that into the pull request description as a short Why this changed section, with every line linked to the session or memory it came from.

What the section says

  • Why: up to six decisions, approaches ruled out, and constraints, each with a link to the session or issue it came from. Nothing is summarised or invented: every line is something a session or a teammate’s memory already recorded, with its source.
  • Who worked on it: the people on those sessions, and whose memories are cited.
  • Open questions: up to three things the sessions left unresolved.
When nothing recorded is worth saying, nothing is written.

Which sessions count

A session is behind a pull request when one of its commits is in the pull request, when it committed to the same branch, or when it worked on the issue the branch names (Linear branch names like you/orc-311-..., or w-12-... for an Orchestra issue). A session that only mentioned the issue in passing does not count.

Who can see what

The description is read by everyone who can read the repository, so the section holds only what every member of your workspace can already see in Orchestra:
  • A private session, and anything remembered in it, is left out, even when you are the one who can see it.
  • Only private repositories get a section. For a public or internal repository nothing is written.
  • Secrets in the source text are redacted before anything is written.
Links open in Orchestra and ask a reviewer to sign in. Someone outside your workspace sees the text but not the sessions behind it.

Where it is written from

orchestra pr describe reads and writes the pull request with your own gh, on your machine. Orchestra sends the cited material it may share; the text is written from your machine to GitHub and is never sent to Orchestra or stored there. Orchestra only changes the text between its two markers (<!-- orchestra:why-this-changed:start --> and ...:end -->). Write anything you like above or below it. If you edit or delete one marker, the description is left alone; delete both to start over.

Keep it current

GitHub does not tell your machine when a pull request opens, so run it once after gh pr create:
Then install the push hook in your clone, and the section is refreshed in the background after every push:
The hook never slows or fails a push. Any pre-push hook you already had still runs.