feat(workflow): auto-flag PRs exceeding commit threshold

[rjmurillo-bot]

Problem

PRs accumulate excessive commits (15-48) without shipping, indicating:

• Scope creep within a single PR
• Responding to every review comment with fixes
• No pressure to ship and iterate

Evidence

PR	Commits	Expected
#255	48	3-5
#235	23	5-10
#199	21	~5

Proposed Solution

Implement commit threshold monitoring:

1. Warning at 10 commits: Label PR with "needs-split"
2. Alert at 15 commits: Notify author to consider splitting
3. Block at 20 commits: Require human override to continue

This creates pressure to ship smaller PRs rather than growing forever.

Acceptance Criteria

• Workflow monitors commit count on PRs
• Warning label applied at threshold
• Process documented for splitting large PRs

Priority

P1 - Prevents future scope explosion, forces smaller PRs

---

🤖 Generated from PR velocity analysis session

[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

• chore: close or split PRs with excessive commit churn (40+ commits) #359
• feat(workflow): require human approval before bot review responses #361

🔗 Related PRs

#226 - feat(workflows): add static PR and issue labeling workflows [merged]
#245 - docs(memory): add decomposition analysis for Issue #239 [closed]
#299 - docs: add autonomous PR monitoring prompt [closed]
#303 - fix(workflow): use correct priority:P1 label format in pr-maintenance [merged]
#331 - docs: add velocity analysis and 10x improvement plan [closed]

👤 Suggested Assignees

• rjmurillo-bot
• rjmurillo

---

🧪 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 this commit threshold monitoring feature.

The directory exists. Let me output the PRD content directly since file creation is blocked.

---

PRD: Commit Threshold Monitoring for PRs

Executive Summary

PRs in this repository accumulate excessive commits (15-48 commits per PR) without shipping, indicating scope creep and lack of pressure to merge incrementally. This feature adds automated commit count monitoring to the PR workflow, applying warning labels and alerts at configurable thresholds.

Scope	Status	Blocker
Workflow monitors commit count	🟢 READY	None
Warning label at threshold	🟢 READY	None
Alert notification at threshold	🟢 READY	None
Block at threshold	🟡 PARTIAL	Requires decision on enforcement mechanism
Documentation for PR splitting	🟢 READY	None

Verdict: READY (core functionality can proceed; blocking enforcement is optional Phase 2)

---

Problem Statement

Current State

Metric	Observed	Expected	Deviation
PR #255 commits	48	3-5	860% over
PR #235 commits	23	5-10	130-360% over
PR #199 commits	21	~5	320% over

No mechanism exists to detect or alert when PRs exceed healthy commit counts.

Gap Analysis

1. No visibility: Authors lack feedback that their PR is growing beyond typical size
2. No process enforcement: No pressure to split PRs or ship incrementally
3. Review burden: Large PRs are harder to review, leading to superficial reviews
4. Merge risk: PRs with many commits accumulate more conflicts

User Impact

User Role	Impact
PR Author	Unaware their PR is growing beyond norms
Reviewer	Overwhelmed by large diffs
Maintainer	Merge conflicts, integration risk, delayed shipping

---

Research Findings

Primary Sources

GitHub Actions API (CONFIRMED):

• github.event.pull_request.commits provides commit count on PR events
• Available on opened, synchronize, and reopened triggers

Existing Patterns in Repository (CONFIRMED):

• label-pr.yml demonstrates label application workflow
• ai-pr-quality-gate.yml shows PR-triggered workflow with status checks
• pr-maintenance.yml shows scheduled PR processing patterns

Empirical Data

Commits	Classification	Action Needed
1-9	Healthy	None
10-14	Warning zone	Label + gentle alert
15-19	High concern	Strong alert
20+	Requires action	Block or escalate

---

Proposed Solution

Phase 1: Warning and Labeling (Status: READY)

Estimated Effort: S

Task	Description
1.1	Create pr-commit-threshold.yml workflow
1.2	Add needs-split label to repository
1.3	Implement commit count check on PR events
1.4	Apply label when threshold exceeded
1.5	Add PR comment with guidance

Phase 2: Documentation (Status: READY)

Estimated Effort: S

Task	Description
2.1	Create docs/pr-splitting-guide.md
2.2	Update CONTRIBUTING.md with threshold expectations

Phase 3: Enforcement (Status: PARTIAL)

Estimated Effort: M
Blockers: Decision needed on enforcement mechanism

Task	Description
3.1	Add configurable blocking threshold
3.2	Implement required status check
3.3	Add override mechanism

---

Functional Requirements

FR-1: Commit Count Monitoring (P0)

ID	Requirement	Acceptance Criteria
FR-1.1	Workflow triggers on PR opened, synchronize, reopened	Workflow runs on each PR update
FR-1.2	Workflow retrieves commit count from PR metadata	Commit count logged in workflow output
FR-1.3	Workflow compares count against configurable thresholds	Thresholds defined in workflow env vars

FR-2: Warning Label Application (P0)

ID	Requirement	Acceptance Criteria
FR-2.1	Apply needs-split label when commits >= WARNING_THRESHOLD	Label visible on PR
FR-2.2	Remove label if commits drop below threshold	Label removed after force-push
FR-2.3	Label application is idempotent	No duplicate labels

FR-3: Notification (P1)

ID	Requirement	Acceptance Criteria
FR-3.1	Post PR comment when threshold first exceeded	Comment appears with guidance
FR-3.2	Comment is idempotent (use marker)	Only one threshold comment per PR
FR-3.3	Comment includes link to splitting guide	Link points to valid documentation

---

Technical Design

Workflow Configuration

# .github/workflows/pr-commit-threshold.yml
name: PR Commit Threshold

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

env:
  WARNING_THRESHOLD: 10
  ALERT_THRESHOLD: 15
  BLOCK_THRESHOLD: 20
  NEEDS_SPLIT_LABEL: needs-split

jobs:
  check-commits:
    name: Check Commit Count
    runs-on: ubuntu-24.04-arm
    if: github.actor != 'dependabot[bot]'
    
    steps:
      - name: Get commit count
        id: commits
        run: |
          COMMIT_COUNT=${{ github.event.pull_request.commits }}
          echo "count=$COMMIT_COUNT" >> $GITHUB_OUTPUT
          
      - name: Evaluate thresholds
        id: evaluate
        run: |
          COUNT=${{ steps.commits.outputs.count }}
          if [ "$COUNT" -ge "$BLOCK_THRESHOLD" ]; then
            echo "level=block" >> $GITHUB_OUTPUT
          elif [ "$COUNT" -ge "$ALERT_THRESHOLD" ]; then
            echo "level=alert" >> $GITHUB_OUTPUT
          elif [ "$COUNT" -ge "$WARNING_THRESHOLD" ]; then
            echo "level=warning" >> $GITHUB_OUTPUT
          else
            echo "level=ok" >> $GITHUB_OUTPUT
          fi
          
      - name: Apply or remove label
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          if [ "${{ steps.evaluate.outputs.level }}" != "ok" ]; then
            gh pr edit ${{ github.event.pull_request.number }} --add-label "$NEEDS_SPLIT_LABEL"
          else
            gh pr edit ${{ github.event.pull_request.number }} --remove-label "$NEEDS_SPLIT_LABEL" || true
          fi
          
      - name: Post threshold comment
        if: steps.evaluate.outputs.level != 'ok'
        uses: actions/github-script@v7
        with:
          script: |
            const marker = '<!-- PR-COMMIT-THRESHOLD -->';
            const count = ${{ steps.commits.outputs.count }};
            const level = '${{ steps.evaluate.outputs.level }}';
            
            const body = `${marker}
            ## PR Commit Threshold ${level.toUpperCase()}
            
            This PR has **${count} commits**.
            
            ### Recommended Actions
            1. Consider splitting into smaller PRs
            2. Squash related commits
            3. See docs/pr-splitting-guide.md for strategies`;
            
            const { data: comments } = await github.rest.issues.listComments({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number
            });
            
            const existing = comments.find(c => c.body.includes(marker));
            
            if (existing) {
              await github.rest.issues.updateComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                comment_id: existing.id,
                body: body
              });
            } else {
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
                body: body
              });
            }

