Reference

Pull Request Template For AI-Assisted Delivery

A markdown template for smaller, more reviewable, higher-trust change

A reusable PR template shaped around the ideas in the verification post: narrow scope, explicit guarantees, evidence, and reviewability.

Why This Exists

When code generation gets cheaper, the real bottleneck becomes review, verification, and integration. This template is deliberately biased toward smaller, clearer pull requests that are easy to understand and safe to merge.

How To Use It

  • Keep the PR scope narrow enough that one reviewer can understand it quickly.
  • Prefer separate PRs for coverage, refactor, and behavior change when possible.
  • Make guarantees explicit instead of forcing the reviewer to infer them from the diff.
  • Do not treat every section as mandatory theatre; use judgment, but keep intent obvious.

Markdown Template

## Summary

Short description of the change in 2 to 4 sentences.

## Change Type

- [ ] Tests / coverage only
- [ ] Pure refactor
- [ ] Small behavior change
- [ ] New feature increment
- [ ] High-risk stateful / distributed change

## Risk Level

- 🟢 Low: cosmetic or local change
- 🟠 Medium: logic or behavior change with bounded impact
- 🔴 High: stateful, distributed, concurrency, recovery, or integration-sensitive change

Selected risk level: ...

## Why This PR Exists

- What pain or need does this PR address?
- Why is this the right incremental step now?

## What Changed

- ...
- ...
- ...

## What Must Remain True

- ...
- ...
- ...

Examples:
- ordering is preserved
- behavior is unchanged outside the named boundary
- no event loss / duplication is introduced
- public API contract remains the same

## Evidence

- Tests added / updated:
  - ...
- Static analysis / checks:
  - ...
- Property-based tests / invariants:
  - ...
- Manual verification:
  - ...

## Review Guidance

- Review this first:
  - ...
- Reviewers should focus on:
  - ...
- Reviewers do not need to re-check:
  - ...

## Deployment / Rollback

- Rollout notes:
  - ...
- Rollback path:
  - ...

## Follow-Up PRs

- ...
- ...

Two Useful Patterns

  • Tests first, refactor second: one PR increases coverage, the next changes structure while tests stay fixed.
  • Feature in steps: land boundaries, flags, and compatibility scaffolding before the behavioral change itself.

Why This Helps

The template is not trying to make PRs look polished. It is trying to make them faster to review, easier to trust, and cheaper to roll back when necessary.