pr

Purpose

Creates high-quality pull requests by analyzing the actual changes, not parroting planning artifacts. The PR should tell a reviewer what changed, why, and how to verify it — nothing more.

Practices

1. Gather Context

Collect everything needed to understand the PR. Run these in parallel:

# Determine base branch (main or master)
git remote show origin | grep 'HEAD branch'

# Full commit log for this branch
git log --oneline <base>..HEAD

# Stat summary of all changes
git diff --stat <base>..HEAD

# Full diff for analysis (use Agent if very large)
git diff <base>..HEAD

Also check for harness artifacts that provide motivation context:

• .docs/specs/*.md — design docs (the "why")
• .docs/stories/*.md — acceptance criteria
• .pipeline/conduct-state.json — feature name if available

2. Analyze Changes

Read the diff carefully and categorize what changed:

• New files — what do they introduce?
• Modified files — what behavior changed?
• Deleted files — what was removed and why?
• Migrations — any schema changes?
• Tests — what's covered?
• Config/infra — docker, CI, dependencies?

Group changes by logical area (e.g., "Notifications module", "Auth projection", "Alembic migrations"), not by file path.

3. Write the Title

Check for project conventions first:

Look for PR title format conventions in the project's CLAUDE.md under a ### PR Title Format heading (or similar). Projects may specify their preferred format (conventional commits, ticket prefixes, etc.). If found, follow those conventions instead of the defaults below.

Common project convention examples:

• Conventional Commits: feat: add notification channel, fix(auth): resolve token expiry
• Ticket prefix: [PROJ-123] Add notification channel
• Type/scope: feat(notifications): add in-app channel

Default rules (when no project convention is defined):

• Under 72 characters — hard limit, no exceptions
• Imperative mood — "Add notifications module" not "Added" or "Adding"
• Specific — "Add in-app notification channel with persistence" not "Update notifications"
• No periods at the end
• If the PR does multiple things, summarize at the highest useful level