/groom-backlog

Walk the backlog, complete Definition of Ready on the top candidates, and wire dependencies — the daytime work that makes beads become surfaceable by bd ready.

The inversion: Ready is computed, not curated

This is the most important thing to internalize before running this command. There is no “move to Ready” action. bd ready mechanically returns every open, unblocked bead whose Definition-of-Ready is complete — it is a query, not a column, and nothing the grooming agent does moves anything to a destination.

Grooming completes DoR. bd ready is the outcome of that work, not the thing you populate. If you find yourself asking “which beads should I put in Ready?”, flip the question: “which beads need DoR work so they naturally surface?”

This inversion is what eliminated ~420 lines of board-hygiene protocol from the v1.6.0 release: the tracker computes Ready, so there is no manual maintenance loop to run.

When to use it

Run this in the morning before kicking off work, or whenever bd ready --json --type=task returns fewer than two candidates. The command launches the backlog-prioritizer agent, which:

Reads strategic context (docs/PRODUCT-REQUIREMENTS.md, docs/PRODUCT-ROADMAP.md)
Counts beads by status from bd list --json and bd ready --json
Scores backlog candidates with Cost-of-Delay ÷ Duration (CD3)
Completes DoR on the top 2–5 candidates: 4 Power Sections, effort label, priority, safety class
Wires or clears dependencies at the bead level
Defers out-of-scope beads to the icebox

Don’t use this for single-ticket triage on a brand-new request — that is /create-ticket territory. Grooming operates on the existing backlog; it doesn’t create new beads.

How it fits in the lifecycle

Inputs are the existing backlog plus strategic context. The output is not “a populated Ready column” — it is a set of beads whose DoR is now complete, which causes them to surface naturally in bd ready.

What it does

Backlog health analysis

The agent counts beads by computed status (backlog = open minus ready; icebox = --status=deferred; in-progress = claimed; etc.) and flags bottlenecks — too many claimed at once, a long stale tail, beads missing effort estimates.

CD3 prioritization

Candidates are scored by Cost of Delay ÷ Duration, weighted by user impact and business value. The agent reads the PRD and roadmap to align prioritization with the current strategic phase.

Definition-of-Ready completion

For each top candidate the agent verifies:

Clear title and description with context
Acceptance criteria that are specific and testable
The 4 Power Sections (A. Environment Context, B. Guardrails, C. Happy Path, D. Definition of Done) per docs/TICKET-FORMAT.md
effort:<S/M/L/XL> label and priority set
Exactly one safety:* label (required before drain can pick up the bead)

Scope check

Before completing DoR, the agent checks each candidate’s size:

More than 3 files for unrelated reasons → flag for decomposition
Environment context exceeds 4 sentences → flag
Happy path has more than 1 major branch point → flag for splitting
Effort estimate is XL → recommend breaking into smaller beads

Candidates that fail scoping are decomposed on the spot (bd create for child beads) rather than allowed through as-is. This is the cheapest place to catch oversized work.

Epic assignment and dependency wiring

For each bead being groomed, the agent assigns it to an epic (bd update <id> --parent <epic-id>) or deliberately marks it loose:


bd note <id> "Deliberately loose: no epic fit"

Loose is a valid first-class state — it is not incomplete grooming. Never assign a bead to a marginally-related epic for tree visibility.

Dependencies are wired at the true bead level only:


bd dep add <blocked-bead> --blocked-by <blocker-bead>

Never use bare bd link. Never create epic-to-epic edges directly — those are a derived visualization of bead-level cross-epic blocking edges, not an input you configure.

After any dependency wiring:


bd dep cycles --json   # must return []
bd ready               # eyeball that intended beads surfaced

Anti-Goodhart posture

The tech tree (.gembaflow-boards/techtree.html) is a projection, never a target. Never add or remove dependencies to make the DAG look tidier, more balanced, or more strategic. If the tree looks wrong, the only legitimate fix is correcting data that is actually wrong. Edges that exist to satisfy aesthetics corrupt the dependency graph and cause bd ready to exclude or include the wrong beads.

Icebox and stale beads

Beads that are out of scope for the current phase are deferred:


bd update <id> --status=deferred

Stale beads (no activity in 30+ days) are flagged for review. The agent never silently deletes beads — it surfaces them and asks for a disposition.

Board projections

.gembaflow-boards/{kanban,techtree}.html regenerate automatically via the Stop and SessionStart hooks after any bd write. The kanban is the headline board (the tech tree is experimental). Use /board-refresh if you need the projections updated mid-session without ending the session.

The projections are read-only — you cannot drag cards or edit them in a UI. All mutations go through bd commands in the operator terminal.

Output

The agent reports:

Backlog health metrics
Beads that became surfaceable in bd ready this session
Beads flagged for refinement
Scoping issues flagged for decomposition
Dependency cycles found (must be zero before the report ends)
Recommended next grooming cadence


---

**Result:** Backlog groomed
Became ready: 4 beads (gs-a1, gs-a2, gs-a3, gs-a4)
Backlog remaining: 8 beads
Flags: 2 beads need refinement (gs-b1, gs-b2)
Dependency check: bd dep cycles --json → []
Boards: refreshed automatically (hook)

/create-ticket — upstream; this command grooms what /create-ticket produced
/sprint-status — the read-only sibling; observes bead health without modifying anything
/work-ticket — downstream; picks up beads that bd ready now surfaces
/drain — autonomous variant that runs /work-ticket against the full ready snapshot overnight

Canonical spec: .claude/commands/groom-backlog.md