pr

Create or Update a Pull Request

Open a PR whose body comes from .github/pull_request_template.md, with the Issues and Docs sections filled in from real signal on the branch, and run the four-pillar judgment passes BEFORE pushing so journal hygiene lands in the same change set. If a PR already exists for the current branch, route to update-mode: diff the current body against the freshly-rendered one, ask before applying, and use gh pr edit instead of gh pr create. This replaces the generic PR-creation flow — do not call gh pr create or gh pr edit directly outside this skill.

Contract

Goal. Be the single, mandatory path for opening or updating a pull request in this repo. The skill renders the PR body from .github/pull_request_template.md, fills the Issues and Docs sections from real branch signal (not intent), and runs three judgment passes — tech-debt scan, decision-shape detect, followup capture — BEFORE the body is pushed, so journal hygiene lands in the same change set rather than as separate manual chores. It is create-or-update aware: an existing open PR for the branch routes to update-mode (diff the current body against a fresh render, confirm, then gh pr edit), and merged/closed PRs abort cleanly instead of opening a duplicate. It ships at the Sonnet tier because the work is template-fill + structured signal-gathering with bounded judgment, with the genuinely judgment-heavy tech-debt walk delegated to its own sub-agent — supersede any default PR-creation flow with this skill; never call gh pr create/gh pr edit directly outside it.

Inputs. No $ARGUMENTS — the skill operates on the current branch and its commits. It expects a non-main, non-detached branch with a clean working tree and an upstream it can push (the pre-flight establishes these, pushing the branch where needed). It reads the PR template, the branch's commit log and diff vs main, an existing PR's body (when one is open) including the embedded <!-- /pr render: sha=... --> marker, and the architecture-docs related-files lint.

Outputs. A created or updated pull request whose body is the filled template (section headings and HTML comments preserved) ending in a hidden <!-- /pr render: sha=<40-char> ts=<ISO-8601-UTC> --> marker that lets the next invocation narrow judgment-pass scope to "since last render"; an imperative-mood title with code identifiers backticked; drafted journal entries (tech-debt / decision / followup) surfaced per-candidate for the user to accept into /log; on the update path, a pre-render backup of the prior body in .claude/handoffs/; and the PR URL printed. No journal entry is written without per-candidate user accept; no body is overwritten without confirmation.

Success criteria.

