notque/pr-workflow

PR Workflow Skill

Umbrella skill for the entire pull request lifecycle. Routes to the correct reference based on the PR task requested.

Routing

Detect the user's intent and load the appropriate reference file:

| Intent | Trigger phrases | Reference | |--------|----------------|-----------| | Sync (default) | "push", "create PR", "sync", "ship this" | ${CLAUDE_SKILL_DIR}/references/sync.md | | Pipeline | "submit PR", "full PR", "end-to-end PR", "open PR" | ${CLAUDE_SKILL_DIR}/references/pipeline.md | | Fix | "fix PR comments", "address review", "pr-fix", "resolve feedback" | ${CLAUDE_SKILL_DIR}/references/fix.md | | Status | "pr status", "branch status", "is my PR ready", "check CI" | ${CLAUDE_SKILL_DIR}/references/status.md | | Cleanup | "clean up branches", "delete merged branch", "prune" | ${CLAUDE_SKILL_DIR}/references/cleanup.md | | Feedback | "process PR feedback", "address reviews", "what did reviewers say" | ${CLAUDE_SKILL_DIR}/references/feedback.md | | Miner | "mine PRs", "extract review comments", "tribal knowledge", "reviewer patterns" | ${CLAUDE_SKILL_DIR}/references/miner.md | | Branch name | "generate branch name", "validate branch name", "name branch", "branch convention", "git branch name" | ${CLAUDE_SKILL_DIR}/references/branch-name.md | | CI check | "check CI", "CI status", "actions status", "did CI pass", "build status", "CI passed" | ${CLAUDE_SKILL_DIR}/references/ci-check.md | | Commit | "commit changes", "stage and commit", "commit my changes", "commit my files", "commit these" | ${CLAUDE_SKILL_DIR}/references/commit.md | | Codex review | "codex review", "second opinion", "code review codex", "gpt review", "cross-model review" | ${CLAUDE_SKILL_DIR}/references/codex-review.md | | Land | "land PR", "land the PR", "merge contributor PR", "rebase and merge PR" | ${CLAUDE_SKILL_DIR}/references/land-pr.md | | Body safety | any gh call writing or reading a PR/issue body | ${CLAUDE_SKILL_DIR}/references/gh-body-safety.md | | Changelog | "update changelog", "release notes", "curate changelog" | ${CLAUDE_SKILL_DIR}/references/changelog-curation.md | | Decision brief | "decision brief", "authorization tier", "ask the owner", "is it decision-ready" | ${CLAUDE_SKILL_DIR}/references/owner-decision-briefs.md |

Default action: When invoked with no arguments or ambiguous intent, load sync.md (the most common PR use case).

Reference Loading Table

| Signal | Load These Files | Why | |---|---|---| | "push", "create PR", "sync", "ship this" | sync.md | Sync (default) | | "submit PR", "full PR", "end-to-end PR", "open PR" | pipeline.md | Pipeline | | "fix PR comments", "address review", "pr-fix", "resolve feedback" | fix.md | Fix | | "pr status", "branch status", "is my PR ready", "check CI" | status.md | Status | | "clean up branches", "delete merged branch", "prune" | cleanup.md | Cleanup | | "process PR feedback", "address reviews", "what did reviewers say" | feedback.md | Feedback | | "mine PRs", "extract review comments", "tribal knowledge", "reviewer patterns" | miner.md | Miner | | "generate branch name", "validate branch name", "name branch", "branch convention", "git branch name" | branch-name.md | Branch name | | "check CI", "CI status", "actions status", "did CI pass", "build status", "CI passed" | ci-check.md | CI check | | "commit changes", "stage and commit", "commit my changes", "commit my files", "commit these" | commit.md | Commit | | "codex review", "second opinion", "code review codex", "gpt review", "cross-model review" | codex-review.md | Codex review | | "land PR", "land the PR", "merge contributor PR", "rebase and merge PR" | land-pr.md | Land | | any gh call writing or reading a PR/issue body | gh-body-safety.md | Body safety | | "update changelog", "release notes", "curate changelog" | changelog-curation.md | Changelog | | "decision brief", "authorization tier", "ask the owner", "is it decision-ready" | owner-decision-briefs.md | Decision brief |

Mandatory PR Body Structure

gh pr create --body "..." is how every agent in this toolkit opens PRs, and it bypasses .github/pull_request_template.md entirely — GitHub only applies that file to the web UI and to a bare gh pr create with no --body. So the structure must be reproduced in the --body string by hand.

