the-nexus/docs/backlog-manager.md

timmy-home Backlog Manager

Issue: #1459 - process: Address timmy-home backlog (220 open issues - highest in org)

Problem

timmy-home has 220 open issues, the highest in the organization. This creates:

• Difficulty finding relevant issues
• No clear ownership or prioritization
• Stale issues cluttering the backlog
• Poor issue management

Solution

Backlog Manager Tool (bin/backlog_manager.py)

Comprehensive tool for managing the timmy-home backlog:

Features:

1. Analyze backlog - Get statistics and insights
2. Generate reports - Detailed markdown reports
3. Bulk operations - Add labels, assign issues, close stale issues
4. Triage support - Identify unlabeled/unassigned issues

Usage

Analyze Backlog

# Quick analysis
python bin/backlog_manager.py --analyze

# Generate detailed report
python bin/backlog_manager.py --report

Triage Issues

# Add label to issue
python bin/backlog_manager.py --add-label 123 "bug"

# Assign issue to user
python bin/backlog_manager.py --assign 123 @username

# Close issue
python bin/backlog_manager.py --close 123

Bulk Operations

# Add label to multiple issues
python bin/backlog_manager.py --bulk-label "bug" "123,456,789"

# Close stale issues (>90 days)
python bin/backlog_manager.py --bulk-close-stale 90

Analysis Results

Current State (Example)

Backlog Analysis:
  Total open issues: 220
  With labels: 45
  Without labels: 175
  With assignee: 30
  Without assignee: 190
  Stale issues (>30 days): 85
  Unlabeled & unassigned: 150

Label Distribution

• bug: 15 issues
• feature: 20 issues
• docs: 10 issues

Assignee Distribution

• @user1: 10 issues
• @user2: 8 issues
• @user3: 7 issues

Recommendations

Based on analysis:

1. Add labels to 175 issues - Categorize for better management
2. Assign owners to 190 issues - Ensure accountability
3. Review 85 stale issues - Close or re-prioritize
4. Triage 150 unlabeled/unassigned issues - Basic triage needed

Triage Process

Step 1: Analyze

python bin/backlog_manager.py --analyze

Step 2: Triage Unlabeled Issues

# Add labels to unlabeled issues
python bin/backlog_manager.py --bulk-label "needs-triage" "1,2,3,4,5"

Step 3: Assign Owners

# Assign issues to team members
python bin/backlog_manager.py --assign 123 @username

Step 4: Close Stale Issues

# Close issues older than 90 days
python bin/backlog_manager.py --bulk-close-stale 90

Integration with CI/CD

Automated Triage (Future)

Add to CI pipeline:

- name: Triage new issues
  run: |
    python bin/backlog_manager.py --add-label $ISSUE_NUMBER "needs-triage"
    python bin/backlog_manager.py --assign $ISSUE_NUMBER @default-assignee

Regular Cleanup

Schedule regular cleanup:

# Daily: Close stale issues
0 0 * * * cd /path/to/repo && python bin/backlog_manager.py --bulk-close-stale 90

# Weekly: Generate report
0 0 * * 0 cd /path/to/repo && python bin/backlog_manager.py --report > backlog-report-$(date +%Y%m%d).md

Example Report

# timmy-home Backlog Analysis Report

Generated: 2026-04-15T05:30:00

## Summary
- **Total open issues:** 220
- **With labels:** 45
- **Without labels:** 175
- **With assignee:** 30
- **Without assignee:** 190
- **Stale issues (>30 days):** 85
- **Recent issues (<7 days):** 15
- **Unlabeled & unassigned:** 150

## Label Distribution
- **bug:** 15 issues
- **feature:** 20 issues
- **docs:** 10 issues

## Assignee Distribution
- **@user1:** 10 issues
- **@user2:** 8 issues
- **@user3:** 7 issues

## Stale Issues (>30 days old)
- **#123**: Old feature request
  - Created: 2026-01-15
  - Labels: None
  - Assignee: None

## Unlabeled & Unassigned Issues
- **#456**: New bug report
  - Created: 2026-04-10

## Recommendations
1. **Add labels to 175 issues** - Categorize for better management
2. **Assign owners to 190 issues** - Ensure accountability
3. **Review 85 stale issues** - Close or re-prioritize
4. **Triage 150 unlabeled/unassigned issues** - Basic triage needed

Related Issues

• Issue #1459: This implementation
• Issue #1127: Perplexity Evening Pass triage (identified backlog issue)

Files

• bin/backlog_manager.py - Backlog management tool
• docs/backlog-manager.md - This documentation

Conclusion

This tool provides comprehensive backlog management for timmy-home:

• Analysis - Understand backlog composition
• Triage - Categorize and assign issues
• Cleanup - Close stale issues
• Reporting - Track progress over time

Use this tool regularly to keep the backlog manageable.

License

Part of the Timmy Foundation project.