denolfe/dotfiles/pr

PR

Dispatch on the first argument:

• create → see Create below
• draft → same as Create but create a draft PR instead of a regular PR
• update → see Update below
• preview → see Preview below
• No argument or unknown → check if a PR exists for the current branch. If yes, run Update. If no, run Create.

An optional base=<branch> argument (any position) sets the target branch. If omitted, default to the repo's default branch. Pass via --base <branch> to gh pr create. Ignored for update and preview.

Before drafting any PR body (create/draft/update/preview): Read [references/content-guidelines.md](references/content-guidelines.md), [references/blocks.md](references/blocks.md), AND [references/visuals.md](references/visuals.md) in full. Do not draft from memory.

Classify

Run this first, before selecting blocks. Classify the change on two axes:

• TYPE (fix vs feature) — infer from Conventional Commit prefixes on the branch commits plus diff shape. fix:/revert: lean fix; feat: leans feature.
• COMPLEXITY (simple vs complex) — infer from files touched, diff size, and whether new architecture or a changed control/data flow is introduced.

Then:

1. State the result in one line, e.g. Detected: feature + complex.
2. Ask the user ONLY when signals conflict: mixed fix/feat commits, or a diff on the simple/complex borderline. Otherwise proceed.

Template

The body is assembled from the block library, not a single fixed template.

1. Take the classification's quadrant and pick the matching profile in references/blocks.md.
2. Add or drop the profile's ○ blocks using the include-when rules there.
3. Emit blocks in the order listed in the block library.
4. Build Overview Visual and Overall Flow from the forms in references/visuals.md. On Update, check kept visuals against those forms too.

Do not add sections outside the block library. Keep all language succinct and concise.

Pre-Apply Check

Before gh pr create, gh pr edit, or printing a Preview body, verify the drafted body:

• Every ## heading appears in the block library in references/blocks.md (no ## Test plan, ## Testing, ## Test coverage, ## Summary, or other ad-hoc headings).
• No line numbers referenced.
• Visuals are fenced markdown blocks only. No HTML files, local paths to artifacts, or images.
• No banned wording from references/content-guidelines.md (AI vocab, hedging, filler, chatbot artifacts).
• Sentence structure (per references/content-guidelines.md): scan all prose. Flag any sentence that chains what changed + mechanism + consequence with which/so/and, or leads with mechanism instead of the change. Split flagged sentences into what-then-why. Additionally, Changes sub-bullets over ~2 sentences / ~25 words (the cap in references/blocks.md) split into two bullets.
• Jargon (per references/content-guidelines.md "Glossing Jargon"): every term of art carries a one-clause appositive gloss at first use. Flag any glossed term expanded into a worked example (cut to the gloss) or re-taught on a later mention.
• No em dashes (—) anywhere in the body, including link/label separators. Grep the drafted body for —; if any appear, replace with a colon, comma, parentheses, or separate sentence before applying.
• Last line of the body is exactly 🤖 Written with AI, appearing once. On Update, do not duplicate a footer already in the existing body.

If any check fails, revise before applying. Do not ship a body you haven't checked.

Applying the Body

For gh pr create and gh pr edit, always use --body-file with mktemp. Never --body (its subshell mangles backticks and $). No exceptions — inconsistency invites the next agent to rationalize their way back to --body.

tmp=$(mktemp -t pr-body.XXXXXX) && trap 'rm -f "$tmp"' EXIT && cat > "$tmp" <<'EOF' && gh pr create --body-file "$tmp" [flags]
[body]
EOF

Run in a single Bash call — the trap only protects the shell it's set in.

Create / Draft

• Inspect branch state and commit history (including git log --oneline -- <changed-files> for convention patterns).
• Generate title
• Conventional Commits: <type>(<scope>)?<!>?: <title>. Title starts lowercase. No trailing period. Omit scope when no single area dominates.
• Synthesize from branch commits
• ≤72 chars
• Should describe the change, not the symptom or task. Focus on what an affected user would interpret, not the exact code change.
• Run Classify above, then write the PR body per Template (profile + include-when rules).
• Create the PR per Applying the Body above (add --draft for draft PRs).
• Say "PR Created: [title] [PR URL]".

Update

<HARD-GATE> STOP before any gh pr edit call. Run git status -b --porcelain=v2 (or check ahead/behind from git status). If the branch is ahead of origin by ≥1 commit, you MUST stop and ask the user: "Branch is N commits ahead of origin. Push before updating the PR body?"

• Yes, push then update body
• No, update body only (description may reference commits not yet on remote)

This is a correctness gate, not etiquette: if you skip it, the body will describe commits the reviewer can't see. Skipping is a violation even if the user previously approved unrelated unpushed commits. </HARD-GATE>

Steps:

1. Find the existing PR for the current branch. If none exists, tell the user to run /pr create instead.
2. Run the HARD-GATE check above. Resolve before continuing.
3. Inspect current branch state and any new design/plan docs since the PR was opened.
4. Run Classify above, then regenerate the PR body per Template (profile + include-when rules). Preserve existing intent where still accurate; revise drifted sections.
5. Apply the new body via gh pr edit per Applying the Body above.
6. Show a diff of the old vs new body, highlighting changes.
7. Say "PR Updated: [PR URL]".

Scope: body only. Do not change title or draft state unless the user asks.

Red flags (rationalizations to reject)

Preview

Generate the PR body and print it inline without creating, updating, or pushing anything.

• Inspect branch state (same as Create).
• Print a preview summary first, then the body. The summary is a fixed set of key/value lines so it's scannable, not prose:

`` **Title:** <generated title> **Detected:** <type> + <complexity> **Blocks:** <comma-separated blocks included, in emit order> **Dropped:** <comma-separated ○ blocks omitted + one-word reason each, or "none"> **Status:** Preview only: nothing created or pushed ``

• After the summary, output the PR body.
• Close with a one-line next step, e.g. "Run /pr create to open it."
• Do NOT write to any file.
• Do NOT run gh pr create, gh pr edit, git push, or any remote-mutating command.