split-pr

# Split Large PR into Smaller Changes

## Purpose

Help developers break down large changesets into logical, reviewable pull requests. This skill analyzes the current diff and proposes a splitting strategy that keeps changes atomic and reviewable.

## Instructions

### 1. Analyze Current Changes

Run these commands to understand the scope:

```bash
# Get detailed file statistics
git diff main...HEAD --stat

# List all changed files
git diff main...HEAD --name-only

# Show commit history for context
git log main...HEAD --oneline

# Count non-generated files changed
git diff main...HEAD --name-only | grep -v 'vendor/' | grep -v '\.pb\.go$' | grep -v 'zz_generated' | grep -v '^docs/' | wc -l

# Count lines changed (excluding generated code)
git diff main...HEAD --stat -- . ':(exclude)vendor/*' ':(exclude)*.pb.go' ':(exclude)zz_generated*' ':(exclude)docs/*' | tail -1
```

### 2. Evaluate Size and Complexity

Assess whether the changes exceed recommended limits:

- **Target limits per PR**:
  - < 10 files changed (excluding tests, generated code, docs)
  - < 400 lines of code changed (excluding tests, generated code, docs)
  - Changes represent one logical unit of work

If changes exceed these limits or mix multiple concerns, proceed to split analysis.

### 3. Identify Logical Groupings

Examine the changed files and identify natural boundaries:

- **By component/package**: Group changes by the package or component they affect
- **By layer**: Separate model changes, business logic, API changes, CLI changes
- **By concern**: Separate refactoring from new features, bug fixes from enhancements
- **By dependency**: Identify which changes depend on others

Use these commands to help:

```bash
# Group changed files by directory
git diff main...HEAD --name-only | grep -v 'vendor/' | grep -v '\.pb\.go$' | cut -d'/' -f1-2 | sort | uniq -c

# Show changes by package
git diff main...HEAD --name-only | grep '\.go$' | grep -v '_test\.go$' | cut -d'/' -f1-3 | sort | uniq -c
```

### 4. Propose Split Strategy

Create a structured plan with multiple PRs:

For each proposed PR, specify:
- **PR Name**: Brief description (e.g., "Add base container interface")
- **Purpose**: What this PR accomplishes and why it's needed
- **Files included**: List of files that would be in this PR
- **Estimated size**: Approximate lines changed
- **Dependencies**: Which other proposed PRs this depends on (if any)
- **Test coverage**: What tests are included
- **Order**: Suggest the sequence for creating PRs (e.g., "Create this first")

### 5. Recommend Creation Order

Determine the optimal order for creating PRs:

1. **Foundation PRs first**: New interfaces, base types, shared utilities
2. **Refactoring PRs second**: Changes that use the new foundation
3. **Feature PRs last**: New functionality that builds on the foundation
4. **Independent PRs anytime**: Changes that don't depend on others

### 6. Present Action Plan

Provide a clear, actionable plan:

```markdown
## Proposed PR Split

### Summary
Currently [X] files changed with [Y] lines modified. Recommend splitting into [N] PRs:

### PR 1: [Name] (Create First)
**Purpose**: [What and why]
**Files**:
- path/to/file1.go
- path/to/file2.go
**Size**: ~100 LOC
**Dependencies**: None
**Tests**: Includes unit tests for new functionality

### PR 2: [Name] (After PR 1)
**Purpose**: [What and why]
**Files**:
- path/to/file3.go
**Size**: ~150 LOC
**Dependencies**: Requires PR 1 (uses new interface)
**Tests**: Integration tests

[... continue for each PR ...]

## Next Steps
1. Would you like me to help create PR 1 first?
2. Should I create a tracking issue for the overall work?
3. Any changes to this split strategy?
```

## Best Practices

### Splitting Principles

- **Each PR should pass tests independently**: Don't create PRs that break builds
- **Prefer multiple small PRs over one large PR**: Easier to review and revert
- **Keep related changes together**: Don't artificially split code that changes together
- **Foundation before features**: Establish abstractions before using them
- **Use feature flags for incomplete work**: If a feature spans multiple PRs

### Common Split Patterns

1. **Refactoring + Feature**:
   - PR 1: Extract interface and refactor existing code
   - PR 2: Add new feature using the interface

2. **Multi-layer Feature**:
   - PR 1: Add data models and database changes
   - PR 2: Add business logic layer
   - PR 3: Add API endpoints
   - PR 4: Add CLI commands

3. **Package Restructuring**:
   - PR 1: Create new package structure (empty or minimal)
   - PR 2: Move code to new structure
   - PR 3: Update imports and references
   - PR 4: Clean up old structure

4. **Kubernetes Operator Changes**:
   - PR 1: Update CRD definitions and generate code
   - PR 2: Update controller logic
   - PR 3: Add validation and defaulting
   - PR 4: Update documentation and examples

### What NOT to Split

- **Atomic refactorings**: Renaming that touches many files but is one logical change
- **Generated code updates**: Proto, CRD, mock updates should stay together
- **Dependency updates**: Keep go.mod and vendor changes in one PR
- **Tightly coupled changes**: Changes that don't make sense independently

## Examples

### Example 1: Adding New CLI Command

**Current state**: 8 files changed, 450 lines

**Split strategy**:
- PR 1: Add business logic to `pkg/` package (3 files, 200 lines)
- PR 2: Add CLI command and E2E tests (5 files, 250 lines)

**Rationale**: Business logic is independently testable and reusable

### Example 2: Refactoring + Feature

**Current state**: 15 files changed, 800 lines

**Split strategy**:
- PR 1: Extract common interface (2 files, 100 lines)
- PR 2: Refactor existing implementations to use interface (6 files, 300 lines)
- PR 3: Add new implementation with feature (7 files, 400 lines)

**Rationale**: Each PR is independently valuable and testable

### Example 3: Operator Enhancement

**Current state**: 12 files changed, 600 lines

**Split strategy**:
- PR 1: Update CRD with new fields and generate code (4 files, 150 lines, mostly generated)
- PR 2: Update controller to handle new fields (5 files, 300 lines)
- PR 3: Add validation webhook (3 files, 150 lines)

**Rationale**: Each PR represents a complete vertical slice of functionality

## User Interaction

After presenting the split strategy:

1. **Ask for feedback**: "Does this split make sense for your workflow?"
2. **Offer to adjust**: Be flexible based on user's preferences
3. **Help with first PR**: "Would you like me to help create PR 1?"
4. **Create tracking**: "Should I create a GitHub issue to track all PRs?"

## Notes

- **Be pragmatic**: The goal is reviewable PRs, not arbitrary rules
- **Consider the team**: Some teams prefer different split strategies
- **Document dependencies**: Make it clear which PRs block others
- **Test independently**: Each PR should pass CI/CD checks