ship-it

Ship It

Input: a PR number or URL, or nothing — then use the current branch's PR (gh pr view with no argument resolves it). If the current branch has no PR yet, push it and open one with gh pr create (maintainer branch only), then continue. Goal: the PR merged with every code-review finding fixed and CI green.

0b. A figure in the description, when the change has a shape

If the PR changes how something flows — a request path, a background job, what a feature does step by step — a picture explains it faster than the diff does. Use the figure skill: write a JSON spec, render one animated SVG, and put it at the top of the PR description. It plays in the description with no upload and no click.

Reference it by commit SHA, not branch name, or the image dies when the branch is deleted at merge: https://raw.githubusercontent.com/<owner>/<repo>/<sha>/<path>.svg. If the SVG is not part of the change itself, don't commit it to the repo — render it, commit it on the PR branch only if it belongs there, and otherwise keep the description's image pinned to the commit that carried it.

Skip it for a fix with no shape: a one-line guard, a dependency bump, a typo.

0. Blocker rule (applies at every step)

A blocker is a finding whose fix would go against the PR's goal — the code-review principles say the thing the PR sets out to do is wrong (e.g. the PR's whole point is a raw-SQL handler, a new advisory lock, a tuple-returning API, a test that asserts via SQL, dropping bank scoping), or fixing it would mean rewriting/removing the feature rather than polishing it.

On a blocker: stop immediately. Don't push, don't merge, don't partially fix. Tell the user what the PR is trying to do, which principle it conflicts with (quote the code-review section), and the options you see — then ask for confirmation with AskUserQuestion. Resume only on an explicit answer.

Everything else (must fix, should fix, nits) is not a blocker: fix it all.

0c. Track everything you start (applies at every step)

Whatever you launch to verify the PR — API, worker, control plane, docs server, a pg0 instance — you must stop yourself at the end (step 7), without touching anyone else's. Other Hindsight worktrees, servers and pytest runs share this machine.

• Start background processes so you know their PID (run_in_background, or cmd & echo $!) and

write each one down. Note the ports you picked.

