Managing Backlog

Automatically maintain a living BACKLOG.md document tracking deferred work, tech debt, bugs, and improvements.

Core principle: Backlog maintains itself. Users only interact to query status or make manual adjustments.

When This Skill Activates

Automatic (no user prompt):

• Work is deferred during brainstorming
• Tasks identified but out of scope during planning
• Tech debt or improvements noted during code review
• Related bugs found during systematic debugging
• Issues discovered during implementation

Manual (user request):

• "Show me the backlog"
• "What's high priority?"
• "Add X to backlog"
• "Mark Y complete"

BACKLOG.md Structure

Location: Project root (BACKLOG.md)

Organization:

• Primary: Priority (High → Medium → Low)
• Secondary: Type (Features, Tech Debt, Bugs, Improvements)
• Completed: Separate section at bottom with commit SHAs

Format:

# Project Backlog

## High Priority

### Features
- [ ] Feature description (added: 2026-01-05)

### Tech Debt
- [ ] Refactor X (added: 2026-01-04)

### Bugs
- [ ] Fix Y (added: 2026-01-05)

### Improvements
- [ ] Optimize Z (added: 2026-01-03)

## Medium Priority
[same subsections...]

## Low Priority
[same subsections...]

---

## Completed

### Features
- [x] User profile (completed: 2026-01-03, commit: 3df7661)

### Tech Debt
- [x] Refactor auth (completed: 2026-01-04, commit: b82e439)

### Bugs
- [x] Fix race condition (completed: 2026-01-05, commit: c91a023)

### Improvements
- [x] Optimize queries (completed: 2026-01-02, commit: f4e8a12)

Adding Items to Backlog

Process

1. Check for BACKLOG.md

• If doesn't exist, create from template at skills/managing-backlog/backlog-template.md
• Announce: "Creating BACKLOG.md"
• Commit: chore: initialize project backlog

2. Check for duplicates

• Scan existing items for similar descriptions (>80% text similarity)
• If found, skip and announce: "Similar item already in backlog: {existing}"

3. Determine priority and type

Use context to set smart defaults:

| Context | Priority | Type | |---------|----------|------| | Bug found during debugging | Medium | Bugs | | Deferred feature from brainstorming | Low | Features | | Tech debt from code review (Minor) | Low | Tech Debt | | Tech debt from code review (Important) | Medium | Tech Debt | | Performance improvement noted | Low | Improvements | | Security issue found | High | Bugs | | Breaking change needed | High | Tech Debt |

4. Insert item

• Add to appropriate priority + type section
• Format: - [ ] {description} (added: YYYY-MM-DD)
• Preserve existing order (newest first within section)

5. Announce and commit

• Announce: "Adding to backlog as [Priority/Type]: {description}"
• Commit message: chore: add backlog item - {description}

Example

During code review, you find magic numbers that should be constants.

You: "Adding to backlog as [Low Priority/Tech Debt]: Replace magic numbers with named constants in validation module"

[Updates BACKLOG.md automatically]
[Commits change]

Edge Cases

Malformed BACKLOG.md:

• Attempt to preserve content while fixing structure
• Fall back to appending to correct section if can't parse
• Never lose user data
• Announce any structural fixes made

Git conflicts:

• If BACKLOG.md has merge conflicts
• Pause automatic updates
• Announce: "BACKLOG.md has merge conflicts. Please resolve before I can update it."

Completing Items

Detection Methods

Explicit reference (preferred):

• Task description: "Fix backlog item: {description}"
• Commit message: "Addresses backlog: {description}"
• User statement: "This completes the backlog item about X"

Fuzzy matching (secondary):

• Compare task/commit description to backlog items
• Strong similarity (>80% match) triggers auto-completion
• Use strongest match if multiple candidates

Process

1. Identify matching item

• Scan all uncompleted items (High, Medium, Low priority sections)
• Find item matching work just completed
• If multiple matches, pick strongest (highest similarity)

2. Mark complete and move

• Check the checkbox: - [ ] → - [x]
• Move to appropriate Completed subsection (by type)
• Add completion info: (completed: YYYY-MM-DD, commit: SHA)
• Place at top of Completed subsection (newest first)

3. Get commit SHA

For git projects:

git rev-parse HEAD | cut -c1-7

For non-git projects:

• Use timestamp only: (completed: YYYY-MM-DD)

4. Announce and commit

• Announce: "Marking backlog item complete: {description}"
• Commit message: chore: mark backlog item complete - {description}

Integration Points

Check for completed backlog items:

• verification-before-completion - Before declaring work done
• subagent-driven-development - After task completion and commit
• finishing-a-development-branch - Scan all commits before merge

Example

You just implemented caching for API responses.

Backlog has: "- [ ] Add caching layer to API responses (added: 2026-01-03)"

You: "Marking backlog item complete: Add caching layer to API responses"

[Moves item to Completed section]
Item becomes: "- [x] Add caching layer to API responses (completed: 2026-01-05, commit: a7f3c21)"

[Commits change]

Manual Commands

Users can manually interact with the backlog through these commands:

Query Commands

"Show me the backlog"

• Read BACKLOG.md
• Present current state organized by priority
• Include item counts per section

"What's high priority?" / "What's medium priority?" / "What's low priority?"

• Filter and show specific priority section
• Include all types within that priority

"What bugs are in the backlog?" / "What features..." / "What tech debt..." / "What improvements..."

• Filter by type across all priorities
• Show priority level for each item

"What's the backlog status?"

• Summary of item counts:
  • High: X items (Y features, Z bugs, ...)
  • Medium: X items
  • Low: X items
  • Completed: X items

Manual Adjustments

"Add X to backlog as [priority/type]"

• User specifies priority (High/Medium/Low) and type (Feature/Bug/Tech Debt/Improvement)
• Follow same addition process as automatic
• Announce and commit

"Remove Y from backlog"

• Find item matching Y
• Remove from BACKLOG.md
• Announce: "Removed from backlog: {description}"
• Commit: chore: remove backlog item - {description}

"Mark Z complete"

• Find item matching Z
• Follow completion process
• Move to Completed section with current commit SHA

"Change X to [priority]"

• Find item X
• Move to specified priority section (keep same type)
• Announce: "Changed priority: {description} → [New Priority]"
• Commit: chore: reprioritize backlog item - {description}

Example Interactions

User: "What's high priority?"

You: "High priority items in backlog:

Features:
- Real-time notifications (added: 2026-01-04)

Bugs:
- Fix session cleanup (added: 2026-01-05)

2 total high priority items."

User: "Add support for PostgreSQL to backlog as High Priority Feature"

You: "Adding to backlog as [High Priority/Feature]: Support for PostgreSQL"
[Updates BACKLOG.md]
[Commits]