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:

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

Reference Loading Table

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):

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. Tests run in CI — the Checks tab is the test record, so keep command output out of the body