dakdevs/pr-this

PR This

Create or update a well-crafted draft PR from the current branch against main.

Behavior

Idempotent. Every invocation re-assesses the full diff against the base branch from scratch and builds a completely fresh title and body. If a PR already exists for the current branch it updates it; otherwise it creates a new one. No special flags needed - just run /pr-this again whenever the branch changes.

CRITICAL: When updating an existing PR, you MUST NOT read or reference the old PR title or body. Do NOT run gh pr view --json body or similar. The old description is dead - it reflects a previous state of the branch and will contaminate your output. Derive everything exclusively from the current git diff main...HEAD. Every section (Summary, What, Why, Diagram) must be written from scratch based solely on what the diff shows right now.

Workflow

0. Stage and commit all changes

Before creating/updating the PR, ensure everything is committed.

1. Run git status to see all untracked and modified files.
2. Review the list. Questionable files - files that might not belong in the repo (e.g., .env, credentials, large binaries, editor configs, OS files, build artifacts) - should be flagged. Use the AskUserQuestion tool to ask the user whether to include each questionable file. List them all in a single question.
3. Stage everything the user approved (or everything if nothing was questionable):

   git add <files...>
   

4. Commit with a descriptive message summarizing all uncommitted work:

   git commit -m "$(cat <<'EOF'
   <message>
   
   Co-Authored-By: Claude Opus 4.6 <[email protected]>
   EOF
   )"
   

5. If there are no uncommitted changes, skip this step and proceed.

1. Gather context

Run in parallel:

git log --oneline main..HEAD           # all commits on this branch
git diff --stat main...HEAD            # file-level summary
git diff main...HEAD                   # full diff
gh repo view --json nameWithOwner -q .nameWithOwner  # org/repo for links
git rev-parse HEAD                     # SHA for permalinks
git log main..HEAD --format="%s"       # commit messages for title conventions

Also read recent merged PR titles to match repo conventions:

gh pr list --state merged --limit 5 --json title -q '.[].title'

2. Clarify intent

Before analyzing, use AskUserQuestion to ask the user about the motivation and goals behind the changes. Ask concisely - e.g., "What's the main goal of this PR? Any specific wins or context I should highlight?" Use their answer to inform the Summary and Why sections. If the branch name and commits already make the intent crystal clear, you may skip this step.

3. Analyze changes

From the diff, commit history, and user's stated intent, identify:

• What changed (files, modules, functions)
• Why it changed (the motivation - from user's answer, commits, branch name, code context)
• Who benefits from this change and how (see "Who this helps" guidance below)
• Notable areas reviewers should look at closely

4. Build the PR title

Match the repo's existing commit/PR title conventions (e.g., conventional commits feat:, fix:, or freeform). Keep it under 70 chars.

5. Build the PR body

Use this structure:

## Summary

1-3 sentences. Plain English - no jargon, no code references, no file names.
Analyze the diff and state objectively what this PR achieves. Frame wins in
terms of concrete outcomes: product improvements, developer experience gains,
performance or speed improvements, new capabilities unlocked, reliability or
correctness increases, reduced complexity, etc. This should read like a
confident release note - what got better and why it matters. If the PR does
multiple things, cover all of them. Must be a strong, quick-read
representation that anyone (engineer or not) immediately understands the value of.
If and only if the scope genuinely can't fit in 3 sentences, switch to bullet
points - one per win. Keep each bullet to one sentence.

## What

1-3 bullet points. Each should be one sentence max. Link to specific code lines
when it compresses context better than describing. Use GitHub permalink format:
`https://github.com/{org}/{repo}/blob/{sha}/{path}#L{start}-L{end}`

## Why

1-2 sentences on motivation. What problem does this solve or what does it enable?

## Who this helps

Identify the real people who benefit from this change and say specifically how.
Think honestly about this - don't inflate the impact or reach for vague claims.

**Customer:** Name the actual audience - end users, other engineers on the team,
ops/SRE, the author's future self, a specific downstream service's consumers, etc.
Be specific. "Users" is almost never the right answer - say which users and in
what context. If the change is pure internal cleanup that only helps the next
person who touches this code, say that honestly.

**Impact:** 1-2 sentences on what concretely gets better for them. Not what the
code does differently - what the *person* experiences differently. Faster page
loads they'll notice? Fewer false alerts waking them up? A confusing API they
no longer have to work around? An error message that now actually tells them
what went wrong? If the impact is indirect or delayed (e.g., "this unblocks X
which will eventually let us do Y"), say so - don't pretend the end user feels
it today if they don't.

If multiple groups benefit, list them separately. If the honest answer is "this
mostly helps us maintain the codebase" - that's a valid customer and a real win,
just say it plainly.

## Diagram

<mermaid diagram - see below>

## Notes for reviewers

Optional. Only include if there are genuinely tricky areas, known limitations,
or decisions worth calling out. Skip this section entirely if there's nothing
non-obvious.

Tone: casual, professional, direct. No filler. Write like you're talking to a senior engineer over coffee - they don't need hand-holding, just the signal.

HARD REQUIREMENT: NEVER use emdashes anywhere in PR titles, bodies, commit messages, or any output. Use regular dashes (-) or rewrite the sentence instead.

Never include any AI attribution anywhere - no "Generated with Claude Code", no "Generated by Claude", no "Co-authored by AI", no bot footers, nothing. Not in the PR title, body, or commit messages created in step 7.

Code links: Use [descriptive text](permalink) whenever pointing at a specific function, struct, or block is clearer than explaining it in prose. Build permalinks from the SHA and file paths gathered in step 1.

6. Mermaid diagram

Always use Before / After diagrams. Every PR diagram section must contain two separate mermaid diagrams showing the system before and after the change. This is the default and only format. If the PR is a one-line config change or a simple rename where a diagram adds no value, skip the ## Diagram section entirely - but if you include diagrams, they must be before/after.

Ask yourself before adding diagrams: "Does this help a reviewer understand the PR faster than reading the bullet points?" If no, don't include them.

Choosing the right diagram type

Pick the type that best communicates the nature of the change:

• flowchart - control flow, request paths, pipelines, decision trees
• sequenceDiagram - temporal interactions between services/components (who calls whom, in what order)
• classDiagram - struct/type relationships, module boundaries, inheritance
• graph - dependency or data flow between modules

Both diagrams should use the same diagram type for easy comparison.

What to show

The diagrams should tell a specific story about the PR:

• Show the relevant slice of the system, not the entire architecture. Only include nodes/edges that are touched by the PR or that provide necessary context for understanding what changed.
• Label edges with what flows through them (data types, event names, HTTP methods) - not just arrows connecting boxes.
• Use real names from the code (function names, service names, struct names) so the diagram maps directly to the diff.
• Keep it compact. If a diagram has more than ~12 nodes, you're showing too much. Zoom in on the interesting part.

Color coding (After diagram only)

The "Before" diagram should be plain (no color) - it represents the old state.

The "After" diagram uses color to highlight what's new or changed. Colors must work in both GitHub light and dark mode - use medium-tone fills with explicit white text (color:#fff):

style NodeName fill:#2ea043,stroke:#3fb950,color:#fff  %% added (green)
style NodeName fill:#d29922,stroke:#e3b341,color:#fff  %% changed (amber)
style NodeName fill:#388bfd,stroke:#58a6ff,color:#fff  %% unchanged context (blue, use sparingly)

Include a legend at the bottom of the After diagram:

subgraph Legend
  direction LR
  added[Added]
  changed[Changed]
  style added fill:#2ea043,stroke:#3fb950,color:#fff
  style changed fill:#d29922,stroke:#e3b341,color:#fff
end

Format

Always use this format:

### Before

<1 sentence caption explaining what the reviewer is looking at>

```mermaid
<diagram showing the old structure - NO color coding, all nodes neutral>
```

### After

<1 sentence caption explaining what changed>

```mermaid
<diagram showing the new structure - use green for added, amber for changed>
```

Rules:

• Each diagram must be self-contained and independently readable. A reviewer should understand each one without cross-referencing the other.
• Use the same node IDs for components that exist in both diagrams so the reviewer can visually map what moved or changed.
• Both diagrams must have a brief caption (1 sentence) above them.

Syntax validation

Before including the diagram in the PR body, double-check for common mermaid syntax errors:

• Subgraph names must NOT be quoted (use subgraph My Name, not subgraph "My Name")
• Node IDs cannot contain spaces or special characters
• Arrow syntax must be valid (-->, -.->, ==>)
• Style declarations must reference existing node IDs
• Nested subgraphs must be properly closed with end

7. Push and create or update the PR

7a. Push the branch

git push -u origin HEAD

7b. Check for an existing PR

Only fetch the PR number and URL - nothing else. Do NOT fetch the old title or body.

gh pr view --json number,url 2>/dev/null

If a PR already exists, update it. If not, create one.

If no PR exists - create

Default is --draft. If the user said "do not draft", omit --draft.

gh pr create --base main --draft --title "<title>" --body "$(cat <<'EOF'
<body>
EOF
)"

If a PR already exists - update

IMPORTANT: The title and body you pass here MUST be built entirely from the current diff (steps 1-6). Do NOT read the old PR body. Do NOT carry forward any content from a previous description. Do NOT try to "merge" old and new content. Treat this as if you are writing the PR description for the first time - because the branch has changed, the old description is stale and wrong.

gh pr edit <number> --title "<title>" --body "$(cat <<'EOF'
<body>
EOF
)"

Print the PR URL when done.