Every agent-authored PR body uses the same three sections as .github/pull_request_template.md, in this order: Summary → Changes → Notes. This keeps PR bodies consistent across models (Opus, Sonnet, and every other harness produce the same shape).

Tests run as GitHub Actions, so the Checks tab is the test record. Let CI carry the proof: keep command output (ruff exit, pytest counts, gate traces, dogfood runs) out of the body. Pasting $ pytest → N passed duplicates the Checks tab and bloats the PR — leave it to CI.

Write for Density

Aim for high meaning per word: each line states one fact about the change, declaratively, so a reviewer understands it fast. Density is the target, not minimal length — a large change keeps the three sections and carries the detail it needs; it earns that length by packing each line with signal. Four rules carry the vibe:

1. One fact per line. Each Changes line reads verb + what + where; Summary states the goal and why. Plain words, high meaning.
2. Summary states the goal. 1-3 plain sentences or a few crisp bullets. Keep metrics to the single number that matters.
3. One line per change. When a change has many sub-items, state the shape and count ("add 21 PR-creation trigger phrases") and let the diff enumerate them. Keep rationale to the clause that earns its place.
4. Notes carries non-obvious signal — required when a trigger applies. Omit it for routine PRs and drop the section when nothing qualifies. Note it, one terse declarative line per point, when a reviewer cannot infer the signal from the diff: a non-obvious decision, a deliberate omission, a follow-up, a gotcha, a "supersedes #N". Note it too when a RISK/VERIFICATION trigger holds — manual verification was performed; part of the change sits outside CI coverage; migration/rollout ordering matters; a security-sensitive surface changed (e.g. Not covered by CI — terraform plan is manual). State each caveat as one fact and let CI carry command output. Skip what is always true (a PR can be reverted; CI runs the tests).

Worked example — the shape to emulate (#608-good vs #710-bad):

| Section | Dense (emulate, like #608) | Bloated (rewrite toward dense, the #710 shape) | |---------|-----------------|--------------------------------| | Summary | "Registers 3 hooks in settings.json; integrates pre-route.py into /do Phase 2 as a deterministic pre-filter." | One 5-sentence block stuffed with jargon and four metrics. | | Changes | "SKILL.md — add 21 PR-creation trigger phrases." | One bullet inlining all 21 phrases verbatim; another a 3-sentence rationale paragraph. | | Notes | "Not covered by CI — the Terraform plan is applied manually." or "Apply the column migration before deploying." (a required risk/verification caveat) — or omitted entirely when nothing qualifies | "Roll back by reverting the branch commits. Tests run in CI — see Checks." (always-true filler) plus a pasted pytest -v dump and a Scope & Risk wall. |

The dense column reads in seconds because each cell carries facts; the bloated column buries the same facts in volume (and re-states what the Checks tab already shows). Aim every body at the dense column.

Copy this canonical skeleton into --body:

## Summary
<!-- State the goal plainly: 1-3 sentences or a few crisp bullets, one fact per line. Name the ADR/issue if any. Keep metrics to the single number that matters. -->

## Changes
<!-- One line per change: verb + what + where. State shape and count for many sub-items; let the diff enumerate them. -->
- `path/or/area` — what changed

## Notes
<!-- Omit for routine PRs (drop the section when nothing qualifies). Note it, one terse declarative line per point, when a reviewer cannot infer the signal from the diff: a non-obvious decision, a deliberate omission, a follow-up, a gotcha, a "supersedes #N". Note it too when a RISK/VERIFICATION trigger holds — manual verification was performed; part of the change sits outside CI coverage; migration/rollout ordering matters; a security-sensitive surface changed (e.g. `Not covered by CI — terraform plan is manual`). Let CI carry command output. Skip what is always true (a PR can be reverted; CI runs the tests). -->

The sync (sync.md Step 5) and pipeline (pipeline.md Phase 5) references carry this same skeleton at their gh pr create call sites. When either path writes a --body, it uses this structure and the density rules above.

Instructions

1. Identify the user's PR task from their message
2. Load the matching reference file from the table above
3. Follow the instructions in that reference file exactly
4. When the task creates a PR, build the --body from the canonical three-section skeleton above (Summary / Changes / Notes), because --body bypasses the GitHub template file. Write the body via temp file + quoted heredoc + --body-file per ${CLAUDE_SKILL_DIR}/references/gh-body-safety.md. Tests run in CI — the Checks tab is the test record, so keep command output out of the body