Skip to main content
Good PRs are easy to review: reviewers should quickly know the intent, verify behavior, and land changes safely. This guide covers concise, high-signal submissions for human and LLM review.

​
What makes a good PR

  • Explain the problem, why it matters, and the change.
  • Keep changes focused. Avoid broad refactors.
  • Summarize user-visible/config/default changes.
  • List test coverage, skips, and reasons.
  • Add evidence: logs, screenshots, or recordings (UI/UX).
  • Code word: put “lobster-biscuit” in the PR description if you read this guide.
  • Run/fix relevant pnpm commands before creating PR.
  • Search codebase and GitHub for related functionality/issues/fixes.
  • Base claims on evidence or observation.
  • Good title: verb + scope + outcome (e.g., Docs: add PR and issue templates).
Be concise; concise review > grammar. Omit any non-applicable sections.

​
Baseline validation commands (run/fix failures for your change)

  • pnpm lint
  • pnpm check
  • pnpm build
  • pnpm test
  • Protocol changes: pnpm protocol:check

​
Progressive disclosure

  • Top: summary/intent
  • Next: changes/risks
  • Next: test/verification
  • Last: implementation/evidence

​
Common PR types: specifics

  • Fix: Add repro, root cause, verification.
  • Feature: Add use cases, behavior/demos/screenshots (UI).
  • Refactor: State “no behavior change”, list what moved/simplified.
  • Chore: State why (e.g., build time, CI, dependencies).
  • Docs: Before/after context, link updated page, run pnpm format.
  • Test: What gap is covered; how it prevents regressions.
  • Perf: Add before/after metrics, and how measured.
  • UX/UI: Screenshots/video, note accessibility impact.
  • Infra/Build: Environments/validation.
  • Security: Summarize risk, repro, verification, no sensitive data. Grounded claims only.

​
Checklist

  • Clear problem/intent
  • Focused scope
  • List behavior changes
  • List and result of tests
  • Manual test steps (when applicable)
  • No secrets/private data
  • Evidence-based

​
General PR Template

#### Summary

#### Behavior Changes

#### Codebase and GitHub Search

#### Tests

#### Manual Testing (omit if N/A)

### Prerequisites

-

### Steps

1.
2.

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort (self-reported):
- Agent notes (optional, cite evidence):

​
PR Type templates (replace with your type)

​
Fix

#### Summary

#### Repro Steps

#### Root Cause

#### Behavior Changes

#### Tests

#### Manual Testing (omit if N/A)

### Prerequisites

-

### Steps

1.
2.

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort:
- Agent notes:

​
Feature

#### Summary

#### Use Cases

#### Behavior Changes

#### Existing Functionality Check

- [ ] I searched the codebase for existing functionality.
      Searches performed (1-3 bullets):
  -
  -

#### Tests

#### Manual Testing (omit if N/A)

### Prerequisites

-

### Steps

1.
2.

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort:
- Agent notes:

​
Refactor

#### Summary

#### Scope

#### No Behavior Change Statement

#### Tests

#### Manual Testing (omit if N/A)

### Prerequisites

-

### Steps

1.
2.

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort:
- Agent notes:

​
Chore/Maintenance

#### Summary

#### Why This Matters

#### Tests

#### Manual Testing (omit if N/A)

### Prerequisites

-

### Steps

1.
2.

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort:
- Agent notes:

​
Docs

#### Summary

#### Pages Updated

#### Before/After

#### Formatting

pnpm format

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort:
- Agent notes:

​
Test

#### Summary

#### Gap Covered

#### Tests

#### Manual Testing (omit if N/A)

### Prerequisites

-

### Steps

1.
2.

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort:
- Agent notes:

​
Perf

#### Summary

#### Baseline

#### After

#### Measurement Method

#### Tests

#### Manual Testing (omit if N/A)

### Prerequisites

-

### Steps

1.
2.

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort:
- Agent notes:

​
UX/UI

#### Summary

#### Screenshots or Video

#### Accessibility Impact

#### Tests

#### Manual Testing

### Prerequisites

-

### Steps

1.
2. **Sign-Off**

- Models used:
- Submitter effort:
- Agent notes:

​
Infra/Build

#### Summary

#### Environments Affected

#### Validation Steps

#### Manual Testing (omit if N/A)

### Prerequisites

-

### Steps

1.
2.

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort:
- Agent notes:

​
Security

#### Summary

#### Risk Summary

#### Repro Steps

#### Mitigation or Fix

#### Verification

#### Tests

#### Manual Testing (omit if N/A)

### Prerequisites

-

### Steps

1.
2.

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort:
- Agent notes: