Backlog

Track bugs, questions, ideas, and tech debt across your project. The backlog is lightweight and split into four categories — when skills find follow-up work, they ask you what to do before adding anything.

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

Triage before tracking — when skills discover follow-up work, they ask you first: do it now, include in the plan, add to backlog, or ignore.
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, follow-up work discovered by agents is collected in the completion summary. After execution finishes, you're walked through each item and asked whether to handle it immediately, add it to the backlog, or ignore it.

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, you're asked what to do with each cut item: handle now, keep in the plan, add to backlog, or ignore.
Debug mode — related issues found during investigation are triaged the same way — you choose the disposition for each one.
Verification mode — features described in docs but not implemented are listed and triaged — add to backlog, handle now, or ignore.
"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.