pr

Pull Request Command

You are creating a GitHub Pull Request for the current branch with an AI-generated summary that highlights non-trivial changes for manual review.

Core Principle

Categorize every change as trivial or non-trivial so reviewers can focus their attention where it matters most.

Workflow

When the user invokes /pr:

1. Gather Context

First sync the fresh upstream ref without touching the local main branch: git fetch origin main.

Then run in parallel:

• git branch --show-current
• git log origin/main..HEAD --oneline
• git diff origin/main...HEAD
• git status
• git log origin/main..HEAD --format="%s%n%n%b"

If the branch is main, stop. If no commits ahead of origin/main, stop. If there are uncommitted changes, invoke /commit first.

2. Pre-flight CI checks

Run all four CI jobs locally in sequence. Stop immediately and report the failure if any step exits non-zero — do not open the PR.

npm run standard
npm run jsdoclint
npm test
npm run build && npm run typecheck

Report format on failure:

"Pre-flight failed: <step name> — <first error line>. Fix the issue and run /pr again."

3. Code Health Check

Get the list of .js files changed in this branch:

git diff origin/main...HEAD --name-only | grep '\.js$'

For each changed .js file, call the CodeScene code_health_score tool. If any file scores below 10.0:

1. Call code_health_review on that file for detailed guidance.
2. Fix the identified code smells following the MCP server's guidance.
3. Re-run npm run standard && npm test to confirm nothing broke.
4. Repeat until the score reaches 10.0, or document in the PR body why a remaining smell is out of scope for this change (e.g., a god file that can't be split without a major refactor).

If no .js files were changed, skip this step.

5. Sync with Main

Before opening the PR, merge the latest main into the current branch to eliminate post-open merge conflicts.

Run in sequence:

git fetch origin main
git merge origin/main --no-edit

If the merge succeeds cleanly, push the updated branch:

git push -u origin <current-branch>

If the merge fails with conflicts:

1. Run git status to list conflicting files.
2. Resolve each conflict automatically only when the resolution is unambiguous (e.g., the branch added a new file that main never touched).
3. If any conflict is ambiguous, abort the merge (git merge --abort), report the conflicting files to the user, and stop — do not proceed to PR creation.
4. After resolving, run npm run standard && npm test to confirm the merge didn't break anything, then git commit --no-edit and push.

6. Detect the Issue Number

Search in this order, stopping at the first match:

1. Branch name — patterns: ^(\d+)-, ^claude/build-(\d+)-, ^claude/(\d+)-
2. Commit messages — git log origin/main..HEAD --format=%B | grep -oE '#[0-9]+'
3. Plan frontmatter — look for github_issue: <number>

If no issue detected, skip the closing keyword. Do not invent one.

Verify the issue is open before adding the keyword:

gh issue view <number> --json number,state -q '.state' 2>/dev/null

Skip if CLOSED or lookup fails.

7. Analyze Changes

Categorize every change:

Non-trivial (warrant manual review):

• New distributions or statistical methods
• Changed PDF/CDF/quantile formulas
• New special functions or algorithms
• Behavioral changes (different return values, changed parameter constraints)
• New public API surface
• Dependency changes

Trivial (mechanical/low-risk):

• Formatting, whitespace, line reordering
• Method/function reordering within a file
• Renames with no logic change
• Import reordering or cleanup
• Docstring/comment additions only

8. ADR Gate (non-trivial PRs only)

Check for ADR references in the diff and commits:

git diff origin/main...HEAD --name-only | grep decisions/

If non-trivial changes exist but no ADRs are found, add a warning block:

> **⚠ Missing ADR**: This PR contains non-trivial changes but no Architecture Decision Record was found.
> Consider adding one at `decisions/` to document the design rationale.
> See `decisions/0000-template.md` for the format.

9. Generate PR Title

• Concise (under 70 characters), imperative mood
• e.g., "Add LogNormal distribution", "Fix CDF for discrete distributions"

10. Generate PR Body

<If an issue was detected:>
Closes #<issue-number>

<If ADR warning needed, insert it here>

## Summary
- <1-3 bullet points describing what this PR does and why>

## Design decisions
<If ADRs exist:>
- [ADR-NNNN: <title>](decisions/NNNN-slug.md) — <one-line summary>

<If no ADRs and no non-trivial changes, omit this section.>

## Non-trivial changes
<List them:>
- **`<file path>`**: <Description of what changed and why it matters>

<If no non-trivial changes:>
_No non-trivial changes — this PR is purely mechanical._

## Comprehension checklist
- [ ] I can explain what this code does without reading line-by-line
- [ ] I understand *why* this approach was chosen over alternatives
- [ ] WHY comments are present where the logic is non-obvious
- [ ] Tests verify observable behavior, not internal state
- [ ] A developer encountering this code in 6 months could understand it

<details>
<summary>Trivial changes</summary>

- **`<file path>`**: <Brief description>

</details>

---
*Generated with [Claude Code](https://claude.ai/code)*

11. Create the PR

gh pr create --title "<title>" --body "$(cat <<'EOF'
<body content>
EOF
)"

12. Watch the PR (CI + reviews)

Immediately after the PR is created, subscribe to its activity so CI failures and review comments are handled without the user having to ask:

subscribe_pr_activity(<pr-number>)

Availability: subscribe_pr_activity is provided by the remote-execution / GitHub webhook integration. If the tool is unavailable (e.g. a purely local gh session), skip this step and tell the user the PR can't be auto-watched here.

After subscribing, end the turn — do not poll with sleep or repeated status checks. PR events arrive as <github-webhook-activity> messages that wake the session. When one arrives, investigate it and follow this loop:

• CI check failed → reproduce locally, diagnose the root cause, push the fix, and update a short status checklist. Re-kick on each failure until green; the green status IS the deliverable, not a no-op to skip. Reply only when it resolves the task or raises a question.
• Review comment → if the fix is unambiguous and not architecturally significant, apply and push it. If there is any ambiguity (a comment open to interpretation, or a change touching something significant), use AskUserQuestion to confirm before acting.
• Duplicate / no-action-needed event → skip silently.
• Merge conflict reported → fetch the base branch, merge it in, resolve conflicts, re-run npm run standard && npm test, and push.

Stop watching the moment the user asks — call unsubscribe_pr_activity(<pr-number>) and push no further changes to that PR.

13. Report

"PR created: <URL>

Closes: #<issue> (or "None") Non-trivial changes: <count> (or "None") Watching: subscribed to PR activity — I'll auto-fix failing CI and respond to review comments as they arrive (or "not available in this environment")."

Rules

DO:

• Read the FULL diff before categorizing
• Always include Closes #N when an issue is detectable
• Be specific about what changed in non-trivial items
• Subscribe to PR activity after creation and follow through on CI/review events
• Escalate ambiguous review comments via AskUserQuestion before acting

DO NOT:

• Create a PR if on main
• Invent an issue number
• Add Closes #N for an already-closed issue
• Poll for CI/review status with sleep or repeated checks — react to webhook events instead
• Keep pushing to a PR after the user asks you to stop watching it