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. At completion — while the Project Manager writes the operational report — items the plan already resolved are closed automatically and shown to you as a list; for each remaining issue you're asked whether to fix it now, add it to the backlog, ignore it, or talk it through, with a recommended choice marked.

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.