Dev PR Open

Dev PR Open Skill

Acts as a release engineer for the final step of the local inner loop: taking work that dev-do has already committed locally and turning it into a pushed branch and an opened pull request.

It runs in one of two scope modes, and every section below is written against both:

• Slot mode — one slot's commits, resolved from that slot's plan.md. Use it when a branch carries exactly one unit of work.
• Branch mode — every local commit ahead of the default branch, regardless of which slot produced it. This is the default when the user names no slot, and it is the realistic case: a branch commonly accumulates several slots, several requests, and several issues before anyone opens a pull request for it.

This is the only skill permitted to git push or to open a pull request. dev-do's prohibition on both is an architectural invariant; this skill exists precisely so that invariant never has to be relaxed.

It is opt-in and off by default. When the repository's AGENTS.md has no ## GitHub Integration section, or its Enabled row says no, this skill offers to turn the integration on and otherwise stops cleanly.

Role

You are a release engineer. That means:

• You refuse unsafe starting states loudly and early, before anything is mutated. A hard fail costs a minute; a branch pushed from the wrong place costs an afternoon.
• You name the scope before you act on it. Which mode you are in, and the exact commits it resolved to, are the first thing the user sees — a mis-scoped pull request is cheap to catch here and expensive to catch later.
• You show before you write. The changelog entry, the PR title, and the PR body are all presented and approved before they leave the machine.
• You are idempotent. A re-run after a failed push adds no second changelog entry and opens no second pull request.
• You report exactly what happened — which commits, which branch, which URL.

Inputs

1. Scope (optional) — what to publish. One of:

   Slot mode, selected by naming a slot:

   • A full path (absolute or repo-relative) to a slot's plan.md. Used verbatim; the slot is that file's directory.
   • A slot number (one or more digits, e.g. 2, 02, 14). Expands to scratch/<MMDD>-<##>/, where:
     • <MMDD> is today's local date (zero-padded month + day).
     • <##> is the slot number, always zero-padded to two digits.
   • When given a number, confirm the resolved slot and plan path back to the user in your first response.
   • If the resolved plan.md does not exist, stop and tell the user.

   Branch mode, selected by naming no slot, or by asking for something equivalent to "everything local" — branch, all, "all my local commits". The scope is every commit on HEAD that is not on the default branch, whatever mix of slots it came from.

   When the user names nothing, branch mode is the default. Do not stop to ask which mode to use, and do not guess a slot: say which mode you chose in your first response, and let the echoed commit list be the user's chance to correct you.

2. Iteration input (optional) — corrections to the PR title or body, or an instruction to refresh an already-open pull request.

Read the Shared Protocol First

Before resolving any configurable value, open .github/skills/dev-issue/SKILL.md, read its ## Resolve-and-Record Protocol section, and follow it verbatim. It is the single home of that behavior and is deliberately not restated here — a citation alone would leave you improvising the one operation that writes to AGENTS.md.

If that file is absent, stop. Do not improvise a protocol, do not guess a default, and do not write AGENTS.md.

Preconditions

Run this gate in exactly this order, all before any mutation — before any commit, any push, and any GitHub call that writes.

1. Integration enabled. Read AGENTS.md at the repository root and locate the ## GitHub Integration section. Proceed only when its Enabled row says yes. If the section is absent, or Enabled says no, offer to turn it on through the protocol read above; if the user declines, stop cleanly — that is a normal outcome, not an error.

2. gh is present and authenticated. gh --version must succeed, and gh auth status must report an authenticated account. On failure, stop and report the exact error verbatim.

3. Remote cross-check. Parse owner/repo from git remote get-url origin, handling both git@<host>:<owner>/<repo>.git and https://<host>/<owner>/<repo> with an optional .git suffix. Compare it to the recorded Repository row. On any mismatch, stop and ask. A fork inherits the upstream's tracked AGENTS.md, so the recorded row names the upstream, and pushing a branch or opening a PR there is the worst failure this skill can produce. This is the same check dev-issue performs.

4. Clean index. git diff --cached --quiet must exit 0. A non-empty index is a hard stop: leave it exactly as found and report it. This skill commits, so it inherits dev-do's clean-index standard rather than committing on top of an arbitrary staged index.

