How to keep pull request descriptions up to date

Rewrite the description on every push so reviewers read what the branch actually does now, not what it did on the first commit.

A pull request description is written once, at open, when the author knows least about the change. Four commits later it describes a branch that no longer exists. Reviewers read it anyway, and the ones who notice it is stale stop reading descriptions at all.

An agent can rewrite it on every push. The pushed action fires on every head advance, including the open, so one trigger covers the whole life of the branch.

ellipsis:
  version: v1
  name: PR describer
  description: Keeps the pull request description current on every push

claude:
  system: |
    Read the full diff of this pull request and the surrounding code,
    then rewrite the description to match what the branch does now:
    what changed, why, and what a reviewer should look at first.

    Preserve anything the author wrote by hand: checklist items, test
    notes, links to issues. Never delete a human's words, and never
    describe work the diff does not contain. Update the description
    with `gh pr edit`.

trigger:
  type: react
  pull_request:
    on: [pushed]
    repositories: [splitshift-api]

sandbox:
  repositories:
    - name: splitshift-api
  github:
    permissions:
      contents: read
      pull_requests: write

budget:
  session: 0.50
  day: 5.00

priya-shah opens "Expire pending trades on account deactivation" with a one-line description, then pushes the rest-period check and a migration over the afternoon. Each push rewrites the description:

Expires pending trade requests when the counterparty account is
deactivated, and enforces rest-period rules on the remaining
trades.

- `trades/expiry.py`: pending trades belonging to a deactivated
  account move to `expired` instead of hanging.
- `trades/validation.py`: rest-period check now runs before a
  trade is accepted, not after.
- Migration `0042`: backfills `expired` for existing pending rows.

Start with `validation.py`. The check moved earlier in the flow,
so a trade that used to be accepted and then flagged is now
rejected outright.

<!-- author's notes, preserved -->
- [ ] Confirm with support before deploying

Scope the token to the job

This agent edits descriptions. It has no reason to push code, so the token says so:

sandbox:
  github:
    permissions:
      contents: read
      pull_requests: write

A permissions map may never exceed what the GitHub App installation already holds; it can only narrow. The alternative, permissions: read_only, is too narrow here: writing the description needs pull_requests: write.

Keep it off other agents' work

for.bots defaults to false, so bot-authored pull requests never trigger the describer. If a release bot opens pull requests you do want described, opt that in explicitly:

trigger:
  type: react
  pull_request:
    on: [pushed]
    for:
      users: true
      bots: [release-please]

Cost

pushed fires on every commit, so this is a high-frequency agent. The per-session budget is the control that matters: at 0.50 a busy repository costs a few dollars a day, and the trailing day cap bounds a bad afternoon. Reading a diff and writing prose is cheap work, so a small model is usually the right call.

Review the code on the same pushes with How to review every pull request as commits land, or see the full filter set for the pull_request surface in the agent config reference.

How to keep pull request descriptions up to date

Scope the token to the job

Keep it off other agents' work

Cost

Next

On this page