feat(skills): Add PR batch merge skill for autonomous operations

[cursor]

Summary

Create a skill for batch-merging multiple PRs with auto-merge, handling the common pattern of merging all APPROVED PRs.

Use Case

During autonomous PR monitoring (Session 106), the agent needed to:

1. List all open PRs
2. Filter to APPROVED PRs
3. Check merge readiness for each
4. Enable auto-merge with correct strategy (squash)
5. Monitor merge progress

This required many individual commands and could be simplified.

Proposed Skill

Invoke-PRBatchMerge.ps1 (or batch-merge-prs.sh for bash)

Parameters

Parameter	Type	Description
-Filter	string	Filter: "approved", "ready", "all"
-Strategy	string	Merge strategy: "squash", "merge", "rebase"
-AutoMerge	switch	Enable auto-merge instead of immediate merge
-DeleteBranch	switch	Delete branch after merge
-DryRun	switch	Show what would be merged without merging

Example Usage

# Merge all approved PRs with squash
./Invoke-PRBatchMerge.ps1 -Filter approved -Strategy squash -AutoMerge -DeleteBranch

# Dry run to see what would be merged
./Invoke-PRBatchMerge.ps1 -Filter approved -DryRun

Output

{
  "processed": 8,
  "autoMergeEnabled": 8,
  "alreadyMerged": 0,
  "failed": 0,
  "prs": [
    {"number": 625, "action": "auto-merge-enabled"},
    {"number": 603, "action": "auto-merge-enabled"}
  ]
}

Benefits

• Reduces token usage for batch operations
• Standardizes merge strategy across PRs
• Provides consistent error handling
• Enables monitoring mode for autonomous agents

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• feat(pr): add skill to list/filter pull requests (avoid raw gh pr list) #633
• feat(skills): Add bash fallback scripts for GitHub skills #629

🔗 Related PRs

#201 - feat(skills): import CodeRabbit AI learnings as validated skills [merged]
#226 - feat(workflows): add static PR and issue labeling workflows [merged]
#301 - docs: autonomous PR monitoring prompt and retrospective [merged]
#322 - feat: Implement PR merge state verification to prevent wasted review effort [merged]
#473 - docs(github): update SKILL.md with new scripts and Copilot guidance [merged]
#493 - feat(skills): recover Detect-CopilotFollowUpPR.ps1 from unmerged PR [merged]

👤 Suggested Assignees

• rjmurillo-bot

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[github-actions]

Product Requirements Document

Important

This PRD was automatically generated based on issue triage escalation.
Complexity Score: 6/12 (Standard)
Escalation Criteria: feature_request,multi_phase_work

About this PRD

This PRD was generated by the Explainer Agent after the issue was flagged
for detailed analysis. The document is designed to be self-contained - it can
be passed to a separate AI agent instance for implementation without additional
context.

PRD Depth Levels:

• Standard (4-6): Brief analysis, clear requirements
• Detailed (7-9): Research section, blocking questions
• Comprehensive (10-12): Phased implementation, risk analysis

---

Now I have sufficient context. Let me create the PRD for the batch merge skill.

The .agents/planning directory exists. The permission issue may be temporary. Let me output the PRD as plain text for the user:

---

PRD: PR Batch Merge Skill for Autonomous Operations

Executive Summary

This PRD defines a PowerShell skill for batch-merging multiple GitHub PRs, addressing the operational inefficiency observed during Session 106 where autonomous PR monitoring required many individual commands to merge APPROVED PRs.

Scope	Status	Blocker
Batch PR merge script	🟢 READY	None
Integration with existing GitHub skill	🟢 READY	None
Auto-merge support	🟢 READY	None
Pester test coverage	🟢 READY	None
SKILL.md documentation update	🟢 READY	None

Verdict: READY for implementation.

Problem Statement

Current State

Aspect	Current Implementation
Single PR merge	Merge-PR.ps1 handles one PR at a time
Auto-merge enable	Set-PRAutoMerge.ps1 enables auto-merge for one PR
Merge readiness check	Test-PRMergeReady.ps1 validates one PR
Batch operations	None. Agent must iterate manually over PR list

