make-pr

Write a PR description a reviewer can trust at a glance. Output sections, in order:

1. Summary — what changed and why, in bullets.
2. What this PR deliberately does NOT do — explicit scope boundaries.
3. Test plan — the exact commands, executed, with real numbers.
4. Confidence Score: X/5 — from the executed, gated rubric in references/rubric.md, with a forced "what's keeping it below 5/5" line.
5. Important Files Changed — two-tier table (behavioural files up top, the rest collapsed).
6. Sequence Diagram — only when the change has a real runtime flow.

The score uses the same rubric pr-loop optimizes toward. Golden rule: never assert a gate result you did not run. A self-authored score is only credible because it is anchored to executed checks.

Inputs

• PR number / branch (optional): default to the PR for the current branch; if none exists, prepare to create one.
• --create / --update: force create-new vs edit-existing. Default: update if a PR exists for the branch, else create.

Procedure

0. Learn the repo's rules

for f in CLAUDE.md AGENTS.md GEMINI.md .github/pull_request_template.md; do
  [ -f "$f" ] && printf '\n=== %s ===\n' "$f" && cat "$f"
done

Honor what you find — especially commit/PR trailers and testing philosophy. If the repo forbids AI-authorship lines (e.g. "never credit AI", "no Co-Authored-By"), do not add any "Generated with…" or co-author trailer. When unsure, omit it. Note any "test the core, not prototype X" guidance — it feeds the context-aware Tests axis.

1. Establish the diff

BASE=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || git symbolic-ref --short refs/remotes/origin/HEAD | sed 's@^origin/@@' || echo main)
git fetch -q origin "$BASE" 2>/dev/null || true
git --no-pager diff --stat "origin/$BASE...HEAD"
git --no-pager diff --name-status "origin/$BASE...HEAD"

Note total files / insertions / deletions — they drive the two-tier table decision in §4.

2. Run the gates — execute, do not assert

Detect what the repo actually has, then run it. Capture real output (counts, pass/fail). Pick detection by ecosystem:

# Node / TS
[ -f package.json ] && jq -r '.scripts // {} | keys[]' package.json   # look for test, build, lint, typecheck
# Python
ls pytest.ini pyproject.toml setup.cfg tox.ini 2>/dev/null            # pytest? ruff? mypy?
# Go / Rust / Make
ls go.mod Cargo.toml Makefile 2>/dev/null

Run each gate that exists and record the exact command + result, e.g.:

pytest -q                 # → "16 passed in 4.2s"
tsc -b                    # → clean / errors
eslint .                  # → 0 problems / N problems

For each gate not configured, record N/A — skipped. Apply the rubric's caps (rubric.md §1): correctness gate red → score ≤ 2; hygiene gate red → score ≤ 3.

If you genuinely cannot run a gate this session (missing service, no credentials), write "not executed this session" — never imply it passed. An unrun gate does not raise the score.

3. Compute the score

Apply references/rubric.md exactly: gates first (caps), then the weakest-link minimum across the five judgment axes. Decide the binding axis (the lowest one) and the one-line "what would raise it". Do not round up out of optimism.

4. Author the body

Use this skeleton (drop any section that does not apply; keep the order):

## Summary

- <bullet: the core change and why>
- <bullet: notable mechanics or decisions>

## What this PR deliberately does NOT do

- <explicit out-of-scope boundary>

## Test plan

- [x] `<command>` → **<real result, e.g. 16 passed>**
- [x] `<command>` → **<result>**
- [ ] `<manual step deferred>` — <why>

<details open><summary><h3>Confidence Score: X/5</h3></summary>

<verdict — one or two sentences.>

**Binding axis: <axis>** — <why not higher>. To raise it: <concrete action>.

_Gates:_ tests `<result>` · build `<result>` · lint `<result>` · scope `<result>`.
</details>

### Important Files Changed

| File | Overview |
|------|----------|
| `<path>` | <what changed + one-line risk/assessment note> |

<details><summary>Other changed files (N)</summary>

| File | Overview |
|------|----------|
| `<path>` | <terse note — tests / config / docs, no behavioural risk> |

</details>

<details open><summary><h3>Sequence Diagram</h3></summary>

```mermaid
sequenceDiagram
    participant A as <real component/file name>
    participant B as <real component/file name>
    A->>B: <call>
    B-->>A: <result>
```
</details>

Section rules:

• Important Files Changed — two-tier. Behaviour-changing files in the top table (most-significant first); everything else (tests, config, docs, lockfiles, generated) in the collapsed <details>. Anything with real risk goes up top — never hide a behavioural change. Exclude pure-formatting/whitespace and lockfile churn from prose detail (list them in the collapsed tier only). Columns stay lean: File | Overview.
• Sequence Diagram — conditional, with fallback.
  • Multi-component runtime interaction (request/response, job, pipeline) → mermaid sequenceDiagram. Use real file/component names as participants; show the happy path plus the key error/branch.
  • Branching logic but no cross-component sequence → mermaid flowchart instead.
  • Neither (docs, config, pure refactor) → omit the section entirely. A contrived diagram erodes trust in the whole PR.

5. Create or update the PR

Write the body to a temp file to keep markdown/heredoc-safe, then:

# update existing
gh pr edit <NUMBER> --body-file /tmp/pr-body.md
# or create
gh pr create --base "$BASE" --title "<title>" --body-file /tmp/pr-body.md

Respect the repo's trailer policy from §0. Do not add an AI-authorship line unless the repo's conventions clearly permit it.

Output

Report to the user: the PR URL, the computed score with its binding axis, and which gates ran vs. were skipped — so the score's evidence basis is explicit.