Briefs Groom

Briefs: Groom the Backlog

A backlog rots quietly. Items ship without being removed, two people write the same item twice, a "highest-value outstanding" note stays after the work landed, and the top of the list stops matching what you are actually doing.

This walks the list with the user and fixes that. It is a working session, not a report — expect to edit BACKLOG.md several times.

Not the same as /briefs-health. Health asks "is this system working?" — am I closing tasks, planning before coding, letting a queue rot. Groom asks "is this list still true?". Run health when a project feels stalled; run groom when the backlog has grown long enough that you skim past it.

The honest constraint

You have less context than the backlog does. These items were written across weeks by sessions that had read the code. A fresh session cannot tell "stale" from "still true" by reading alone, and guessing produces confident nonsense that costs the user more than leaving the item.

So: verify what is verifiable, ask about the rest. Never delete an item because it looks done. Say what you checked and what you found, then let the user decide.

Step 1: Read

Find the briefs folder (.claude/briefs-path → .briefs/ → ask). Read BACKLOG.md, PROGRESS.md, and CURRENT.md.

PROGRESS.md is the useful one — it is evidence of what actually shipped, with commit SHAs. Most of the checks below lean on it.

Count the items and say so before starting: *"38 items in # Backlog, 5 in

Blocked. Working through them."*

Step 2: The checks worth making

Run these in parallel where you can. Each produces a finding or nothing; none produces a judgement on its own.

Shipped but never removed. For each item, look for its subject in PROGRESS.md — by commit SHA if the item names one, otherwise by the files and symbols it mentions. A hit is strong evidence. State it as evidence, not a verdict: "'Paragraphs as a field type' — PROGRESS has four entries covering reader, rich text, images and quotes. Looks shipped. Remove?"

Self-contradicting. An item whose body says something the title does not. Bodies get appended to over weeks: a title claiming "highest-value outstanding" above a body listing four merged commits is the common shape. These are findable by reading and are worth flagging every time.

Verifiable claims. An item naming a file, class, method or flag can be checked in seconds — does SourceMap::warm() still exist, is field_paragraphs still in that skip list, does that line number still say what the item claims? Check a handful, especially for older items. Report what you found either way; a confirmed-still-true item is a useful result.

Duplicates and overlaps. Two items describing the same work, or one item that is really a sub-part of another. Visible from the text alone, so this is safe to be confident about. Propose a merge and show both bodies.

Blocked too long. Items under # Blocked with no date, or blocked more than a few weeks. Ask whether the blocker is still real — publishers answer, decisions get made, and nobody goes back to update the item.

Order versus reality. Compare the top few items against PROGRESS.md's recent entries and CURRENT.md. If the last several completed tasks are all one theme and the backlog's top item is unrelated, either the order is wrong or the top item is being avoided. Name the pattern; do not diagnose it.

Graveyard tail. Items untouched for a long time that nothing references. Worth asking about in a batch rather than one at a time: "These six are from July and nothing since has mentioned them — still real?"

Step 3: Work through it with the user

Batch by finding type, not by item. "Four items look shipped — here they are" beats forty separate questions. The user can answer a batch in one message.

Order the batches by how much they shrink the list: shipped items first, then duplicates, then blocked-too-long, then the tail.

Apply edits as you go, once per batch, rather than collecting everything for one big rewrite. If the session is interrupted, the work so far is saved.

Copy the file before the first edit — cp BACKLOG.md /tmp/BACKLOG.bak. This skill deletes things.

Step 4: Reorder, once

Only after removals — a shorter list is easier to order. Propose a new order for the top five or so, with a sentence of reasoning each, and let the user correct it. Leave the tail alone; ordering a graveyard is busywork.

Step 5: Report what changed

Short, and in counts:

38 items → 29
  removed 5 as shipped (verified against PROGRESS.md)
  merged 2 pairs
  moved 2 to # Blocked
  reordered the top 5

If anything was left unresolved because you could not verify it, say so explicitly. An unanswered question is a fine outcome; a silently skipped one is not.

What this skill does not do

• Does not plan. If an item turns out to be the next task, say so and suggest /briefs-plan — do not start designing it here.
• Does not touch CURRENT.md. An active task is not backlog.
• Does not write PROGRESS.md. Only /briefs-done writes there. If grooming finds work that shipped without being archived, that is worth naming, but the fix is a /briefs-done run, not an entry invented after the fact.
• Does not delete on its own judgement. Every removal is something the user agreed to.