Shipping A Pr Agent Skill

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.