Skip to content

Editing PR titles & descriptions

A PR’s title and description start as its commit’s subject and body. You can rewrite either in place: the edit is saved to the PR’s prs file, never to the commit, so the reviewed repo is untouched. The copy buttons then give you exactly the text the real GitHub PR should have, project context included.

The description editor open on a PR: Write and Preview tabs, a formatting toolbar, the text, and Cancel and Save buttons

  • Title: Edit beside the title turns it into an input. Enter saves, Esc cancels (asking first if you changed it).
  • Description: the pencil in the description’s header (or … → Edit) opens a Write / Preview editor with a small toolbar (bold, italic, code, link, list, quote; ⌘B / ⌘I / ⌘K), prefilled with the current description. ⌘/Ctrl+Enter saves, Esc cancels (asking first if you changed something).
  • Back to the commit message: saving text identical to the commit message clears the override instead. An overridden field shows edited ▾ (“Edited locally; the commit message is unchanged”), whose menu shows the commit’s version and has Revert to commit message.
  • If the file changes while you edit (an agent rewrote the description): an untouched editor just follows it; one with your changes keeps them and offers Load it / Keep mine.
  • Drafts are kept as you type, so they survive switching tabs and commits, a reload, or closing the browser. See Drafts.

An agent can do the same by writing title: / body: into the prs file, or with PUT …/pr; the UI shows it live.

Every text box keeps what you type, as GitHub’s do: the PR title and description, the project intro and stack notes, a new comment, a reply, an inline comment (on a line or a range), and an edit of one of your comments.

A new comment box after a reload: "Restored an unsaved draft from 16" with Discard above the text, which is still there
A comment typed, then the page reloaded before it was sent. (The capture rig typed it; the app kept the draft.)
  • Kept as you type, a moment after you stop. Reload, close the tab or come back tomorrow, and the editor is open again with your text (an inline comment’s form on the same line in Files changed), under a line saying Restored an unsaved draft from 10:42, with Discard.
  • Cleared once it’s saved, when you cancel or discard it, or when the saved text comes to say the same (saved from another tab, say). A save that fails keeps the draft. An editor you opened but didn’t change leaves nothing behind.
  • If the saved text changed meanwhile (an agent rewrote the description in the prs file, or the intro in project.yaml), neither version is overwritten: the editor says it was changed elsewhere and offers Load it (theirs; your draft goes) or Keep mine.
  • A small amber dot marks where drafts are waiting: on a PR’s row in the sidebar and on its Conversation or Files changed tab, on a stack’s title, and on the project page link (for the intro).
  • Two tabs on the same page share their drafts: what you type in one shows up in the other, except in a box you’re typing in there. The last one written wins.
  • After a rebase, a draft on a commit that’s gone moves to the commit that took its place, matched the way review files are (the same patch-id, else the same subject if no other commit has it: Following rebases), and an inline one moves to where its line is now. Its notice says which commit it was written on. A draft whose PR has gone without a successor is kept until it expires, in case it comes back.
  • Housekeeping: a draft nobody has touched for 30 days is dropped, and all of them together are kept under about a million characters, the oldest going first.
  • No “Leave site?” prompt while your drafts are kept, since they come back anyway. If the browser can’t keep one (its storage is full or turned off), the editor says so, and only then does leaving the page ask first.

PR descriptions, stack notes and the project intro can show images: a diagram, a screenshot, a before and after. All three take them the same way, wherever you edit them (the PR page, the stack page, the project page, or the context boxes). In any of their editors, paste an image (a screenshot from the clipboard), drop an image file onto it, or use the image button in the toolbar. Each one is uploaded into the project’s assets/ folder, and its markdown goes in at the cursor:

![Architecture diagram](assets/3f2a9c1e0b7d4a65.png)
  • While it uploads, an ![Uploading …]() placeholder holds its place and Save waits.
  • PNG, JPEG, GIF, WebP and SVG, up to 5 MB. Anything else is refused with a message under the editor (Couldn't add notes.png: the file isn't a PNG image …), and its placeholder is removed.
  • The same image added twice is stored once: files are named by their content.
  • An agent adds one with local-review asset add <project> <file>, which prints the same markdown (CLI).
  • Images on the web (![x](https://…)) work as in any markdown. Comments show assets/ images too, but have no upload.

Where the files live, and why they’re never deleted: Images.

Click an image (the cursor is a magnifier over the ones you can) to open it in a viewer over the page, scaled to fit the window, with its title, or else its alt text, as the caption. That works wherever markdown is shown: descriptions, stack notes, the project intro, comments, and an editor’s Preview.

  • Click the image (or the magnifier button) to see it at 100%, its full size, centred on the point you clicked. Scroll or drag to move around it; click again to fit it back to the window. An image that already fits at 100% has nothing to zoom to.
  • ← / →, or the arrows at the sides, step through the other images in the same description, note or comment, wrapping round at the ends; the top corner shows which one you’re on (2 / 4).
  • Esc, the × button or a click outside the image closes it, and focus goes back to the image. Images can be focused with Tab and opened with Enter or Space, too.
  • Images in links keep the link. A badge or a screenshot that links somewhere else opens its link, as on GitHub. An image linked to itself ([![diagram](assets/….png)](assets/….png)) opens the viewer; ⌘/Ctrl- or shift-click it to open the link instead.
An image in a stack note open in the viewer: a diagram of what happens to an offered spot, fitted to the window over the dimmed stack page, with its alt text as the caption and zoom and close buttons in the corner
The viewer, open on an image in a stack note. Staged for this page: the demo's stack notes have no images, so this diagram was added to one with local-review asset add.

While the viewer is open, the other keyboard shortcuts are off, so j / k don’t move you to another PR behind it.

Context flows down: the project’s text shows on each stack page and PR page, and the stack’s on each of its PR pages. On a PR’s Conversation tab, above the description, there are two compact boxes:

  • Project context (plum): the project intro, linking to the project page.
  • Stack context (in the stack’s colour, with its STACK n · TITLE): this PR’s stack note, linking to the stack page. PRs that aren’t in a declared stack (Unstacked, or a repo without stacks:) have no stack note, so no stack box.

Each has Copy and Edit. Edit opens the same editor as the description (Write/Preview, the toolbar, image attachment, ⌘↵ saves, Esc cancels, and a “changed elsewhere” notice). A draft is shared with the other places the same text is edited, so you can start it on a PR and finish it on the stack page. Collapse a box with its chevron; each kind remembers that on its own (in localStorage, for every PR and project), and a collapsed box shows its first line. Images in them are drawn as thumbnails, up to 180px tall; click one for the lightbox.

The Project context and Stack context boxes, each with copy and edit buttons and a link to its page

  • The project intro is description: at the top of project.yaml: context for the whole effort. It’s also the Conversation tab of the project page.
  • The stack note is description: on the stack: how this stack relates to the others. It’s also the Conversation tab of the stack page.

Saving writes just that one field into project.yaml, keeping its comments and formatting. The UI never writes text you didn’t type: nothing is generated. Details: How the UI edits project.yaml.

ButtonCopies
The copy icon beside the titleThe plain title (no #n).
The copy icon in the description headerThe description’s raw Markdown.
… → Copy MarkdownThe description’s raw Markdown, as the copy icon does.
… → Copy title + descriptionThe title, a blank line, then the body.
Full body (beside the copy icon), or … → Copy full PR bodyWhat the real PR’s body should be (below).

The full body is the project intro, a blank line and the stack note (if there is one), then a blank line, ---, a blank line, and the PR description. Missing parts are left out:

Why this effort exists, … ← the project intro
First of three stacks: … ← the stack note
---
What this PR changes, and why. ← the PR description

The separator is CONTEXT_SEPARATOR in shared/prText.ts, and local-review plan composes exactly the same text, so what an agent publishes matches what you copied.