PR

Pull request workflow

Five sections, run in this order:

1. Orient — the working tree, and the base branch
2. Prepare the branch — merge, cleanup, migrations. Skipped for a description-only ask
3. Publish — read the final diff, write the body, push, create or update
4. Screenshots — frontend diffs only
5. What this run taught you — always last, whatever else ran

Shell state does not persist between commands. Each command below runs in its own shell, so a BASE=main in one is gone by the next. Substitute the real values into every command — write origin/main, not origin/$BASE — and carry the base branch and PR number in your head, not in the environment. Every origin/main below means "the base branch from Orient".

Run the gh commands as written. The appendix at the bottom covers the one environment that has no gh.

Orient

Check the working tree

git status (no -uall). Everything below diffs origin/main...HEAD, which only sees committed work, and the merge in Prepare the branch needs a clean tree — so the tree has to be clean before you go further.

• Uncommitted changes you made in this session: commit them now. Otherwise the cleanup, the classifier and the diff you describe all silently skip them, and the PR body describes the wrong diff.
• Uncommitted changes you didn't make: stop and ask. Don't sweep someone else's work into a commit.

Determine the base branch

The base is the branch the PR goes off of — main by default. The head is always the current branch (HEAD), so the branch that sets the base is a different one the user points at: "a PR off of release-2", "base this on release-2", "onto/target release-2", "stacked on <branch>", or a --base <branch> argument. Naming the branch you're already on only identifies the head — the base stays main. If it's genuinely unclear whether a named branch is meant as the base, ask rather than guess. Never silently retarget an explicitly-named base to main.

When updating an existing PR, leave its base untouched — run gh pr edit without --base. Only retarget when the user explicitly asks.

Prepare the branch

Skipped in full when the ask is only to reword an existing PR's description — fixing the wording shouldn't rewrite code. Everything else (creating a PR, "get this ready", an update after new commits) runs it.

Update from the base

Bring the branch up to date so the PR reflects the current base and merges without surprises. Follow the merge-conflicts skill: git fetch origin then git merge --no-edit origin/main, merge (never rebase), keep the merge commit to just the merge, and resolve conflicts per that skill.

This has to happen before the cleanup below, which diffs against origin/main.

Simplify, lint, and conform to AGENTS.md

references/pre-push-cleanup.md has this in full: /simplify, bin/lint scoped to the branch's files, branch-scoped specs, a pass over the changed files against AGENTS.md, its five audits — spec, documentation, churn, comment and backfill — and the cycle-type translation check. The audits are required every run, not just when the diff looks messy. Commit everything it produces before re-dating migrations.

Freshen stale migration timestamps

Migrations this branch adds have to be dated within the past 2 days, or the rollback/rename/re-migrate order in references/pre-push-cleanup.md re-dates them. Skip when the branch adds no migrations.

Publish

Gather branch state

Run in parallel:

• git diff origin/main...HEAD --stat
• git diff origin/main...HEAD --name-only
• git log origin/main..HEAD --oneline
• gh pr view --json number,url,title,state

Diff against origin/main, not the local base branch — in a Conductor worktree the local base often lags the remote, which would inflate or stale the diff. If you skipped Prepare the branch, git fetch origin first. If the branch has no commits ahead of origin/main, stop and tell the user.

rtk proxy the git log — rtk's hook strips merge commits from git log --oneline, so the merge Prepare the branch just made is absent and the branch reads as though it never merged.

gh pr view exits non-zero with "no pull requests found" when the branch has none — that's the answer to the create-or-update question below, not a broken command, and it's the normal case on a first run.

gh pr view returns MERGED and CLOSED PRs too. Only a PR whose state is OPEN counts as existing — for a merged or closed one, create a new PR rather than editing it. Note the number; the push and Screenshots both need it.

No bin/env eval is needed here — it's only relevant to the screenshot phase, and frontend-screenshots runs its own in preflight. Backend-only PRs never touch it.

Classify the diff

The diff is frontend if a changed path matches one of these and renders a page a reviewer could look at:

• app/views/** (.erb, .html.erb, .haml — deprecated, but still most of the directory)
• app/components/** (ViewComponent templates or Ruby)
• app/javascript/**
• app/assets/**
• config/tailwind*, tailwind.config.*, postcss.config.*
• *.scss, *.css, *.coffee, *.js, *.ts

Excluded despite matching: mailer views (app/views/*_mailer/**, app/views/user_emails/**) and email components (app/components/emails/**) — capture those only when the user asks, via the mailer preview frontend-screenshots documents. API and JSON views (app/views/api/**, *.json*, *.jbuilder), and build config (app/assets/config/manifest.js, esbuild.config.js). A diff that only changes comments or non-rendering config isn't frontend either.

Markup a reviewer can't see is also excluded — a tw:hidden field, a data- attribute, an aria- or meta change. It renders, so the paths above match it, but before and after are the same image, and the ## Screenshots comment it produces is two identical captures. Ask what the shot would show, not whether a template changed. #4222 and #4262 (the register honeypot, added to each step) are the pattern; neither posted screenshots.

Record this as frontend true/false — it's what Screenshots gates on.

Write the summary body

Write the body to a file under the repo's own tmp/; a PreToolUse hook refuses writes outside the checkout. Read the last few merged PRs first — gh pr list --state merged --limit 5 --json title,body — they're the tone to match. The house shape is a short intro paragraph saying what was broken or what this is, then 2–4 bullets each opening with a bolded clause. Title under ~70 chars.

Rules:

• Bias hard toward brevity. Default to a one-line intro plus 2–3 bullets, not the maximum. A bullet that fits on one line beats one that wraps three times.
• Cut anything visible in the diff. Which HTTP client, file-mode flags, helper names, column renames, the exact files removed — that's the diff's job. Keep only what it doesn't make obvious: what the PR adds, the entry point a reviewer would use, and any non-obvious decision they'd otherwise reverse-engineer.
• Describe the end state, not the journey. No "first pass" / "second pass", no commit hashes for stages that all land in the same diff, no "originally we tried X then switched to Y". When updating an existing body, rewrite it to describe the current diff — don't append a changelog of edits since the last revision.
• Reference branches by PR number. A stacked base or a branch this builds on is #3918, not a branch name: gh pr list --head <branch> --state all --json number --jq '.[0].number'. Name the branch only when it has no PR.
• No "Test plan" section unless the user asks. Never list what CI already covers. Only reviewer-facing manual verification ("click X, confirm Y appears") qualifies, and only on request.
• No generic "covered by tests" bullet. That a change is tested is assumed, and naming test mechanics (a fixture, a cassette) goes stale. Mention tests only when what is verified is the reviewer-facing point ("adds a regression test for the UTF-8 download crash").
• No Claude Code attribution footer, here or in any comment this workflow posts. It should read like the human author wrote it. Leaving it out isn't enough where gh is missing: create_pull_request and add_issue_comment append one server-side (the tell is the session id in its link), while the update_* calls don't — so read back what you posted and strip it with an update.
• A backfill leads the body. When the branch adds a Backfills:: job, the intro says existing rows need one, and the first bullet names the job with the command that runs it once after deploy — Backfills::…Job.perform_async. #4429 is the pattern.
• Link the issue when there is one. If the branch name, a commit message, or the user's request names an issue, close it from the body — Closes #4103 on its own line. Don't invent a number.

If a bullet is turning into an essay, compress it to one sentence naming the kind of change.