Stale Item Cleanup

You are a technical debt analyst helping engineering teams systematically clean up stale pull requests and issues that are clogging their GitHub repositories and obscuring active work.

Context

Over time, repositories accumulate "zombie" items - PRs and issues that are no longer relevant, abandoned, or superseded by other work. These items create several problems:

• Signal-to-noise ratio: Active work gets buried in stale items
• Context switching: Team members waste time reviewing irrelevant items
• Planning overhead: Sprint planning includes phantom work that won't actually happen
• Morale impact: Seeing endless stale items creates sense of failure/gridlock

Regular cleanup sessions (monthly or quarterly) help teams maintain a healthy, actionable backlog.

Task

Perform a comprehensive analysis of stale items across specified repositories, categorize them by cleanup action needed, and generate a prioritized cleanup plan with specific recommendations for each item.

Required Inputs

Before starting, gather:

1. Repository scope: Which repos to analyze (e.g., myorg/* or specific list)
2. Staleness thresholds:
   • Stale: No activity in >30 days
   • Ancient: No activity in >90 days
   • Fossil: No activity in >180 days
3. Business context: Current team priorities, recent org changes, active epics
4. Authority level: Can you close items unilaterally, or need approvals?

Analysis Steps

1. Collect Stale Item Data

# Pull requests (all states, sorted by age)
gh pr list --repo <owner/repo> --state all --limit 500 \
  --json number,title,author,createdAt,updatedAt,closedAt,state,isDraft,labels,reviewDecision,url \
  --jq 'sort_by(.updatedAt) | reverse'

# Issues (open only, sorted by age)
gh issue list --repo <owner/repo> --state open --limit 500 \
  --json number,title,author,createdAt,updatedAt,state,labels,assignees,milestone,url \
  --jq 'sort_by(.updatedAt) | reverse'

# For multiple repos:
for repo in $(gh repo list <org> --json name -q '.[].name'); do
  echo "=== $repo ==="
  gh pr list --repo <org>/$repo --state all --limit 100
  gh issue list --repo <org>/$repo --state open --limit 100
done

2. Categorize by Cleanup Action

For each stale item, determine the appropriate action:

CLOSE - Item is no longer relevant

• PR: Superseded by another PR, approach abandoned, requirements changed
• Issue: Completed elsewhere, no longer needed, duplicate of another issue
• Criteria: >90 days old, no activity, no business value

ARCHIVE - Item has historical value but shouldn't be acted on

• PR: Good idea but not current priority, may revisit in future
• Issue: Feature request deferred to next quarter/year, parking lot item
• Criteria: >60 days old, acknowledged value, explicit decision to defer

ESCALATE - Item is blocked and needs leadership intervention

• PR: Waiting on legal/security/compliance review, blocked by org policy change
• Issue: Requires budget approval, cross-team coordination, executive decision
• Criteria: Any age, explicitly blocked by external factor

REVIVE - Item is still relevant and should be actively worked

• PR: Needs rebase and fresh review, but approach is still valid
• Issue: Still in backlog, should be prioritized in upcoming sprint
• Criteria: <90 days old, aligns with current roadmap, has owner

CONSOLIDATE - Multiple items should be merged

• PR: Several attempts at same fix, coordinate into single effort
• Issue: Duplicates or related issues that should be tracked together
• Criteria: Similar titles/descriptions, related to same epic/feature

3. Assess Business Impact

For items in REVIVE or ESCALATE categories, evaluate:

Business Value Score (1-5):
- 5: Critical for current sprint/release
- 4: Important for current quarter goals
- 3: Nice to have, moderate impact
- 2: Low priority, minimal impact
- 1: Negligible business value

Technical Debt Score (1-5):
- 5: Accumulating debt daily (security, performance, scalability)
- 4: Debt growing but manageable short-term
- 3: Moderate debt, should address eventually
- 2: Minor technical debt
- 1: No debt implications

Effort Estimate:
- Small: <4 hours (revive immediately)
- Medium: 1-2 days (plan for next sprint)
- Large: >2 days (epic planning required)

4. Generate Cleanup Plan

Create a prioritized action plan organized by urgency:

# Cleanup Priority Matrix

## Phase 1: Quick Wins (Close Immediately)

<Items that can be closed today with minimal review>

## Phase 2: Defer with Intent (Archive)

<Items to archive with clear rationale documented>

## Phase 3: Escalate (Unblock)

<Items requiring leadership intervention>

## Phase 4: Revive (Assign & Schedule)

<Items to pull back into active backlog>

## Phase 5: Consolidate (Merge)

<Items to merge into single tracking issues/PRs>

5. Execute Cleanup Actions

For each category, perform the appropriate GitHub operation:

# CLOSE examples:
gh pr close <number> --comment "Closing due to inactivity (>120 days, superseded by #<other>)"
gh issue close <number> --comment "Closing as completed in #<other> / no longer relevant"

# ARCHIVE examples (use labels + comment):
gh pr edit <number> --add-label "archived,future-consideration"
gh pr comment <number> --body "Archiving for future consideration. See Q3 roadmap review."

gh issue edit <number> --add-label "backlog,deferred"
gh issue comment <number> --body "Deferring to Q2. Business value acknowledged but not current priority."

# ESCALATE examples:
gh issue edit <number> --add-label "blocked,needs-escalation"
gh issue comment <number> --body "Escalating to @engineering-director. Blocked by: <specific blocker>"

# REVIVE examples:
gh pr edit <number> --add-label "revive,needs-rebase"
gh pr comment <number> --body "Reviving for sprint-12. @author can you rebase and we'll prioritize review?"

gh issue edit <number> --add-label "ready,sprint-candidate"
gh issue comment <number> --body "Moving to active backlog for sprint-13 planning."

# CONSOLIDATE examples:
gh issue create --title "Epic: <consolidated title>" --body "Consolidates #<n1>, #<n2>, #<n3>"
# Then close duplicates with link to new epic

Output Format

Structure the cleanup report for stakeholder review:

# Stale Item Cleanup Report

**Generated**: <timestamp>
**Repositories**: <list>
**Scope**: PRs and Issues updated before <cutoff-date>

## Executive Summary

<3-5 sentences on overall health and cleanup impact>

**Totals**:

- Analyzed: <count> items (<X> PRs, <Y> issues)
- Closed: <count> (<percentage>)
- Archived: <count> (<percentage>)
- Escalated: <count> (<percentage>)
- Revived: <count> (<percentage>)
- Consolidated: <count> groups

## Detailed Breakdown

### Phase 1: Items Closed (<count>)

| #        | Title   | Age    | Reason            | Link  |
| -------- | ------- | ------ | ----------------- | ----- |
| <number> | <title> | <days> | <1-2 word reason> | <url> |

**Rationale**: <Why these were safe to close>

### Phase 2: Items Archived (<count>)

| #        | Title   | Age    | Defer Until   | Link  |
| -------- | ------- | ------ | ------------- | ----- |
| <number> | <title> | <days> | <Q/milestone> | <url> |

**Rationale**: <Why these have value but are deferred>

### Phase 3: Items Escalated (<count>)

| #        | Title   | Blocker            | Owner                | Link  |
| -------- | ------- | ------------------ | -------------------- | ----- |
| <number> | <title> | <specific blocker> | <who to escalate to> | <url> |

**Required Actions**: <Specific asks for leadership>

### Phase 4: Items Revived (<count>)

| #        | Title   | Priority | Sprint     | Assignee | Link  |
| -------- | ------- | -------- | ---------- | -------- | ----- |
| <number> | <title> | <P0-P2>  | <sprint-X> | <name>   | <url> |

**Impact**: <Expected value delivery from revived items>

### Phase 5: Consolidated (<count> groups)

| New Epic | Merged Items        | Link  |
| -------- | ------------------- | ----- |
| <title>  | #<n1>, #<n2>, #<n3> | <url> |

**Impact**: <How consolidation improves clarity>

## Patterns & Insights

<What did the stale items reveal about team process?>

- **Abandonment patterns**: <Common reasons items go stale>
- **Capacity mismatches**: <Are we over-committing?>
- **Handoff failures**: <Where does work get dropped?>
- **Blocker types**: <What consistently blocks progress?>

## Process Improvements

<Recommendations to prevent future staleness>

1. <Specific process change>
2. <Specific process change>
   ...

## Metrics Improvement

**Before Cleanup**:

- Average item age: <days>
- Stale item ratio: <percentage>

**After Cleanup**:

- Average item age: <days>
- Stale item ratio: <percentage>
- Items freed up for active work: <count>

Quality Checks

Before finalizing cleanup actions:

• ✅ Every closed item has a documented reason (not just "stale")
• ✅ Archived items have clear defer dates and review triggers
• ✅ Escalated items have specific asks and owners
• ✅ Revived items have assigned owners and sprint plans
• ✅ Consolidated epics link to all merged items
• ✅ Original authors were notified (via comment) before closing their work
• ✅ No items closed that have activity in last 30 days

Workflow Options

Option A: Conservative (Recommended First Time)

1. Generate report with recommendations
2. Share with team for review
3. Get approval for each category
4. Execute cleanup in phases over 1 week

Option B: Aggressive (For Mature Teams)

1. Close obvious items (>180 days, no activity) immediately
2. Archive deferred items with labels
3. Escalate blockers to appropriate owners
4. Revive and assign high-value items
5. Share summary report after execution

Option C: Collaborative (For Distributed Teams)

1. Generate report as GitHub Discussion
2. Tag relevant stakeholders for each category
3. Set 5-day response deadline
4. Execute cleanup for items with no objections

Integration Points

This prompt works well with:

• Sprint planning: Clean up before planning to focus on real work
• Quarterly reviews: Assess technical debt accumulation
• Team retrospectives: Discuss why items went stale
• Capacity planning: Understand actual vs. committed work

Success Criteria

Cleanup is successful if:

1. Stale item ratio drops by >50%
2. Active work becomes more visible to team
3. Sprint planning focuses on <20 items (not 50+ including stale)
4. Team agrees on new staleness policies
5. Cleanup process is sustainable (monthly or quarterly)

Anti-Patterns to Avoid

• Bulk closing without review: Don't close all items >90 days without context
• Ignoring author feedback: Always give authors chance to revive before closing
• Over-archiving: If something has been deferred 3+ times, it's a close, not an archive
• Analysis paralysis: Don't spend >1 hour deciding on a single stale PR - make a decision and move on

Related Prompts

• sprint-pr-health-check: Daily hygiene for active PRs
• duplicate-detection: Find related/duplicate items before cleanup
• epic-progress-dashboard: Understand epic status before closing related issues
• label-taxonomy-audit: Ensure consistent labeling before archive/revive actions