checkout

name	checkout
description	Check out the PR branch for an issue — /checkout <issue-number> finds the issue's PR (linked-PR chip fast path, then agent comments, then the claude/issue-N-* branch convention) and checks its branch out in the current repo clone.

Check out an issue's PR branch

Given an issue number (/checkout 97), find the right PR for that issue and check out its branch. This is a mechanical skill: the common case is ONE command — run it without narration and report its OK line at the end.

Fast path (usual case: issue has a linked-PR chip)

Run the script that lives next to this skill (substitute this skill's base directory, which the invocation message provides):

bash <skill-base-dir>/checkout.sh <N>

One invocation does everything: dirty-tree guard, meridian-repo resolution (NOT necessarily origin — fork clones point origin at upstream, whose issue numbers are unrelated), a single GraphQL call for the chip + head/base refs, the VS Code PR-extension branch config (written BEFORE the checkout — the extension reads it on the HEAD-change event), a submodule-recursion-free fetch + gh pr checkout, and a git submodule update so submodule working trees match the new branch (no spurious M in status). If an open ts-mono companion PR exists for the same branch name (the agent convention for viewer work — fork branches and External contributors' upstream branches alike; only agent-authored ts-mono PRs count, so generic contributor branch names can't false-match), the submodule is switched onto that branch — the parent gitlink intentionally shows modified until the merge-time pointer bump.

Chip selection: an OPEN same-repo chip wins; otherwise a single OPEN cross-repo chip is checked out against its own repo — this covers External proxies (the contributor's upstream PR) and promotions still open upstream. With no chip at all, the script falls back to the proxy body's machine-written Upstream PR: line before giving up — chips only exist after the browser sweep runs, so fresh proxies often lack one.

Exit codes:

• 0 — prints OK branch=… pr=… issue=#N (title); report that line, done (a [cross-repo: …] suffix means an upstream PR — relay its caution).
• 2 — dirty tree (files listed on stderr): STOP, show the user; never switch over uncommitted work.
• 3 — no usable open chip (stderr lists the chips it saw, including closed ones and ambiguous multiples): use the slow path below.
• 4 — repo unresolvable: no meridianlabs-ai remote and no gh default.

Slow path (no chip, or only closed/cross-repo entries)

b. Agent comments — scan ALL i-am-marvin comments on the issue for /pull/<M> refs (not just the last comment; superseded PRs sit next to live ones). Keep the open one, newest if several.

c. Branch convention — match PR heads against claude/issue-<N>-*:

gh api "repos/$REPO/pulls?state=all&per_page=100" \
  --jq '.[] | select(.head.ref|test("^claude/issue-<N>-")) | {number, state, head:.head.ref}'

If candidates disagree: open chip > open comment-ref > open branch-match > most recently updated. Say which rule matched. Once a PR number is in hand, finish with the script's tail by hand: write both branch configs BEFORE the checkout (branch.<B>.github-pr-owner-number = owner#repo#M, branch.<B>.vscode-merge-base = <base-remote>/<baseRefName>), then gh pr checkout <M> -R "$REPO", then git submodule update --init --quiet so submodule working trees match the new branch.

Fallbacks — tell the user instead of guessing

• No PR but a branch exists (a "Claude finished" comment names a claude/issue-N-* branch never turned into a PR): fetch + switch to it from the meridian remote; say there's no PR. Still set vscode-merge-base before the switch (with no PR to read the base from, use the branch's fork point — meridian on the fork, the default branch elsewhere).
• Only a MERGED/CLOSED cross-repo chip (the script handles open ones): the work was promoted and already landed upstream. Say so; offer the branch only if the user still wants it.
• Nothing found: list what was scanned so the user can point at the right thing.