• Need a database? Give it a new, unique pg0 instance name (e.g.

HINDSIGHT_API_DATABASE_URL=pg0://ship-it-pr-<N>) and write down that you created it. If you reuse an instance that already existed (check pg0 list first), write down that it is shared.

• Never pkill -f hindsight, pkill -f pytest, killall, or kill by port without checking the

PID is one of yours. Those hit other sessions.

1. Load the PR

Read the PR — title, body, linked issue, diff — so you know its goal; the blocker rule depends on it. If it's CONFLICTING, rebase onto origin/main first: a conflicting PR gets zero CI runs, silently.

Work out whether the author is a maintainer (write/maintain/admin on the repo, e.g. nicoloboschi).

2. Check out the PR branch

Work in the current worktree — don't create a new worktree or clone. Before switching, note its state (current branch/commit and any uncommitted changes) so you can restore it in step 6; set uncommitted work aside with a WIP commit or a uniquely tagged stash (never a bare git stash — the stash stack is shared across worktrees). Then check out the PR's branch (skip if you're already on it). On current-branch input, ask the user if uncommitted work isn't obviously part of the PR.

• Maintainer PR: fixes are committed and pushed to this branch — the PR's own head. Never open a separate fix PR.
• External (fork) PR: push to the fork branch too if maintainers can modify it; otherwise stop

and ask the user how to proceed (follow-up PR vs. ask the contributor).

Before every push, make sure the author hasn't pushed meanwhile. If they have, read their new commits and rebase yours onto their head — never force-push over work you haven't read.

3. Review

Read and follow the repo's code-review skill at its absolute path, <repo>/.claude/skills/code-review/SKILL.md (<repo> = git rev-parse --show-toplevel), against the PR's changes (base = origin/<baseRefName>). Collect every finding: must fix, should fix, and nits.

Classify each against step 0. Any blocker → stop and ask.

4. Apply ALL fixes

• Fix every finding, not just the must-fixes. Stay in the PR's scope — don't refactor neighbouring code the review didn't flag.
• Run ./scripts/hooks/lint.sh and the tests covering the touched code (see CLAUDE.md for commands).

Regenerate OpenAPI/clients/docs-skill if the change requires it.

• Loop until clean. One review pass is never enough: fixes introduce new findings, and the

review only sees what the last pass changed. So repeat — review → fix everything → review again — until a full code-review pass returns zero findings of any severity (must fix, should fix, nits). Don't stop at "only nits left", don't stop because the last pass found fewer things, and don't declare done on a pass you didn't actually re-run. The only early exit is a blocker (step 0) → stop and ask.

• Follow-up work is done here, not later. If the PR needs more to be complete — a missing

piece the review or you found, a doc page, a client regen, a test — do it in this ship-it, on this branch. "Follow-up PR" is not an option for work that belongs to this change. Only work that is truly a different problem goes to an issue (step 7).

• Commit with a message that lists what was fixed, then push to the PR branch.

Don't post a review comment on a maintainer's PR — findings go in the chat reply and the commit message. On an external PR, one short comment summarising the fixes you pushed is fine.

5. Wait for CI green

The repo has no required status checks: gh pr merge --auto merges immediately, and gh pr checks reports only the checks registered so far (a lone early Strix check reads as "green"). Gate on the CI workflow run for the pushed head SHA:

SHA=$(gh pr view <N> --json headRefOid --jq .headRefOid)
gh run list --branch <headRefName> --workflow CI --json databaseId,status,conclusion,headSha \
  | jq --arg s "$SHA" 'map(select(.headSha==$s)) | .[0] // empty'

No run yet → keep waiting (give up and report after ~15 min with no run). Once completed, judge per job (gh run view <id> --json jobs): zero failure. If the PR touches the API/engine, test-api (1..3/3), Core LLM tests, and the LLM acceptance matrix must be success, not skipped; for changes outside those paths the change filter skips them legitimately. The oracle-client jobs are known-flaky and may be cancelled — ignore those.

Fork PRs skip `test-api` and the LLM jobs (no secrets). Run the full suite on an upstream branch before merging — merging to main runs no CI at all:

git push origin HEAD:ci/pr-<N>-verify
gh workflow run CI --ref ci/pr-<N>-verify   # exactly ONCE — a second dispatch cancels the first

A failure caused by the PR/fixes → fix, push, back to step 5. A known flake (check the job log isn't touching the PR's code) → gh run rerun <id> --failed once the run has completed. If CI still fails for reasons you can't attribute, stop and report — don't merge red.

6. Restore the worktree, then merge

First restore the worktree to how you found it: switch back to the original branch/commit and re-apply any work you set aside (undo the WIP commit / apply-then-drop your tagged stash). Do the same if you stop early on a blocker or failure. Restoring first also keeps --delete-branch from trying to check out main, which another worktree may hold.

gh pr merge <N> --squash --delete-branch
git push origin --delete ci/pr-<N>-verify   # if you created it

7. Clean up, file issues, report

Do this also when you stop early (blocker, red CI).

Stop what you started — only that. Kill each PID you wrote down in step 0c (kill <pid>; check it's gone, kill -9 <pid> only if it hangs). Before killing, confirm with ps -p <pid> -o command= that it is still your process. For each pg0 instance:

• Created for this ship-it → pg0 drop --name <name> -f (stops it and deletes its data).
• Shared / already existed → don't touch it. Not stop, not drop.

Then check nothing of yours is left: lsof -nP -iTCP:<port> -sTCP:LISTEN for each port you used.

File issues for real project problems you ran into. While reviewing, testing or waiting on CI you may have hit problems that are not this PR's job and not your local setup: a flaky test, a bug in nearby code, a broken script, wrong docs, a CI job that is always red. For each one:

1. Search first so you don't duplicate: gh issue list --state open --search "<keywords>".
2. If none exists, create it: gh issue create --title ... --body .... Body: what happens, how to

see it (command or steps), what should happen, and where in the code. Keep it short.

Local problems (your env, missing tools, a port in use, a stale .env) are not issues — mention them in the report only if the user needs to act.

Report:

• PR link and the CI run that gated the merge.
• The findings fixed (one line each), and anything deliberately left, with why.
• Issues found on the project — a clearly marked section listing each issue you created (link +

one line), and any existing issue you found instead of creating one. Say "none" if none.

• What you stopped and dropped, and any shared pg0 instance you left alone.

Note on gh pr edit

It fails on this repo — a GraphQL "Projects (classic)" deprecation aborts it and nothing changes, silently. To edit a description use the REST API instead:

gh api -X PATCH repos/<owner>/<repo>/pulls/<N> -F body=@body.md