the-nexus/docs/pr-backlog-process.md

PR Backlog Management Process

Overview

This document outlines the process for managing PR backlog in the Timmy Foundation repositories, specifically addressing the high PR backlog in timmy-config.

Current State

As of the latest analysis:

• timmy-config: 31 open PRs (highest in org)
• the-nexus: Multiple PRs for same issues
• hermes-agent: Moderate PR count

Process

1. Weekly Analysis

Run the PR backlog analyzer weekly:

python scripts/pr-backlog-analyzer.py

This generates a report in reports/pr-backlog-YYYYMMDD.md.

2. Review Stale PRs

PRs older than 30 days are considered stale. For each stale PR:

1. Check relevance: Is the PR still needed?
2. Check conflicts: Does it conflict with current main?
3. Check activity: Has there been recent activity?
4. Action: Close, update, or merge

3. Merge Approved PRs

PRs with approvals should be merged within 7 days:

1. Verify CI: Ensure all checks pass
2. Verify review: At least 1 approval
3. Merge: Use squash merge for clean history
4. Delete branch: Clean up after merge

4. Review Pending PRs

PRs waiting for review should be reviewed within 48 hours:

1. Assign reviewer: Ensure someone is responsible
2. Review: Check code quality, tests, documentation
3. Approve or request changes: Don't leave PRs in limbo
4. Follow up: If no response in 48 hours, escalate

5. Close Duplicate PRs

Multiple PRs for the same issue should be consolidated:

1. Identify duplicates: Same issue number or similar changes
2. Keep newest: Usually the most up-to-date
3. Close older: With explanatory comments
4. Document: Update issue with which PR was kept

Automation

GitHub Actions Workflow

The pr-backlog-management.yml workflow runs weekly to:

1. Analyze all open PRs
2. Generate a report
3. Create an issue if backlog is high (>10 stale PRs)

Manual Trigger

The workflow can be triggered manually via GitHub Actions UI.

Metrics

Track these metrics weekly:

• Total open PRs: Should be <20 per repo
• Stale PRs: Should be <5 per repo
• Average PR age: Should be <14 days
• Time to review: Should be <48 hours
• Time to merge: Should be <7 days after approval

Escalation

If backlog exceeds thresholds:

1. Level 1: Automated issue created
2. Level 2: Team lead notified
3. Level 3: Organization-wide cleanup sprint

Tools

PR Backlog Analyzer

# Run analysis
python scripts/pr-backlog-analyzer.py

# View report
cat reports/pr-backlog-$(date +%Y%m%d).md

Manual Cleanup

# List stale PRs
curl -s -H "Authorization: token $GITEA_TOKEN"   "https://forge.alexanderwhitestone.com/api/v1/repos/Timmy_Foundation/timmy-config/pulls?state=open" |   jq -r '.[] | select(.created_at < "'$(date -u -d '30 days ago' +%Y-%m-%dT%H:%M:%SZ)'") | .number'

# Close a PR
curl -s -X PATCH -H "Authorization: token $GITEA_TOKEN"   -H "Content-Type: application/json"   -d '{"state": "closed"}'   "https://forge.alexanderwhitestone.com/api/v1/repos/Timmy_Foundation/timmy-config/pulls/123"

Success Criteria

• Short-term: Reduce timmy-config PRs from 31 to <20
• Medium-term: Maintain <15 open PRs across all repos
• Long-term: Automated PR lifecycle management

Related

• Issue #1470: process: Address timmy-config PR backlog (9 PRs - highest in org)
• Issue #1127: Evening triage pass
• Issue #1128: Forge Cleanup