• The pre-flight gates hold: not on main, not detached, clean tree, branch pushed — hard failures stop and report; an obvious push is not gated behind a verbal question.
• Existing-PR routing is correct: open → update-path (diff, confirm, gh pr edit); merged or closed → abort with the right recovery instruction; none → create-path.
• The four-pillar judgment passes run against the resolved <lower> SHA (prior render marker on update, main on create) so the user isn't re-asked about already-handled candidates, and each candidate is confirm/skip per-item.
• The Issues section always contains something (a real Fixes/Ref #N, or None); the title backticks code identifiers; the Docs checkboxes reflect the actual diff, not intent.
• gh pr create / gh pr edit / Write permission prompts are left intact — they are the user's gate on body content and backup creation, not suppressed.

Failure modes to avoid.

• Polluting the skill's context with the tech-debt walk. Never Read docs/architecture/tech-debt.md inline from inside /pr — that inline read IS the context pollution Pass 1 exists to prevent. Spawn tech-debt-scan as a Task sub-agent with an explicit model: sonnet, and never narrate sub-agent invocation while the transcript shows a Read.
• Auto-applying journal entries. The judgment passes produce drafts only; apply a tech-debt edit or invoke /log only on explicit per-candidate accept.
• Overwriting a PR body without confirmation or backup. On the update path, always diff-then-confirm and write the prior body to .claude/handoffs/ before gh pr edit; if gh pr edit fails, the backup is the recovery path — surface it, don't claim success.
• Opening a duplicate on a merged/closed PR. Abort with the recovery instruction; never silently create a second PR.
• Rephrasing the title to drop a code reference when the spell-check precheck fails — backtick the identifier instead; dropping the reference is the wrong fix.
• Suppressing the create/edit/Write permission prompts by allowlisting them — they are intentional user gates.

When NOT to use.

• You want to investigate review comments on an existing PR — that's /pr-review, not /pr (which CREATES or updates a PR).
• There is no branch to ship (on main, or nothing committed) — there's nothing to open a PR for.
• You need to bypass the journal-hygiene passes for a genuinely trivial change — that's still in-scope (skip the judgment block with one confirmation), not a reason to call gh pr create directly.

Implementation

gh pr edit and Write are intentionally NOT pre-approved in this skill's frontmatter — the permission prompts they trigger are the user-approval gate for body overwrites and local backup file creation. Don't try to suppress them.

The mechanical close-loop side (move ## Currently running → ## Recently shipped, bump last-updated:) runs automatically after the PR merges via .github/workflows/journal-sync.yml. This skill does NOT touch that — its job is the judgment side: tech-debt entries, decision entries, and followup entries that need a human call.

Pre-flight (abort if any fails)

Run in parallel:

• git rev-parse --abbrev-ref HEAD — must NOT be main, must NOT be HEAD (detached). If detached, abort and ask the user to check out a branch first.
• git status --porcelain — must be empty (no uncommitted changes).
• git rev-parse --abbrev-ref --symbolic-full-name @{u} — if no upstream, run git push -u origin <branch>. The permission prompt is the gate; don't ask verbally.
• git rev-list --count @{u}..HEAD — if non-zero, run git push.

If a hard check (on main / detached HEAD / dirty tree) fails, stop and report. Pushing a feature branch to open its PR is obvious — don't gate it behind a verbal question.

Detect existing PR (route create vs update)

Run gh pr view --json number,url,state,isDraft,author,body,headRefOid for the current branch. Branch on state:

• MERGED — abort. Print: PR #<N> is already merged at <url>. Switch off this branch (e.g. git switch main && git pull) before opening a follow-up PR. Don't try to update or open a duplicate.
• CLOSED (not merged) — abort. Print: PR #<N> at <url> was closed without merging. Reopen manually with gh pr reopen <N> if you want to revive it, or start a new branch. Don't silently open a duplicate.
• OPEN — enter the update path. Capture <N>, <url>, <author.login>, <body>, and <headRefOid> for later steps.
• No PR exists (gh pr view exits non-zero with "no pull requests found for branch") — enter the create path (today's flow).

Update-path setup (skip on create path)

1. Author warn (best-effort) — run gh api user --jq .login. If the result differs from the captured <author.login>, print one line: Note: PR #<N> was opened by <other-user>. Body edits will appear under your account. Don't abort. If gh api user fails (auth/rate limit), skip the warn silently — it's informational only.
2. Resolve lower-bound SHA — this becomes the input range for judgment passes (so the user isn't re-asked about candidates already accepted/skipped on the prior /pr render):
   1. Parse the PR body for the marker <!-- /pr render: sha=([a-f0-9]{40}) ts=(\S+) -->. If multiple markers exist (rare — copy-paste), take the LAST match.
   2. If a marker SHA is found AND git merge-base --is-ancestor <sha> HEAD exits 0 → use that SHA.
   3. Otherwise, fall back: gh pr view --json commits --jq '.commits[0].oid'. If that SHA is also reachable from HEAD, use it.
   4. Ultimate fallback (force-push edge case where neither prior SHA is reachable): use main — same scope as the create path. Print one line so the user knows the narrow scope was lost: Note: prior /pr render SHA unreachable from HEAD (rebase or force-push?). Falling back to full-branch scope for judgment passes.
3. The resolved SHA is referenced as <lower> throughout the rest of this skill. On the create path, <lower> is main.

Four-pillar judgment passes (before drafting the PR body)

Three quick passes that surface journal entries the user should write — each with one-line confirm/skip per candidate. Drafts only; the user accepts before any /log invocation. Skip the whole block (with one user "skip judgment passes" confirmation) if the change is trivial (typo / dep bump / docs-only).

Both pass 1 and pass 2 use the <lower> SHA resolved in "Detect existing PR" above as their lower bound. On the create path that's main (today's behavior). On the update path it's the prior /pr render SHA — so the user isn't re-asked about candidates already accepted/skipped on a previous /pr invocation against the same PR.

Pass 1 — Tech-debt scan

Invoke /tech-debt-scan as a sub-agent (not inline) to keep its candidate-walk from polluting the /pr skill's context. Spawn it with an explicit model: sonnet (matching tech-debt-scan's own frontmatter pin) — a sub-agent with no model override inherits the session model, and if that session is a 1M-context model the spawn hits the "usage cred

Content truncated.