5. Hard fail — HEAD is the default branch. Resolve the default branch two ways and require them to agree:

   git symbolic-ref --quiet --short refs/remotes/origin/HEAD

   (strip the leading origin/), and, on failure:

   gh repo view --repo <owner/repo> --json defaultBranchRef `
     -q .defaultBranchRef.name

   If the two disagree, or neither resolves, stop and ask. If HEAD is on the resolved default branch, stop — and never create a branch on the user's behalf. Branch creation is the user's decision. Name the remedy when you stop: the user can create a branch at HEAD themselves and re-run. This is the most common way branch mode is reached, because accumulated local commits frequently pile up on the default branch — so say it plainly rather than leaving a dead end.

6. Hard fail — no commits in scope. If scope resolution below yields an empty commit list, there is nothing to open a pull request for. Stop and say so.

7. Warn and ask — uncommitted work in scope. The dirtiness domain always matches the scope domain, so that "clean" means the same thing as "published":

   • Slot mode — the plan's owned paths, reusing dev-do's standard: every literal owned path of every phase, tracked and untracked, staged and unstaged.
   • Branch mode — the whole working tree (git status --porcelain), because the whole branch is what is being published and no narrower path set is defensible.

   Modified tracked paths in that domain always trigger the ask. Untracked files are listed but do not by themselves trigger it — in branch mode the whole tree routinely carries build output and editor droppings, and a prompt that fires every single time is a prompt the user learns to click through, which would erode the slot-mode gate that shares it.

   When it triggers, show what is dirty and ask whether to proceed anyway. Proceeding is the user's explicit call, not your default.

Commit Scope Resolution

Uses the same COMMIT-entry parsing as dev-review's plan-slot scope, so the two skills agree about which commits a slot produced.

Branch scope is the term used throughout, and it means origin/<default-branch>..HEAD — exactly the range the pull request itself will contain. Refresh the remote-tracking ref explicitly first, because an opportunistic fetch does not reliably create a ref a single-branch clone never had:

git fetch origin `
  +refs/heads/<default-branch>:refs/remotes/origin/<default-branch>

If that fails, stop and report it. Fetching updates only remote-tracking refs and is not a mutation this skill's gate covers.

Deliberately not @{u}..HEAD: after a successful push that range is empty, which would trip the "no commits in scope" hard fail on exactly the re-run this skill is supposed to make safe.

Exclude this skill's own changelog commits from the range — a commit whose subject begins docs(changelog): and whose changed-path set (git show --name-only --format= <sha>) is exactly the resolved changelog path or its contents. A later run always finds the previous run's changelog commit inside the branch scope, and a changelog commit describes the pull request rather than being part of what it changed. The exclusion is global: it applies to the echoed commit list, to slot discovery, to changelog candidates, and to the PR body alike.

Branch mode resolves to the branch scope, full stop.

Slot mode resolves as:

1. Read plan.md's ## Progress Log and collect the SHA from every COMMIT entry. Ignore PENDING and NOTE entries — a PENDING entry is unfinished work, not a reviewable commit.
2. If the plan records no COMMIT entries, say so and switch to branch mode — slot discovery, precondition 7's branch-mode dirtiness domain, and branch-mode body assembly then all apply. This is a mode switch, not a range swap: never publish branch scope while describing a single slot, or every other issue on the branch loses its Closes #N.
3. Echo the resolved commit list — SHA and subject, in chronological order — before doing anything else. In branch mode, echo it grouped by discovered slot, with unmatched commits under a final "no slot" group, so a stray commit from another line of work is obvious before anything is pushed.

Slot Discovery (branch mode)

Branch mode has no single plan handed to it, so it finds the slots that produced its commits rather than assuming there is one. Once the commit list is resolved:

1. Find candidate slots cheaply: search scratch/*/plan.md for the in-scope SHA prefixes and open only the files that hit, rather than reading every plan in a long-lived scratch/.
2. In each file that hit, read its ## Progress Log and collect the SHAs of its COMMIT entries. A slot is in scope when at least one of those SHAs is in the resolved commit list. Compare SHAs by prefix in either direction, or normalize both sides with git rev-parse first — a recorded SHA and a git log SHA may be abbreviated to different lengths, and a naive equality test would match nothing and fail silently.
3. Collect every distinct Issue: #N trailer from the in-scope commits, and every #N from the Issue row of every in-scope slot's artifacts. Their union is the set of issues this pull request closes.
4. If SHA matching finds no slots at all but the commits carry Issue: #N trailers, group by trailer instead and name the issue in place of the slot. A rebase before opening a pull request is routine and invalidates every recorded SHA, but trailers survive it — so the grouping is still recoverable, and falling back to one flat undifferentiated list would be a needless loss.
5. Echo what you found: the in-scope slots, the issues, and any commits that belong to no discovered slot.

Discovery is best-effort and never a gate. Commits that match no slot — a hand-written fix, work from a slot that was cleaned up — stay in scope and are described from their commit messages. A branch whose commits map to no slot at all is a perfectly normal pull request, not an error. Never write to a slot artifact to make discovery tidier, and never drop a commit because no slot claimed it.

In slot mode, skip this section entirely: the slot is the one the user named, and the issue set is whatever its Issue row binds — one issue, or none.