Gap Analysis

1. No batch merge capability: Agents must call individual scripts for each PR, consuming tokens and time.
2. Manual filtering: Agent must query PRs, filter by approval status, then iterate.
3. No structured batch output: No aggregated results for monitoring or reporting.
4. Inconsistent error handling: Individual failures are not aggregated or reported systematically.

User Impact

• Autonomous agents: Spend excessive tokens (5-10 per PR) on repetitive merge operations.
• Session duration: Batch operations take longer due to sequential individual calls.
• Error visibility: No consolidated view of batch operation success or failure.

Research Findings

Primary Sources

Existing Implementation Pattern (CONFIRMED)

The Merge-PR.ps1 script (.claude/skills/github/scripts/pr/Merge-PR.ps1) provides the canonical single-PR merge implementation:

• Uses gh pr merge CLI command
• Supports merge strategies: merge, squash, rebase
• Supports -Auto flag for auto-merge
• Supports -DeleteBranch for branch cleanup
• Returns structured JSON output

Auto-Merge Implementation (CONFIRMED)

Set-PRAutoMerge.ps1 uses GraphQL mutations:

• enablePullRequestAutoMerge mutation
• disablePullRequestAutoMerge mutation
• Supports merge method: MERGE, SQUASH, REBASE
• Returns structured JSON with Success, Action, AutoMergeEnabled

Merge Readiness Check (CONFIRMED)

Test-PRMergeReady.ps1 validates:

• PR state (open, not draft)
• No merge conflicts
• Review threads resolved
• CI checks passing
• Returns CanMerge boolean with Reasons array

Proposed Solution

Phase 1: Core Implementation (Status: READY)

Estimated Effort: M (4-6 hours)

Task	Description
1.1	Create Invoke-PRBatchMerge.ps1 in .claude/skills/github/scripts/pr/
1.2	Implement -Filter parameter with "approved", "ready", "all" options
1.3	Implement -Strategy parameter (squash, merge, rebase)
1.4	Implement -AutoMerge switch for auto-merge vs. immediate merge
1.5	Implement -DeleteBranch switch
1.6	Implement -DryRun switch
1.7	Return structured JSON output with batch results

Phase 2: Testing and Documentation (Status: READY)

Estimated Effort: S (2-3 hours)

Task	Description
2.1	Create Pester tests in .claude/skills/github/tests/Invoke-PRBatchMerge.Tests.ps1
2.2	Update SKILL.md decision tree and script reference
2.3	Add examples to SKILL.md Common Patterns section

Functional Requirements

FR-1: PR Discovery and Filtering (P0)

ID	Requirement	Acceptance Criteria
FR-1.1	Script MUST list open PRs in the repository	Returns array of open PR numbers
FR-1.2	Script MUST filter by -Filter approved	Only returns PRs with APPROVED review
FR-1.3	Script MUST filter by -Filter ready	Only returns merge-ready PRs
FR-1.4	Script MUST filter by -Filter all	Returns all open PRs without filtering
FR-1.5	Script MUST accept -PRNumbers array	Processes only listed PRs

FR-2: Merge Operations (P0)

ID	Requirement	Acceptance Criteria
FR-2.1	Script MUST support -Strategy squash	Squash merges PRs
FR-2.2	Script MUST support -Strategy merge	Creates merge commits
FR-2.3	Script MUST support -Strategy rebase	Rebases and merges PRs
FR-2.4	Script MUST support -AutoMerge switch	Enables auto-merge
FR-2.5	Script MUST support -DeleteBranch switch	Deletes head branch after merge

FR-3: Dry Run Mode (P1)

ID	Requirement	Acceptance Criteria
FR-3.1	Script MUST support -DryRun switch	No mutations when DryRun is set
FR-3.2	Dry run MUST output what would be merged	Returns PR list with proposed actions
FR-3.3	Dry run MUST check merge readiness	Reports which PRs are ready

FR-4: Output Format (P0)