Labels Required

Label	Color	Description
needs-split	#d93f0b	PR exceeds commit threshold
override-commit-limit	#0e8a16	Maintainer override

---

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
False positives on large PRs	Medium	Medium	Override label mechanism
Authors ignore warnings	High	Medium	Block threshold creates hard stop
Thresholds too aggressive	Medium	Low	Start conservative, tune based on data

---

Success Metrics

Metric	Target
Average commits per merged PR	< 10
PRs with needs-split label merged without splitting	< 20%
PRs blocked at 20+ commits	100% (unless override)

---

Implementation Plan

Phase 1 Tasks

1. Create needs-split and override-commit-limit labels
2. Create .github/workflows/pr-commit-threshold.yml
3. Test on a PR with 10+ commits

Phase 2 Tasks

1. Create docs/pr-splitting-guide.md
2. Update CONTRIBUTING.md with threshold expectations

---

Open Questions (Non-Blocking)

1. Q: Should thresholds be configurable per-repository?

   • Hypothesis: Start hardcoded, add configuration later

2. Q: Should this integrate with pr-maintenance.yml?

   • Hypothesis: No, event-driven is sufficient

---

Verdict: READY. Recommend routing to implementer for Phase 1 execution.

_{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-workflows"]
Priority	P1
Milestone	v1.1
PRD Escalation	Generated (see below)

Categorization Analysis

```json
{
  "labels": ["enhancement", "area-workflows"],
  "category": "enhancement",
  "confidence": 0.95,
  "reasoning": "Issue proposes a new GitHub Actions workflow to monitor and flag PRs exceeding commit thresholds"
}

</details>

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

```json
```json
{
  "milestone": "v1.1",
  "priority": "P1",
  "epic_alignment": "",
  "confidence": 0.7,
  "reasoning": "Process improvement for PR hygiene aligns with v1.1 maintainability focus; does not map to existing epics",
  "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) - [View Workflow](https://github.com/rjmurillo/ai-agents/actions/runs/20486446596)</sub>