Shipping a PR
The PR lifecycle: ship the workspace's finished work, maintain PR metadata, and keep the PR healthy when requested. One workflow, six phases as sibling docs — enter at the phase the ask names.
Completion modes
- Snapshot mode is the default for creating, syncing, or updating a PR and for one-time status requests. Take one fresh checks and merge-state snapshot, report pending/failing/indeterminate state as observed, and stop without polling or fixing unrelated state. A push never upgrades the mode by itself.
- Wait mode requires an explicit remote-completion ask: monitor or watch checks, investigate CI, wait until green, or make the PR merge-ready. Done means every configured check is green, the head is current with its base, and GitHub reports an affirmative merge state; a requested draft is reported as draft, never merge-ready. A repo with no CI is reported as exactly that, never silently green.
Observed, never assumed (applies to every phase)
Git and GitHub state is concurrent and mutable: the base moves, CI lags, mergeability is computed lazily, and this workflow's own steps dirty the tree they just checked. Four rules hold at every step of every phase:
- Verify at the point of action. An irreversible step — push,
gh pr create,gh pr edit, replying to a thread, declaring done — re-checks the exact state it consumes immediately before running. A gate passed earlier does not survive the mutations made since it passed. - Keep verification tied to the final tree. Reuse exact prior results while the inputs they cover remain unchanged. Before every code-affecting push, run project-required checks that are missing or invalidated by later code, configuration, dependency, base, or conflict-resolution changes. If a check, cleanup, or self-review causes another relevant edit, reassess and repeat before pushing.
- Fetch, don't remember. Remote state is read fresh and completely at the moment it's needed:
the current body before editing it,
--paginateon every listing,git fetchbefore reasoning about the base. - Indeterminate is not affirmative. In wait mode, a pending or still-computing answer (an
UNKNOWNmerge state, queued checks) is polled until it resolves; done is declared only from observed affirmative state. In snapshot mode, report it as indeterminate without turning the phase into a watch.
Classify the ask
| The ask | Phase doc | Default mode |
|---|---|---|
| Create a PR — the work is finished | creating.md | snapshot |
| Bring the PR up to date / resolve conflicts with its base | syncing.md | snapshot |
| Update the PR title or body | body.md | snapshot |
| Add or refresh screenshots on a PR | screenshots.md | snapshot |
| Report the current checks / merge state once | checks.md | snapshot |
| Monitor CI / investigate or fix failing checks | checks.md | wait |
| Address review comments | review-comments.md | snapshot |
Read and follow the selected phase doc — the gates and mechanics live only there; never run a phase from this spine's summary. Carry the completion mode selected above into that doc; a later push does not change it. A compound ask ("rebase, verify, and create a PR") is one flow: start at the earliest phase named; the docs chain forward on their own. If the work itself isn't finished — the ask bundles new design or implementation before the ship — that part is not this workflow's; route it per choosing-a-workflow first and come back here when it lands.
Working files
Ephemeral files this workflow uses, all under the workspace's gitignored .thinkrail/context/:
pr-body.md— the PR body draft; always passed via--body-file, never inline.pr-shots/— staged before/after screenshots awaiting attachment.
Both are deleted when the phase that made them completes (screenshots stay while the user is
uploading by hand — see screenshots.md).
Ending
Every phase ends through checks.md in the completion mode selected above.
