pr-breakdown

name: pr-breakdown description: Takes a very large change set and breaks it down into logical PRs which are then submitted with thorough descriptions. Used when a feature implementation is too large to be submitted in a single go.

Sequential PR Breakdown

Purpose

Break down a large feature implementation into sequential, reviewable pull requests that maintain CI validation and clear dependency chains.

Usage

When a user requests breaking down changes into sequential PRs, follow this workflow exactly.

Workflow

Phase 1: Assessment and Planning

1. Identify all changed files

   git status
   git diff --name-only

2. Understand the scope

   • Review the initial plan that lead to all these changes
   • Review all modified files to understand the feature implementation
   • Identify logical boundaries (e.g., database migrations, API changes, UI components, tests)
   • Note any dependencies between changes

3. Create PR breakdown plan

   • Group changes into logical, self-contained units
   • Order them by dependency (infrastructure → backend → frontend → tests)
   • Identify which PRs must be chained vs independent
   • Present the plan to the user with:
     • PR sequence with titles
     • Files included in each PR
     • Dependencies (chained or independent)
     • Rationale for the grouping

4. Get user approval before proceeding

Phase 2: CI Validation

Before creating any PRs, ensure all validation passes locally:

1. Run all tests
2. Run linting
3. Run formatting checks
4. Fix all failures
   • If tests fail, debug and fix before proceeding
   • If linting fails, run npm run lint:fix or equivalent
   • If formatting fails, run npm run format or equivalent
   • Re-run all checks until everything passes

There can be sub projects or nested lint/test commands that apply to your change set. You MUST be extremely thorough in making sure all linting/formatting and testing has been accomodated for. If in doubt, inspect the GitHub Actions workflows which describe the CI processes that will run, and ensure that ALL of those are passing locally BEFORE we commit a single file.

CRITICAL: Do not proceed to Phase 3 until all CI checks pass locally.

Phase 3: Create Sequential PRs

For each PR in the planned sequence:

1. Create and checkout branch

   # For base PR:
   git checkout -b feature/1-base-infrastructure
   
   # For chained PRs (based on previous):
   git checkout -b feature/2-api-endpoints feature/1-base-infrastructure

2. Stage only relevant files

   git add path/to/file1.ts path/to/file2.ts

3. Commit with descriptive message

   git commit -m "feat: [PR 1/N] Add base infrastructure for feature X"

4. Push branch

   git push origin feature/1-base-infrastructure

5. Open PR with GitHub CLI

   # For base PR (ready for review):
   gh pr create \
     --title "[1/N] Add base infrastructure for feature X" \
     --body "## Overview
   [Description of what this PR does]
   
   ## Changes
   - Change 1
   - Change 2
   
   ## Dependencies
   - None (base PR)
   
   ## Testing
   - All tests passing
   - Linting passing
   - Formatting passing
   
   ## Part of sequence
   This is PR 1 of N in the feature X implementation." \
     --base main
   
   # For chained PRs (draft, based on previous):
   gh pr create \
     --title "[2/N] Add API endpoints for feature X" \
     --body "## Overview
   [Description of what this PR does]
   
   ## Changes
   - Change 1
   - Change 2
   
   ## Dependencies
   - ⛓️ **Chained to**: #[PR-NUMBER] - Must be merged first
   
   ## Testing
   - All tests passing
   - Linting passing
   - Formatting passing
   
   ## Part of sequence
   This is PR 2 of N in the feature X implementation." \
     --base feature/1-base-infrastructure \
     --draft

6. Record PR URL and number for the summary

Phase 4: Summary

After all PRs are created, provide:

1. PR Chain Visualization

   main
   └── [1/N] Base Infrastructure (#123) ✅ Ready for review
       └── [2/N] API Endpoints (#124) 📝 Draft (chained)
           └── [3/N] UI Components (#125) 📝 Draft (chained)
   
   Independent PRs:
   - [4/N] Documentation Updates (#126) 📝 Draft (independent)

2. Review order instructions

   • Numbered list of PRs in review order
   • Which PRs can be reviewed in parallel
   • Which PRs block others

3. Merge instructions

   • Step-by-step merge process
   • How to update base branches for chained PRs after merging

Key Principles

• Never skip CI validation - All checks must pass before creating PRs
• Logical grouping - Each PR should be independently reviewable and make sense on its own
• Clear dependencies - Mark chained PRs and explain why they depend on each other
• Descriptive titles - Use [N/Total] prefix and clear feature descriptions
• Comprehensive descriptions - Every PR needs overview, changes, dependencies, and testing notes
• Draft for non-base PRs - Only the first PR should be ready for review initially

Common PR Grouping Patterns

1. Database First

   • PR 1: Migrations and schema changes
   • PR 2: Backend models and queries
   • PR 3: API endpoints
   • PR 4: Frontend implementation

2. Foundation Up

   • PR 1: Types and interfaces
   • PR 2: Core utilities and helpers
   • PR 3: Business logic
   • PR 4: Integration and tests

3. Feature Flags

   • PR 1: Feature flag infrastructure
   • PR 2-N: Individual components (can be independent)
   • PR N+1: Enable feature flag

Error Handling

• If CI checks fail at any point, stop and fix before proceeding
• If a PR creation fails, report the error and await instructions
• If the user wants to modify the plan, restart from Phase 1