/pr
Open a pull request from current branch state.
Role
Engineer shipping clean, well-documented PRs.
Objective
Create a draft PR from current branch. Link to issue, explain what/why/how.
Latitude
-
Stage and commit any uncommitted changes with semantic message
-
Read linked issue from branch name or recent commits
-
Write PR body that explains decisions, not just changes
PR Body Requirements (MANDATORY)
Every PR body must contain all six sections. A PR missing any section is not ready.
Summary
What changed and why it matters. Not a diff recap — explain the significance. Link to the issue. State the problem this solves or the capability this adds.
Changes
Concise list of what was done. Reference key files/functions.
Acceptance Criteria
Copied or derived from the linked issue. Checkboxes.
Manual QA
Step-by-step instructions a reviewer can follow to verify the change works. Include: setup steps, exact commands, expected output, URLs to visit.
What Changed
Mermaid diagram showing the nature of the change. Selection:
| Change type | Diagram |
|---|---|
| New feature / component | graph TD of new components and their relationships |
| Bug fix | stateDiagram-v2 showing broken state → fixed state |
| Refactor | graph TD before vs. after (two diagrams, labeled Before/After) |
| Data model change | erDiagram of affected tables/relations |
| API change | sequenceDiagram of old vs. new call flow |
| Simple/internal change | Omit — don't force a diagram when it adds no signal |
Decision rule: If the change can be explained in one sentence with no branching or relationships → omit. Otherwise → include.
Load ~/.claude/skills/visualize/references/github-mermaid-patterns.md for annotated examples and GitHub gotchas.
Before / After
Show the state before and after this PR. MANDATORY for every PR.
Text: Describe the previous behavior/state and the new behavior/state.
Screenshots: Include before and after screenshots for any user-facing change
(UI, CLI output, error messages, dashboards). Use  / .
Skip screenshots ONLY when the change is purely internal (no visible output difference). When in doubt, screenshot.
Test Coverage
Pointers to specific test files and test functions that cover this change. Note any gaps: what ISN'T tested and why.
Workflow
-
Clean — Commit any uncommitted changes with semantic message
-
Context — Read linked issue, diff branch against main, identify relevant tests
-
Visual QA — If diff touches frontend files (app/ , components/ , *.css ), run /visual-qa . Fix any P0/P1 issues before opening PR. Capture screenshots for Before/After section.
-
Dogfood QA — Run /dogfood http://localhost:3000 (start dev server first if not running). Fix all P0/P1 issues found. Iterate until clean. Do not open a PR until this passes. Include dogfood summary (issues found, fixed) in PR body under Manual QA section.
-
Describe — Title from issue, body follows PR Body Requirements above (capture before state FIRST, before making changes if possible)
-
Before/After — Use screenshots from visual QA + dogfood steps. For non-UI changes, describe behavioral difference in text.
-
Open — gh pr create --draft --assignee phrazzld
-
Comment — Add context comment if notable decisions were made
-
Retro — If this PR closes a GitHub issue, append implementation feedback: /retro append --issue $ISSUE --predicted {effort_label} --actual {actual_effort}
--scope "{what_changed_from_spec}" --blocker "{blockers}" --pattern "{insight}"
This feeds the grooming feedback loop — /groom reads retro.md to calibrate future effort estimates and issue scoping.
Comment Style
Like a colleague leaving context for future-you:
-
Concise — No fluff
-
High-context — Reference files, functions, decisions
-
Useful — What's not obvious from the diff?
-
Human — Some wit welcome
Output
PR URL. Retro entry appended to .groom/retro.md (if issue-linked).