> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orchestrahq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pull request context

> A cited Why this changed section in your pull request, so reviewers see the reasoning without installing anything

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.

```bash theme={null}
orchestra pr describe            # print the section for this branch
orchestra pr describe --update   # write it into the pull request
```

## 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`:

```bash theme={null}
gh pr create && orchestra pr describe --update
```

Then install the push hook in your clone, and the section is refreshed in the
background after every push:

```bash theme={null}
orchestra pr hook            # install
orchestra pr hook --remove   # take it out
```

The hook never slows or fails a push. Any pre-push hook you already had still
runs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.