# 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.
```bash
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:
```bash
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:
```bash
git fetch origin main
git merge origin/main --no-edit
```
If the merge **succeeds cleanly**, push the updated branch:
```bash
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:
```bash
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:
```bash
git diff origin/main...HEAD --name-only | grep decisions/
```
If non-trivial changes exist but no ADRs are found, add a warning block:
```markdown
> **⚠ 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
```markdown
<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
```bash
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