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]