| name | pr |
| description | Use when the user asks to create or update a pull request for the current branch. |
Open a reviewable PR/MR for the current branch. The reviewer arrives cold — not a teammate who lived through the work, but someone handed an agent's output. The body is the only bridge between the agent's context and what the human needs to decide.
Multi-repo work is one PR per repo. cd into each repo root before the create command — git CLIs infer the remote project from cwd, not from arguments. Cross-reference paired PRs in the body.
Conventional commits
!cat ~/.claude/skills/conventional-commits.md
CLI invocation
--fill conflicts with explicit title/body in both gh and glab.
| Title | Body | Create | Cleanup flag |
|---|
gh | --title | --body | gh pr create | --delete-branch |
glab | --title | --description | glab mr create | --remove-source-branch |
Pass the cleanup flag so the source branch is removed on merge.
Updating an existing PR: gh pr edit --body / glab mr update --description take the new body and overwrite — re-render from current truth, don't fetch-and-concat.
PR body
No placeholders, no filler — a ## Summary with [Description of changes] is worse than no Summary at all.
- Task — issue link or one-line of what was asked.
- Summary — what + why. Approach chosen and why over alternatives: "X over Y because Z." 2–4 lines.
- Focus — one line right under Summary: the single place the reviewer's attention is most load-bearing. The 15-second "look here" pointer; detailed judgment calls live in Human Review.
- Changes — prefer inline diff annotations for per-hunk WHY. Body list only when the change spans many files/areas and the grouping itself aids navigation — a change list, not a file list. Else skip; don't restate the diff.
- Self-Review —
[x] lines only, each naming its witness (test output, gate, diff hunk). Every claim must trace to the diff or pasted command output — an unsubstantiated "phantom" claim is worse than omitting it (sharply lowers merge rate, slows time-to-merge). Drop unchecked [ ]; "didn't verify" is noise — state the gap in Human Review.
- Human Review — specific things where human judgment is load-bearing.
- Architecture (when warranted, see below) — always the last section, after Human Review.
Before/after diagram
When the PR reshapes data flow, control flow, ownership, or sync boundaries — anything where the reviewer has to hold "old shape" and "new shape" in their head to judge the diff — embed a before/after Mermaid as a ## Architecture block at the bottom of the PR body, after ## Human Review. Not in ## Summary — the diagram is reference material reviewers scroll to, not the lede. GitLab and GitHub both render ```mermaid fences inline; no images, no Kroki.
Stacked TB layout — BEFORE on top, AFTER below. Outer flowchart TB, each subgraph direction TB, force ordering with an invisible BEFORE ~~~ AFTER link between the subgraph IDs themselves (not inner nodes — a node-level cross-subgraph edge collapses internal direction TB back to horizontal under the dagre renderer):
```mermaid
flowchart TB
subgraph BEFORE["BEFORE — <one-line label>"]
direction TB
B_x["..."]
end
subgraph AFTER["AFTER — <one-line label>"]
direction TB
A_x["..."]
end
BEFORE ~~~ AFTER
```
Side-by-side LR is unreliable on the dagre renderer GitLab/GitHub ship: any cross-subgraph edge (including the ordering hack) flips internal direction TB to horizontal. Stack instead.
Skip the diagram for pure refactors, bugfixes, dep bumps, copy changes — anything where the shape didn't move.
Template
$(cat <<'EOF'
## Task
## Summary
**Focus:**
## Changes
<!-- Only for many-file spans where grouping aids navigation. Else annotate the diff inline and delete this section. -->
-
## Self-Review
- [x]
## Human Review
- [ ]
## Architecture
<!-- Only when the PR reshapes data/control flow. Otherwise delete this section. -->
EOF
)
