Plan PRs Command

Generate a proactive PR delivery strategy for a Jira issue BEFORE coding begins.

Step 0: Time Tracking Initialization

AUTOMATIC: This step runs silently before command execution begins.

The orchestration system tracks execution time for this command. When the command completes:

If duration >= 60 seconds AND a Jira issue key is detected
A worklog is automatically posted with comment: [Claude] /jira:plan-prs - {duration}

Issue Key Detection Priority

Command argument (e.g., ${issue_key})
Git branch name (e.g., feature/PROJ-123-desc)
Environment variable JIRA_ISSUE_KEY
Current orchestration session

Configuration

Time logging can be configured in jira-orchestrator/config/time-logging.yml:

enabled: Toggle auto-logging (default: true)
threshold_seconds: Minimum duration to log (default: 60)
format: Worklog comment format (default: "[Claude] {command} - {duration}")

Why Use This Command?

Large PRs are hard to review and often lead to:

🐛 Missed bugs and security issues
😓 Reviewer fatigue and burnout
⏰ Delayed merges and blocked teammates
📉 Lower code quality overall

This command helps by planning how to split work into small, reviewable PRs upfront.

What It Does

Fetches Issue Details
- Gets parent issue and all sub-items from Jira
- Analyzes scope and complexity
Estimates PR Size
- Uses codebase patterns to estimate lines of code
- Categorizes work by type (API, UI, tests, etc.)
Creates Splitting Strategy
- Recommends how to divide work into PRs
- Maps sub-items to specific PRs
- Defines dependency order
Posts Plan to Jira
- Documents the strategy on the parent issue
- Creates visibility for the team
Configures Orchestration
- Saves strategy for CODE phase agents
- Enables checkpoint PR creation
- Generates a work plan artifact consumed by /jira:work

Usage

/jira:plan-prs ISSUE-KEY

Example Output

📊 PR Size Estimation Complete

Parent Issue: PROJ-123
Total Estimated: ~1,450 lines (🔴 Large - Split Required)

Strategy: 3-PR Split (Sub-Item Based)

┌─────────────────────────────────────────────────────────────┐
│ PR #1: [PROJ-123] Part 1: Database Layer                    │
│ ├─ Sub-Items: PROJ-201, PROJ-202                            │
│ ├─ Est. Size: ~350 lines                                    │
│ ├─ Dependencies: None                                        │
│ └─ Merge Order: First                                        │
├─────────────────────────────────────────────────────────────┤
│ PR #2: [PROJ-123] Part 2: API Layer                         │
│ ├─ Sub-Items: PROJ-203, PROJ-204, PROJ-205                  │
│ ├─ Est. Size: ~600 lines                                    │
│ ├─ Dependencies: PR #1                                       │
│ └─ Merge Order: After PR #1 merges                          │
├─────────────────────────────────────────────────────────────┤
│ PR #3: [PROJ-123] Part 3: UI Components                     │
│ ├─ Sub-Items: PROJ-206, PROJ-207                            │
│ ├─ Est. Size: ~500 lines                                    │
│ ├─ Dependencies: PR #2                                       │
│ └─ Merge Order: Final                                        │
└─────────────────────────────────────────────────────────────┘

✅ Strategy posted to Jira: https://jira.company.com/browse/PROJ-123
✅ Configuration saved for CODE phase agents
✅ Work plan artifact saved: `.claude/orchestration/plans/PROJ-123-plan.json`

Next Steps:
1. Run /jira:work PROJ-123 to start development
2. Checkpoint PRs will be created automatically
3. Each PR stays under 400 lines for easy review

Size Thresholds

Total Lines	Strategy	What Happens
< 200	Single PR	✅ Proceed normally
200-400	Single PR with roadmap	⚠️ Create review chunks
400-800	Split into 2-3 PRs	🟠 Split recommended
> 800	Split into 3+ PRs	🔴 Split required

Workflow

graph TD
    A[/jira:plan-prs ISSUE-KEY] --> B[Fetch Issue from Jira]
    B --> C[Get Sub-Items]
    C --> D[Analyze Complexity]
    D --> E{Estimated Size?}

    E -->|< 400 lines| F[Single PR Strategy]
    E -->|400-800 lines| G[2-3 PR Strategy]
    E -->|> 800 lines| H[3+ PR Strategy]

    F --> I[Generate Report]
    G --> I
    H --> I

    I --> J[Post to Jira]
    J --> K[Save Config + Work Plan Artifact]
    K --> L[Ready for /jira:work]

Agent Used

This command invokes the pr-size-estimator agent which:

Analyzes the codebase for similar patterns
Calculates line estimates per sub-item
Creates the splitting strategy
Posts documentation to Jira

Configuration Options

Environment variables to customize behavior:

# Size thresholds
PR_WARN_THRESHOLD=400       # Warn above this many lines
PR_BLOCK_THRESHOLD=800      # Require split above this

# Strategy preferences
PR_SPLIT_STRATEGY=auto      # auto, sub_item, layer, feature_slice
PR_MAX_SIZE=400             # Target max size per PR

Integration

This command works with:

/jira:work: Uses the strategy during CODE phase
/jira:work: Loads the work plan artifact to adapt phase staffing, gating, and PR splits
checkpoint-pr-manager: Creates PRs based on strategy
draft-pr-manager: Creates early draft PRs
pr-size-guard hook: Enforces size limits

Work Plan Artifact (Required)

/jira:plan-prs writes a JSON artifact to .claude/orchestration/plans/{ISSUE-KEY}-plan.json. /jira:work must load this file before task breakdown to enforce scope, sequencing, and PR splits.

{
  "issue_key": "PROJ-123",
  "estimated_total_loc": 1450,
  "pr_strategy": "sub_item",
  "max_pr_size": 400,
  "pr_splits": [
    {"name": "Database Layer", "sub_items": ["PROJ-201", "PROJ-202"], "dependencies": []},
    {"name": "API Layer", "sub_items": ["PROJ-203"], "dependencies": ["Database Layer"]}
  ],
  "gates": {
    "max_parallel_prs": 2,
    "required_reviewers": ["backend-architect", "api-security-expert"]
  }
}

When to Use

Run this command:

✅ Before starting work on any significant feature
✅ When you suspect a PR will be large
✅ After PLAN phase but before CODE phase
✅ When you want team visibility into delivery plan

/plan-prs