pr

When asked to create a pull request, follow these steps:

## Phase 1: Pre-flight checks

1. Run `git status`. If any of the following conditions apply, stop and report the errors:

   - There are unstaged changes
   - There are untracked files
   - The current branch is the default branch (`main`)

2. Check if this is a stacked PR:

   - Run `git merge-base main HEAD` to find the common ancestor with main
   - Run `git log --oneline <merge-base>..HEAD` to see commits since diverging from main
   - Check if any parent commits are on another feature branch (not main)
   - If so, run `gh pr list --head <parent-branch>` to check if that branch has an open PR
   - If a parent branch has an open PR, this is a **stacked PR**

3. Run `git log main..HEAD --oneline` to see the commit history.

4. Get the diff for the review:
   - If this is a **stacked PR**, run `git diff <parent-branch>...HEAD` to scope the diff to only this branch's changes.
   - Otherwise, run `git diff main...HEAD`.

## Phase 2: Automated PR review (parallel subagents)

**MANDATORY — DO NOT SKIP.** This phase must run before any PR is created, regardless of how "simple", "mechanical", or "well-tested" the changes appear. Subtle bugs (e.g., semantic mismatches in API migrations) hide in exactly the changes that seem safe to skip. The only exception is docs-only changes as described below.

Before creating the PR, analyze the diff to decide **which review subagents to launch**. Not every PR needs every reviewer.

### Triage: classify the change

Categorize each changed file, then pick subagents based on which categories are present. A file belongs to exactly one category — evaluate in this order (first match wins):

1. **docs**: `.md`, `.txt`, `CHANGELOG`, `LICENSE`, `docs/`, `.claude/`
2. **ci**: `.github/workflows/`, `.github/actions/` — these often contain shell scripts with non-trivial logic
3. **config**: `.json` (not `package.json`), `.yml`, `.yaml`, `.eslintrc*`, `.prettierrc*`, `tsconfig*`, `Dockerfile`, `.editorconfig`, `.gitignore`, `.gitattributes`, `.nvmrc`, `.yarnrc*`
4. **test**: files matching `*.test.ts`, `*.spec.ts`, or under `test/` directories
5. **code**: everything else (`.ts`, `.js`, `.mjs`, `.cjs`, `package.json`, etc.)

Then decide which subagents to launch:

- If **only docs** files changed: **skip the entire review phase** and go straight to Phase 3.
- Otherwise, select subagents based on which categories are present:
  - **ci** present → launch **Subagent 1 (Correctness)** (review shell logic, conditional expressions, job dependency chains)
  - **config** or **test** present → launch **Subagent 2 (Style)**
  - **test** present → also launch **Subagent 4 (Tests)**
  - **code** present → launch **Subagent 1 (Correctness)** and **Subagent 2 (Style)**
  - **code** present → also launch **Subagent 4 (Tests)**
  - **code** present and diff touches security-sensitive areas (network/HTTP, user input, auth, crypto, `eval`/`Function`, capability passing, `harden()`/SES) → also launch **Subagent 3 (Security)**

### Subagent 1: Correctness & Logic

Prompt the agent to:

- Review the diff for logical errors, off-by-one mistakes, race conditions, and incorrect assumptions
- Check that error handling is adequate at system boundaries
- Verify that new code paths are reachable and dead code hasn't been introduced
- Flag any behavior changes that aren't covered by tests

### Subagent 2: Style & Conventions

Prompt the agent to:

- Check adherence to the project's CLAUDE.md conventions (TypeScript types over interfaces, no `any`, no `enum`, kebab-case files, `@metamask/superstruct` for runtime types, options bags for 3+ args, `harden()` usage, etc.)
- Check test conventions (no "should", `toStrictEqual` for full objects, `it.each` for parameterized tests, concise verb-form titles)
- Flag unnecessary complexity, over-engineering, or missing `harden()` calls

### Subagent 3: Security & Performance

Prompt the agent to:

- Look for OWASP top-10 vulnerabilities (injection, XSS, etc.)
- Check for capability leaks in the ocap model (unhardened objects, leaked references)
- Identify performance issues (unnecessary allocations in hot paths, missing early returns, O(n^2) patterns)
- Verify that lockdown/SES compatibility isn't broken (no ambient authority, no forbidden globals)

### Subagent 4: Test Coverage

Prompt the agent to:

- Identify new or changed logic that lacks corresponding test coverage
- Check that edge cases and error paths are tested
- Verify tests are co-located correctly per project conventions
- Flag any test anti-patterns (global state, missing cleanup, overly broad mocks)

## Phase 3: Review summary

If the review phase was skipped (docs-only), proceed directly to Phase 4.

Otherwise, after all launched subagents complete:

1. Compile findings into a **Review Summary** with sections for each subagent that ran.
2. Classify each finding as one of:
   - **blocker** - Must fix before merging
   - **suggestion** - Should consider fixing
   - **nit** - Minor, optional improvement
3. If there are **blockers**, present them to the user and ask whether to:
   - Fix the blockers automatically, then re-review
   - Proceed with PR creation anyway
   - Abort
4. If there are no blockers, briefly summarize the findings and proceed.

## Phase 4: Create the PR

1. Run `gh pr create` to create a pull request. The PR body should include:

   - A brief narrative description of the PR
   - A summary of the changes (bullet points)
   - A brief description of how the code is tested (narrative, not a checklist)

   **If this is a stacked PR**, add `--draft` to create it as a draft PR.

2. Note the PR number from the created PR URL — it is needed for changelog entries. Proceed to Phase 5 before presenting results to the user.

## Phase 5: Update changelogs

**MANDATORY — DO NOT SKIP.** Analyze the diff and determine whether any changes are consumer-facing (i.e., affect the behavior or API of a published or private package).

- **If there are NO consumer-facing changes** (e.g., docs-only, CI, tooling, skill definitions, dev scripts): add the `no-changelog` label to the PR via `gh pr edit <number> --add-label no-changelog` and skip the rest of this phase.
- **If there ARE consumer-facing changes**: update changelogs as described below.

Read the instructions in [`docs/contributing/updating-changelogs.md`](../../../docs/contributing/updating-changelogs.md) and follow them **to the letter**. In particular:

- **Think from the consumer's perspective.** A changelog is not a git history. For each affected package, ask: "What changed for someone who depends on this package?" Describe changes in natural language; do not simply reuse commit messages.
- **Combine like changes.** If multiple commits contribute to a single logical change within one package, write one changelog entry — not one per commit.
- **Split disparate changes.** If one commit touches unrelated concerns in a single package, write separate entries.
- **Link the PR.** Use the PR number from Phase 4 in each entry (e.g. `([#123](https://github.com/.../pull/123))`).

Commit the changelog updates to the current branch with the message "docs: Update changelogs" and push.

## Done

Present the PR URL and any relevant information to the user. If a review was performed, include the review summary.