Backlog

Commands

/backlog add <description>

1. Determine the title — short, imperative (e.g., "Add .options() and .env() to createTestService")
2. Determine what blocks it — another feature, a design decision, a package change, etc.
3. Create a GitHub Issue using

   gh issue create

   with:
   • Label:

     backlog

   • Label:

     blocked

     (if there's a known blocker)
   • Body format:

## What

<1-2 sentences describing the deferred work>

## Blocked by

<What needs to happen first. Reference issues/PRs if applicable, or describe the prerequisite.>
- [ ] <blocker 1>
- [ ] <blocker 2> (if multiple)

## Context

<Where this came up — PR number, conversation context, or design doc reference>

1. Print the issue URL when done.

/backlog list

gh issue list --label backlog --state open

• Blocked — issues that also have the

  blocked

  label
• Ready — issues with

  backlog

  label but NOT

  blocked

/backlog unblock <issue-number>

blocked

gh issue edit <number> --remove-label blocked

/backlog close <issue-number>

gh issue close <number>

When to Use

• During PR review: When a reviewer or agent flags a missing feature that's out of scope
• During implementation: When you discover work that depends on something not yet built
• During planning: When a phase is deferred or descoped
• After merging: When unblocking a prerequisite, run

  /backlog list

  to check if anything is now ready

Labels

• backlog

  — deferred work item

• blocked

  — waiting on a prerequisite

Rules

• Every deferred item MUST have a backlog issue — don't just mention it in a PR comment and forget
• Always include what blocks the work — "blocked by X" is required context
• Keep titles actionable — "Add X to Y" not "X is missing"
• Reference the PR or conversation where the item was identified