open-pr

A pull request is a lot of things skipped, usually: a stated goal, a way to check that goal without re-reading the whole diff, an honest note on risk. This skill is the fixed shape that keeps those present on every PR, whatever host you're on.

Arguments: $ARGUMENTS — first word selects the sub-command.

Host-agnostic setup

This skill assumes a git-hosting CLI is on PATH and authenticated — gh (GitHub), glab (GitLab), or your host's equivalent. Resolve once per invocation:

if command -v gh >/dev/null 2>&1; then HOST_CLI=gh
elif command -v glab >/dev/null 2>&1; then HOST_CLI=glab
else echo "open-pr: no git-hosting CLI found (need gh or glab on PATH)" >&2; exit 1
fi

Everything below is written against gh's command shape; substitute the equivalent glab (or direct REST) call if you're on a different host. Never hand-roll the diff/PR-metadata fetch when the CLI already exposes it — that's the thing most likely to silently drift from the real API.

create — Open a pull request

1. Preflight — one branch, one PR. Before opening a new PR, check whether the current branch already has an open one:

   gh pr view --json number,url 2>/dev/null && echo "PR already exists for this branch — push instead of opening a new one" && exit 1

2. Gather the diff against the real base, not a stale local branch:

   git fetch origin "$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)" --quiet
   git diff origin/<base>...HEAD --stat

3. Write the body with the mandatory sections (do not omit any):

   ## Problem
   <What's observably wrong or missing TODAY, and who/what it affects. Plain language — no
   function names or file paths yet. A reviewer should feel why this matters before any solution.>
   
   ## Goal
   <One objectively-checkable sentence: a test that now passes, a specific behavior, a file that
   now exists. NOT "improves code quality" or "fixes the bug" — those aren't checkable.>
   
   ## Verification
   1. **<check name>**:

   <exact command> # Expected: <exact condition> ``` 2. ...

   What changed

   <2-4 bullets: the mechanism — function/file names, what changed and why. Keep this OUT of Problem/Goal above; those two sections must stay readable without touching the diff.>

   Risk

   <docs-only | cleanup | bugfix-narrow | bugfix-wide | feature | infra>

   Review gate

   • Goal-Diff alignment — every changed file justified by the Goal
   • Verification green — every Verification check passes
   • Reviewed by a second agent or human

   
   **The reader test:** someone who has never opened this code should be able to restate, from
   `Problem` + `Goal` alone, what was wrong and how you'll know it's fixed — without reading the
   diff. If the Goal reads like a title ("refactor the dispatch path"), rewrite it as a checkable
   outcome.
   

4. Open it and report the URL:

   gh pr create --title "<type>: <description>" --body-file <tmpfile> --base <base>

   Title follows the project's conventional-commit prefix (feat|fix|refactor|docs|test|chore).

review — Verify a PR against its own contract

Does: checks the PR delivers what its own ## Goal + ## Verification promise, and that the diff is fully explained by the ## Goal. Does not: replace human judgment on architecture, taste, or security — this is a mechanical gate, not a substitute reviewer.

1. Fetch the PR and check out its head ref into an isolated worktree (never review in your main working tree — see disciplines/worktree-isolation-per-agent.md):

   gh pr checkout <N> --branch "pr-review/<N>"

2. Hard gate: if ## Goal or ## Verification is missing, or the Goal isn't a checkable statement (no verb implying a testable outcome), stop and report that — do not invent your own checks to paper over a missing contract.
3. Run every Verification check and record PASS/FAIL/UNKNOWN against its stated # Expected:. A check you can't run (missing fixture, needs prod access) is UNKNOWN, not a silent skip.
4. Goal-Diff alignment: git diff origin/<base>...HEAD --name-only — for each changed file, is it justified by the Goal? A file that's neither justified by the Goal nor an obvious support file (test, doc for the change) is OUT-OF-SCOPE.
5. Baseline sanity: grep the diff for secrets (api[_-]?key|secret|password|token|-----BEGIN), debug artifacts (console.log, print(, TODO, pdb.set_trace), and confirm the title uses a conventional-commit prefix.
6. Verdict (first true wins):
   • Any Verification FAIL, or any OUT-OF-SCOPE file → BLOCK.
   • Any UNKNOWN check, or a secret/debug-artifact hit needing a human call → NEEDS-HUMAN.
   • Everything checked and clean → SHIP.
7. Post the report as a PR comment (gh pr comment <N> --body-file <report>), and on SHIP, tick the review-gate checkboxes in the PR body.
8. Clean up the review worktree whether the review passed or not — git worktree remove + delete the local pr-review/<N> branch.

merge — Merge after the gate

1. Re-confirm every ## Review gate checkbox is ticked in the current PR body — do not trust a memory of a prior review; re-fetch the body.
2. Confirm mergeable + CI green:

   gh pr view <N> --json mergeable,statusCheckRollup

3. If both hold, merge (gh pr merge <N> --squash or the project's preferred merge strategy) and close any issue the PR's Closes #<N> line references (most hosts do this automatically on merge — verify rather than assume).
4. If either check fails, stop and report which gate is unmet — never merge past a red check because "it's probably fine."

check — Inbox pass

List every open PR you own (gh pr list --author @me --json number,title,url,statusCheckRollup), and for each: is it waiting on you (new review comment, failing check) or waiting on someone else (pending review, pending CI)? Report only the ones waiting on you, grouped by what's needed (fix-CI / respond-to-comment / needs-a-review-request).