Backlog

Track bugs, questions, ideas, and tech debt across your project. The backlog is lightweight, user-initiated only, and split into four categories — nothing gets added automatically.

Four categories

Category	ID Prefix	Use for
Bugs	`B-NNN`	Defects, crashes, errors, things that are broken
Questions	`Q-NNN`	Decisions needed, blockers, unclear requirements, things to investigate
Ideas	`I-NNN`	Future features, improvements, "we should consider" items
Debt	`D-NNN`	Refactoring, cleanup, workarounds, code quality issues

Each category lives in its own JSON file under documentation/backlog/.

Commands

# Add items
/uc:backlog add idea: cache API responses for offline support
/uc:backlog add bug: login fails silently when session expires
/uc:backlog add question: should we support OAuth or just JWT?
/uc:backlog add debt: refactor auth middleware into separate module

# Add with labels (inline #tag syntax)
/uc:backlog add idea: cache API responses #performance #backend

# List and manage
/uc:backlog list              # all items across categories
/uc:backlog list bugs         # bugs only
/uc:backlog list #frontend    # filter by label
/uc:backlog done B-003        # mark as completed
/uc:backlog block Q-001 I-003 # Q-001 blocks I-003

# Labels
/uc:backlog label I-001 frontend  # add a label
/uc:backlog unlabel I-001 frontend # remove a label
/uc:backlog labels            # list all labels with counts

Key principles

User-initiated only — no skill or agent adds items to the backlog automatically. You decide what gets tracked.
Priorities — items have priority levels that affect sort order when listing
Labels — tag items with freeform labels using #tag syntax for lightweight categorization beyond the four category files. Labels are normalized to lowercase-hyphenated strings.
Blocking relationships — items can block other items, creating a dependency graph
Documentation links — items can reference documentation files for context
Source tracking — each item records where it came from (which conversation, which skill)

During plan execution, if agents discover follow-up work, bugs, or ideas, they're listed in the completion summary — not auto-added to the backlog. You decide what to track.

How backlog integrates with planning

The backlog is a lightweight project management layer that complements the planning skills:

Feature mode — when scope is cut during planning, the AI mentions cut items. You can add them to the backlog with /uc:backlog add idea: ...
Debug mode — investigation may reveal related issues beyond the immediate bug. Note them for later.
Verification mode — features described in docs but not implemented are listed separately. You decide whether to track them.
"What should we work on?" — run /uc:backlog list to see everything in one place, sorted by priority and blocking status

File format

Each category file is a simple JSON structure:

{
  "items": [
    {
      "id": "I-001",
      "title": "Cache API responses for offline support",
      "priority": "medium",
      "status": "open",
      "source": "feature-mode session",
      "created": "2026-04-07",
      "labels": ["performance", "backend"],
      "links": [],
      "blocked_by": [],
      "blocks": []
    }
  ]
}

You never need to edit these files directly — the /uc:backlog commands handle all operations.