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

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

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

### Triage Issues

```bash
# 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

```bash
# 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
```bash
python bin/backlog_manager.py --analyze
```

### Step 2: Triage Unlabeled Issues
```bash
# Add labels to unlabeled issues
python bin/backlog_manager.py --bulk-label "needs-triage" "1,2,3,4,5"
```

### Step 3: Assign Owners
```bash
# Assign issues to team members
python bin/backlog_manager.py --assign 123 @username
```

### Step 4: Close Stale Issues
```bash
# 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:
```yaml
- 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:
```bash
# 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

```markdown
# 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.