Grooming Backlog

Grooming Backlog

Use this skill when the backlog needs a grooming pass. Grooming moves tasks from ambiguous, underspecified, or stale states into a ready state where an agent can pick them up and work them without needing additional decisions or clarification.

Goals

• Every Open task is either Pending (ready to work), Blocked (blocker documented), or has a clear next action.
• Every Pending task has all product and design decisions recorded.
• Every Blocked task documents what it is blocked on and what would unblock it.
• Dependencies (depends_on and exec_plan fields) are accurate and complete.
• Task files are self-contained — no open questions in the body or comments.
• Generated indexes are regenerated via ahm index.

When to groom

• Before a sprint or work cycle planning.
• When the backlog has accumulated stale Open or Blocked tasks.
• After a block of implementation work (to rebalance the queue).
• Any time an agent reports a task is too vague to work.

Workflow

1. Inspect the queue

# Quick ready queue
ahm task ready

# Active tasks not ready
ahm task blocked
ahm task list --status Open

# Label vocabulary and counts
ahm task labels

If ahm is unavailable, read .agents/.tasks/index.md as the fallback queue artifact and inspect the relevant files under .agents/.tasks/active/.

2. For each task that is not Completed or Cancelled, audit:

Front matter invariants:

• status is one of: Open, Pending, In Progress, Blocked, Tracking.
• priority is set and uses the project's priority scale.
• effort is set and uses the project's effort scale.
• labels include at least one type:* and one area:* label.
• depends_on references real task IDs. A task only depends on another if the dependency is genuinely blocking — not just "related to."
• exec_plan references an existing ExecPlan file when the task is L or XL, or documents that no plan is needed (-).

Decision completeness:

• If the Summary or Fix Direction presents alternatives (e.g., "use X or Y"), record which alternative was chosen and why. If none is chosen yet, flag the task as Blocked and document what decision is needed.
• If the task references external inputs (issues, design docs, conversations) that have since been resolved, capture the resolution in the task body.
• If the task is an L or XL without an ExecPlan, flag it.

Body quality:

• Acceptance Notes checklist should not contain TODO placeholders or unchecked items that should have been decided before work begins.
• Relevant files, modules, and commands listed in the task are still valid (paths exist, modules still in use).
• The task body does not contain "ask the user" or "decide later" phrasing without a corresponding Blocked status and blocker note.

Dependency graph:

• For each depends_on entry, check that the dependency exists and is not itself Blocked or Open. If a dependency is blocked, the depending task should also be Blocked with a note referencing the dependency.
• For each task that other tasks depend on, check that its status reflects that it is a dependency (e.g., if task 102 and 103 depend on 101, 101 should not be moved to Cancelled without unblocking or updating 102 and 103).

3. Fix what you can directly

• Use ahm task accept, ahm task dep add, ahm task dep remove, ahm task cancel, and other ahm task ... commands when they express the needed change.
• Update front matter status, priority, effort, labels, depends_on, or exec_plan by hand only when no command fits the change.
• Record decisions in the task body (add a ## Decision section when recording a resolved choice).
• Remove stale TODO placeholders from Acceptance Notes when the question has been answered.
• If a task is superseded, obsolete, or no longer relevant, cancel it with ahm task cancel <id> --reason <text>.

4. Flag what needs human input

When a task needs a product, design, or architecture decision that an agent cannot make alone:

1. Set status: Blocked in the task front matter.
2. Add or update the blocker note at the top of the task body:

   ## Blocker
   Awaiting decision on [describe what]. See [reference].
   

3. Do not leave the task Pending with undocumented open questions.

5. Regenerate indexes after manual edits

After manual edits:

ahm index

Verify no pending writes:

ahm --dry-run index  # should produce no output