Add Lightweight Maintenance Backlog for Non-Story Work

[klueless-io]

BMAD v6 Proposal: Lightweight Maintenance Tracking

Author: David Cruwys (AppyDave)
Date: 2025-12-28
Status: Draft
Target: BMAD Method v6+

---

Problem Statement

During BMAD-driven development, teams frequently discover small items that don't warrant full story ceremony:

• Infrastructure gaps (e.g., missing gitignore entries, pre-commit hooks)
• Tech debt (e.g., unused variables, lint warnings, outdated patterns)
• Documentation drift (e.g., README shows old patterns, outdated examples)
• Small bugs (e.g., edge cases, minor fixes)

Current State

BMAD v4/v6 offers brownfield-create-story for small work (~4 hours), but this still requires:

• SM to draft the story
• Story structure with ACs, tasks, dev notes
• Dev agent to implement
• QA review

For 5-15 minute fixes, this is disproportionate overhead.

What Happens Today

Teams either:

1. Forget items - No lightweight capture mechanism
2. Tack onto unrelated stories - Pollutes story scope, unclear traceability
3. Skip the fix - Creates accumulating debt
4. Create micro-stories - Ceremony costs more than the work

---

Proposed Solution

Maintenance Backlog

A lightweight markdown file tracked in core-config.yaml:

maintenance:
  backlogFile: docs/backlog/maintenance.md
  categories:
    - infrastructure
    - tech-debt
    - documentation
    - bugs

File Format

# Maintenance Backlog

> Lightweight tracking for chores, infrastructure, and small fixes.
> Items here don't require full BMAD ceremony.

## Pending

### Infrastructure
- [ ] Add GitHub Actions CI pipeline

### Tech Debt
- [ ] Fix unused param warning in health.ts

### Documentation
- [ ] Update README installation steps

### Bugs
- [ ] Handle edge case in date formatting

## Done (2025-12)

- [x] Add gitleaks hook — Story 2.3, commit abc123
- [x] Add .astro/ to gitignore — Story 2.3, commit abc123

---

BMAD Integration Points

1. Agent Discovery

All BMAD agents can find the backlog via core-config.yaml:

maintenance:
  backlogFile: docs/backlog/maintenance.md

2. Agent Interactions

Agent	Capability
Dev Agent	Add items discovered during development
QA Agent	Add non-blocking issues found during review
SM Agent	List items, promote to story if needed
PO Agent	Review backlog health, batch into housekeeping story

3. Suggested Commands

*list-maintenance     # Show pending items by category
*add-maintenance      # Add discovered item
*promote {item}       # Convert to brownfield-create-story
*housekeeping         # Create batched story for multiple items

4. Story Cross-Reference

When items are fixed during story work, the Done entry references the story:

- [x] Add gitleaks hook — Story 2.3, commit f31c346

When items are fixed outside stories:

- [x] Fix lint warning — commit abc123

---

Workflow

Discovery Flow

During Story Work
       │
       ▼
┌─────────────────┐
│ Notice small    │
│ issue/gap       │
└────────┬────────┘
         │
         ▼
    ┌────────────┐
    │ Is it a    │
    │ blocker?   │
    └─────┬──────┘
          │
    ┌─────┴─────┐
    │           │
   Yes          No
    │           │
    ▼           ▼
┌────────┐  ┌──────────────┐
│ Fix    │  │ Add to       │
│ now    │  │ maintenance  │
└────────┘  │ backlog      │
            └──────────────┘

Resolution Flow

Between Stories / Free Time
           │
           ▼
   ┌───────────────┐
   │ Check backlog │
   │ for 15-60 min │
   │ items         │
   └───────┬───────┘
           │
           ▼
   ┌───────────────┐
   │ Pick item     │
   │ Fix it        │
   │ Mark done     │
   └───────┬───────┘
           │
           ▼
   ┌───────────────┐
   │ Commit with   │
   │ reference     │
   └───────────────┘

Promotion Flow

Item Grows During Analysis
           │
           ▼
   ┌───────────────┐
   │ Estimate > 2  │
   │ hours?        │
   └───────┬───────┘
           │
          Yes
           │
           ▼
   ┌───────────────┐
   │ *promote      │
   │ Creates       │
   │ brownfield    │
   │ story         │
   └───────────────┘

---

Benefits

For Teams

1. Capture - Small items don't get lost
2. Visibility - Team sees accumulated maintenance work
3. Low friction - Add items in seconds, no ceremony
4. Batching - Group related items for efficiency
5. Traceability - Done items link to commits/stories

For BMAD

1. Completeness - Covers work type not currently addressed
2. Lightweight - Doesn't add ceremony, reduces it
3. Integrated - Works with existing agents via core-config
4. Optional - Teams can adopt if useful, ignore if not

---

Implementation Suggestions

Phase 1: Documentation & Convention

• Add maintenance section to core-config.yaml schema
• Document the pattern in user-guide.md
• Provide template for maintenance.md

Phase 2: Agent Awareness

• Agents check for backlogFile in core-config
• Dev/QA agents can add items during their work
• SM agent can list and promote items

Phase 3: Commands (Optional)

• *list-maintenance - Display pending items
• *add-maintenance - Quick add with category
• *promote - Convert to brownfield story
• *housekeeping - Batch multiple items into one story

---

Example: Real-World Usage

During Story 2.3 (Implement Handlebars Helpers), we discovered:

Item	Time to Fix	Ceremony Cost if Story
Add .astro/ to gitignore	2 min	~30 min
Add gitleaks pre-commit hook	15 min	~45 min
Update README to ESM pattern	10 min	~30 min
Add .d.ts type declarations	20 min	~45 min

Total fix time: ~47 minutes
Ceremony cost if separate stories: ~2.5 hours
Savings: 70% overhead reduction

These were handled as part of Story 2.3's completion notes, but a maintenance backlog would have:

• Captured them as they were discovered
• Made them visible for prioritization
• Allowed fixing between stories if preferred

---

Open Questions

1. Should Done items auto-archive after 30 days?
2. Should there be a size limit (e.g., max 2 hours) enforced?
3. Should agents auto-add items, or just suggest?
4. Integration with GitHub Issues for teams that prefer issue tracking?

---

References

• BMAD Method v4: brownfield-create-story.md
• BMAD Method v6: GitHub Releases
• Scrum concept: Spikes, Chores, Tech Debt backlog

---

Feedback

This proposal is based on practical experience using BMAD v4 on the POEM-OS project. Feedback welcome via:

• GitHub issue on bmad-code-org/BMAD-METHOD
• BMAD Discord community