ID	Requirement	Acceptance Criteria
FR-4.1	Output MUST be structured JSON	Valid JSON parseable by ConvertFrom-Json
FR-4.2	Output MUST include aggregated counts	processed, succeeded, failed, skipped
FR-4.3	Output MUST include per-PR results	Array with number, action, success, error

Technical Design

File Location

.claude/skills/github/scripts/pr/Invoke-PRBatchMerge.ps1
.claude/skills/github/tests/Invoke-PRBatchMerge.Tests.ps1

Script Parameters

[CmdletBinding(SupportsShouldProcess)]
param(
    [string]$Owner,
    [string]$Repo,
    
    [Parameter(ParameterSetName = 'Filter')]
    [ValidateSet('approved', 'ready', 'all')]
    [string]$Filter = 'approved',
    
    [Parameter(ParameterSetName = 'Explicit')]
    [int[]]$PRNumbers,
    
    [ValidateSet('squash', 'merge', 'rebase')]
    [string]$Strategy = 'squash',
    
    [switch]$AutoMerge,
    [switch]$DeleteBranch,
    [switch]$DryRun
)

Output Schema

{
  "Success": true,
  "Processed": 8,
  "Succeeded": 7,
  "Failed": 1,
  "Skipped": 0,
  "Strategy": "squash",
  "AutoMerge": true,
  "Results": [
    {
      "Number": 625,
      "Title": "feat: Add feature",
      "Action": "auto-merge-enabled",
      "Success": true,
      "Error": null
    }
  ]
}

Filter Logic

Filter	Criteria
approved	reviewDecision == 'APPROVED'
ready	APPROVED AND MERGEABLE AND CI_SUCCESS AND !isDraft
all	isDraft == false (all open, non-draft PRs)

Success Metrics

Metric	Target
Token reduction for batch merge	80% reduction vs. individual calls
API calls for 8-PR batch	Max 10 calls
Test coverage	80% line coverage
Documentation completeness	SKILL.md updated

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
API rate limiting on large batches	Medium	Medium	Use Test-WorkflowRateLimit before batch operations
Partial batch failure	Low	Low	Report per-PR success/failure; re-run with failed PRs
Auto-merge not enabled in repo	Low	Medium	Surface actionable error message

Blocking Questions

None. All requirements are clear and implementation path is defined.

Open Questions (Non-Blocking)

1. Q: Should the script support a -MaxPRs limit parameter?

   • Hypothesis: Yes, for safety in large repositories.

2. Q: Should we emit GitHub Actions step summary when running in CI?

   • Hypothesis: Yes, consistent with Invoke-PRMaintenance.ps1 pattern.

---

Recommend orchestrator routes to implementer for implementation.

_{Generated by AI PRD Generation | View Workflow}

[github-actions]

AI Triage Summary

Note

This issue has been automatically triaged by AI agents

What is AI Triage?

This issue was analyzed by AI agents:

• Analyst Agent: Categorizes the issue and suggests appropriate labels
• Roadmap Agent: Aligns the issue with project milestones and priorities
• Explainer Agent (if escalated): Generates comprehensive PRD

Triage Results

Property	Value
Category	enhancement
Labels	["enhancement","area-infrastructure"]
Priority	P2
Milestone	v1.1
PRD Escalation	Generated (see below)

Categorization Analysis

```json
{
  "labels": ["enhancement", "area-infrastructure"],
  "category": "enhancement",
  "confidence": 0.9,
  "reasoning": "Issue proposes a new PowerShell skill for batch-merging PRs to improve autonomous agent operations"
}

</details>

<details>
<summary>Roadmap Alignment</summary>

```json
```json
{
  "milestone": "v1.1",
  "priority": "P2",
  "epic_alignment": "",
  "confidence": 0.70,
  "reasoning": "Skills system enhancement aligns with v1.1 Maintainability focus; moderate impact on autonomous agent efficiency",
  "escalate_to_prd": true,
  "escalation_criteria": ["feature_request", "multi_phase_work"],
  "complexity_score": 6
}

</details>

---

<sub>Powered by [AI Issue Triage](https://github.com/rjmurillo/ai-agents) workflow</sub>