Skill: gh-pr
Purpose
Open a well-written PR for the current branch: a faithful summary of the
changes, links to the issue and spec, and a verifiable test plan.
Preconditions (check, fix if needed)
- Current branch ≠ default branch. Otherwise, offer to create one
(
feat/<ref>-<slug> or fix/<slug>).
- Everything is committed and pushed (
git status,
git push -u origin HEAD). The flux-gate hook runs the gates on push:
if it blocks, fix the failures first, never bypass it.
- Read
flux-config.yml: github.labels = default PR labels.
Writing
- Title: conventional commit format (
feat(candidates): add pipeline board); it often becomes the squash-merge commit message.
- Body: build it from the actual diff (
git diff main...HEAD), not
from memory:
## Summary
[What the PR does and why, 2-4 sentences]
Closes #N <!-- if an issue is linked; otherwise omit -->
Spec: `specs/SPEC-<ref>.md` <!-- if applicable -->
## Changes
- [Notable change, grouped by intent]
## Test plan
- [Command or manual step to verify, with expected result]
## Review notes
- [Debatable tradeoff, accepted debt, area worth a close look]
- Only list what helps the reviewer: no file-by-file inventory, the diff
already shows that.
Creation and follow-up
gh pr create --base main --title "…" --body "…" --label <labels>.- Give the URL to the requester and restate the circuit: green CI, then a
review on request (
/flux:review) and its human triage, before
merge. Never merge yourself.
- On merge: if a spec is linked, set its frontmatter to
status: implemented and update the specs/README.md index.
After creation: watch CI and fix autonomously
Do not stop at "PR opened". A PR with red CI is not delivered.
gh pr checks --watch --fail-fast (fall back to polling gh pr checks
if --watch is unavailable).- On failure:
gh run view <run-id> --log-failed, but don't dump it
whole into context. Grep it for the failing assertion or error line
first; pull more of that step's log only if the grep hit isn't enough
to diagnose the cause.
- Fix the cause on the branch (never by weakening the gate or the test),
let flux-gate validate locally, push. The checks re-run.
- Loop until green. After 3 failed attempts on the same error, stop and
report the diagnosis to the user instead of thrashing.
- When green: nothing reviews the PR on its own, and there is no CI job
to wait for. Tell the user the PR is ready and a review is one command
away (
/flux:review, run locally in a session). If you are driving
the full cycle (feature skill) and they ask for it now, run that flow
and chain into the triage flow of gh-address-comments in the same
session. Either way the triage itself is human: review comments are
never auto-addressed.
1---2name: gh-pr3description: Write and open the pull request for the current branch via the gh CLI, linked to its issue and spec. Use when the user asks to create/open/write a PR.4---56# Skill: gh-pr78## Purpose910Open a well-written PR for the current branch: a faithful summary of the11changes, links to the issue and spec, and a verifiable test plan.1213## Preconditions (check, fix if needed)14151. Current branch ≠ default branch. Otherwise, offer to create one16 (`feat/<ref>-<slug>` or `fix/<slug>`).172. Everything is committed and pushed (`git status`,18 `git push -u origin HEAD`). The flux-gate hook runs the gates on push:19 if it blocks, fix the failures first, never bypass it.203. Read `flux-config.yml`: `github.labels` = default PR labels.2122## Writing2324- **Title**: conventional commit format (`feat(candidates): add pipeline25 board`); it often becomes the squash-merge commit message.26- **Body**: build it from the actual diff (`git diff main...HEAD`), not27 from memory:2829```markdown30## Summary31[What the PR does and why, 2-4 sentences]3233Closes #N <!-- if an issue is linked; otherwise omit -->34Spec: `specs/SPEC-<ref>.md` <!-- if applicable -->3536## Changes37- [Notable change, grouped by intent]3839## Test plan40- [Command or manual step to verify, with expected result]4142## Review notes43- [Debatable tradeoff, accepted debt, area worth a close look]44```4546- Only list what helps the reviewer: no file-by-file inventory, the diff47 already shows that.4849## Creation and follow-up50511. `gh pr create --base main --title "…" --body "…" --label <labels>`.522. Give the URL to the requester and restate the circuit: green CI, then a53 review on request (`/flux:review`) and its human triage, before54 merge. Never merge yourself.553. On merge: if a spec is linked, set its frontmatter to56 `status: implemented` and update the `specs/README.md` index.5758## After creation: watch CI and fix autonomously5960Do not stop at "PR opened". A PR with red CI is not delivered.61621. `gh pr checks --watch --fail-fast` (fall back to polling `gh pr checks`63 if `--watch` is unavailable).642. On failure: `gh run view <run-id> --log-failed`, but don't dump it65 whole into context. Grep it for the failing assertion or error line66 first; pull more of that step's log only if the grep hit isn't enough67 to diagnose the cause.683. Fix the cause on the branch (never by weakening the gate or the test),69 let flux-gate validate locally, push. The checks re-run.704. Loop until green. After 3 failed attempts on the same error, stop and71 report the diagnosis to the user instead of thrashing.725. When green: nothing reviews the PR on its own, and there is no CI job73 to wait for. Tell the user the PR is ready and a review is one command74 away (`/flux:review`, run locally in a session). If you are driving75 the full cycle (feature skill) and they ask for it now, run that flow76 and chain into the triage flow of `gh-address-comments` in the same77 session. Either way the triage itself is human: review comments are78 never auto-addressed.
sbnet