the-nexus/docs/backlog-manager.md

NexusBurn Backlog Manager

Automated backlog management tool for the Timmy Foundation organization. Processes triage data from issues like #1127 and automates cleanup actions.

Overview

The NexusBurn Backlog Manager is designed to:

1. Parse triage data from issues containing PR reviews and recommendations
2. Identify and close zombie PRs, duplicate PRs, and rubber-stamped PRs
3. Generate reports on organization health and process issues
4. Automate cleanup actions to keep repositories clean and manageable

Features

Triage Data Processing

• Parses structured triage issues (like #1127: Perplexity Evening Pass)
• Extracts PR reviews, process issues, and recommendations
• Categorizes PRs by verdict (Approved, Close, Comment, Needs Review)

Automated Actions

• Close zombie PRs: PRs with no actual changes (0 additions, 0 deletions)
• Close duplicate PRs: PRs that are exact duplicates of other PRs
• Address rubber-stamping: PRs with approval reviews but no actual changes
• Generate cleanup reports with metrics and recommendations

Reporting

• Markdown reports with summary statistics
• JSON logs for programmatic processing
• Metrics on organization health and process issues
• Actionable recommendations for process improvements

Usage

Basic Usage

# Generate report only (no actions)
python bin/backlog_manager.py --report-only

# Dry run (show what would be closed)
python bin/backlog_manager.py --close-prs --dry-run

# Actually close PRs (with confirmation)
python bin/backlog_manager.py --close-prs

# Parse custom triage file
python bin/backlog_manager.py --triage-file path/to/triage.md --report-only

Command Line Options

--triage-file PATH    Path to custom triage issue body file
--dry-run            Don't actually close PRs, just show what would happen
--report-only        Generate report only, don't process closures
--close-prs          Process PR closures based on triage verdicts

Configuration

The manager uses config/backlog_config.yaml for configuration:

Key Settings

backlog:
  # Repository settings
  organization: "Timmy_Foundation"
  
  # Repositories to manage
  repositories:
    - name: "the-nexus"
      priority: "high"
      auto_close_zombies: true
      auto_close_duplicates: true
  
  # PR closure rules
  closure_rules:
    zombie:
      action: "close"
      comment_template: "Closed by NexusBurn..."
  
  # Automation settings
  automation:
    dry_run_default: true
    require_confirmation: true
    log_all_actions: true

Output Files

Reports

• Markdown reports: ~/.hermes/backlog-logs/backlog_report_YYYYMMDD_HHMMSS.md
• Action logs: ~/.hermes/backlog-logs/backlog_actions_YYYYMMDD_HHMMSS.json

Example Report Structure

# NexusBurn Backlog Report
Generated: 2026-04-13T18:19:00Z
Source: Issue #1127 — Perplexity Evening Pass

## Summary
- Total PRs reviewed: 14
- Process issues identified: 5
- Recommendations: 4

## PR Review Results
| Verdict | Count |
|---------|-------|
| Approved | 8 |
| Close | 4 |
| Comment | 1 |
| Needs Review | 1 |

## PRs to Close
- **#572** (timmy-home): Zombie — 0 additions, 0 deletions
- **#377** (timmy-config): Duplicate of timmy-home #580
- **#363** (timmy-config): Exact duplicate of #362
- **#359** (timmy-config): Zombie — 0 changes, rubber-stamped

Process Improvements

Based on issue #1127 analysis, the manager identifies:

1. Rubber-stamping: PRs with approval reviews but no actual changes
2. Duplicate PRs: Same work filed multiple times across repos
3. Zombie PRs: PRs with no changes (already merged or never pushed)
4. Missing reviewers: PRs sitting with 0 assigned reviewers
5. Duplicate milestones: Confusing milestone tracking across repos

Integration

With Hermes

• Logs all actions to Hermes logging system
• Can be triggered from Hermes cron jobs
• Integrates with burn mode workflows

With Gitea

• Uses Gitea API for PR management
• Respects branch protection rules
• Adds explanatory comments before closing

With Cron

• Can be scheduled for regular runs (e.g., daily at 6 PM)
• Supports dry-run mode for safe automation

Testing

Run the test suite:

python -m pytest tests/test_backlog_manager.py -v

Architecture

bin/backlog_manager.py          # Main entry point
config/backlog_config.yaml      # Configuration
tests/test_backlog_manager.py   # Unit tests
docs/backlog-manager.md         # Detailed documentation

Future Enhancements

1. Milestone consolidation: Automatically deduplicate milestones
2. Reviewer assignment: Auto-assign reviewers based on CODEOWNERS
3. Duplicate detection: Advanced diff comparison for finding duplicates
4. Process metrics: Track improvements over time
5. Slack/Telegram integration: Notifications for critical issues

License

Part of the Timmy Foundation project. See LICENSE for details.