shipping-a-pr

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, --paginate on every listing, git fetch before reasoning about the base.
• Indeterminate is not affirmative. In wait mode, 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. 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.