| name | shipping-a-pr |
| description | Use when finished work needs to ship as a pull request, or when the ask is about a PR — creating one, bringing it up to date, adding screenshots, watching its checks, or addressing its review comments. Not for reviewing a PR you are not shipping. |
Shipping a PR
The PR lifecycle: ship the workspace's finished work as a pull request and keep that PR healthy
until it is mergeable. One workflow, five phases as sibling docs — enter at the phase the ask names.
The done bar (applies to every phase)
A PR is done when every check it has is green — a repo with no CI is reported as exactly
that, never silently treated as green — and the user has the link plus its current state; never at
"PR opened", "pushed", or "comment replied". Every phase below therefore ends in checks.md,
which declares this workflow's terminal state.
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. Three 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.
- Fetch, don't remember. Remote state is read fresh and completely at the moment it's needed:
the current body before editing it,
--paginate on every listing, git fetch before reasoning
about the base.
- Indeterminate is not affirmative. A pending or still-computing answer (an
UNKNOWN merge
state, queued checks) is polled until it resolves; done is declared only from observed
affirmative state, never from the absence of a bad signal.
Classify the ask
| The ask | Phase doc |
|---|
| Create a PR — the work is finished | creating.md |
| Bring the PR up to date / resolve conflicts with its base | syncing.md |
| Add or refresh screenshots on a PR | screenshots.md |
| Monitor CI / investigate or fix failing checks | checks.md |
| Address review comments | review-comments.md |
Read and follow the selected phase doc — the gates and mechanics live only there; never run a
phase from this spine's summary. 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 path ends in checks.md; its terminal state is the only way this workflow finishes.
