Briefs Health

Briefs: Health Check

Run this when a project feels muddled, stalled, or you've lost the thread. It reads the briefs and gives you an honest picture of the state — then helps you reorder, not just report.

Step 1: Find the briefs folder

Check these in order:

• Read .claude/briefs-path for a saved path
• Check if .briefs/ exists in the project root
• If neither works, ask the user for the path

Step 2: Read all four files in parallel

CURRENT.md, BACKLOG.md, PROGRESS.md, NOTES.md — plus any staged plans in queue/.

If the folder has a PLAN.md but no BACKLOG.md, it predates the rename — treat PLAN.md as BACKLOG.md and offer to mv it.

Step 3: Audit each file

CURRENT.md

• Is there an active task? If empty or vague, flag it.
• Does it look stale? Signs: no concrete next move, multiple tasks crammed in, "TODO" or "TBD" with no follow-up, # Log silent while the task claims to be in flight.
• All task-list boxes ticked but the task still active? It's awaiting review — suggest the user review, commit, and run /briefs-done so it gets archived instead of rotting here.
• Non-trivial task with an empty # Approach? Flag it — suggest /briefs-plan before more work happens ad hoc.
• Is the active task actually reflected in BACKLOG.md's # Backlog or # Blocked?

BACKLOG.md

• # Backlog: items that are actually blocked but not moved to # Blocked? Items whose title no longer matches what the body says? (Items may be ## headings or older - [ ] checkboxes — both are fine, but flag a file that mixes the two.)
• # Blocked: Any items missing a reason or date for when they were blocked? Anything that might be unblocked by now?
• # Backlog: long enough that you would skim past it, or full of items nobody has touched in weeks? Don't try to groom it here — say so and suggest /briefs-groom, which walks the list item by item and can verify claims against the code.
• Format: does the file use the current shape — sections as #, items as ## headings with a *tag* line — or the older one, with a # Backlog title, a ## Up next section, and - [ ] checkbox items? Both work; report which, and offer the conversion in step 6. A file that mixes the two is worth fixing regardless.
• # Done: newer briefs keep this as a one-line pointer to PROGRESS.md. If the file still lists completed items here, check they are also in PROGRESS.md — a hand-maintained second copy drifts.
• Missing any of these sections entirely? Note it.

PROGRESS.md

• Recent entries? If CURRENT.md shows active work but PROGRESS.md hasn't been touched in a while, tasks are probably finishing without /briefs-done — completed work is evaporating instead of being archived.

queue/ (staged plans)

• Any plan whose "planned against commit" stamp is far behind HEAD, or that's weeks old? Flag likely plan rot — it may need a /briefs-plan refresh instead of promotion.
• A queue growing while nothing gets promoted is planning as procrastination — worth naming.

Step 4: Report

Keep it tight. For each file: one line if healthy, one line + specific issue if not. Use this format:

CURRENT.md   ✓ Active task: [name]
BACKLOG.md   ⚠ 3 items are blocked but still under # Backlog
             ⚠ "News category fix" blocked since [date?] — reason missing
PROGRESS.md  ✓ Last entry [date]
NOTES.md     ✓ (or "empty — fine if nothing to record")

Step 5: Ask one question

Don't dump a list of things to fix. Pick the most important problem and ask one focused question to resolve it. Examples:

• "Three items are really blocked on the publisher. Move them to # Blocked?"
• "CURRENT.md has been on 'investigate date mismatch' for a while with no concrete next move — do you know what's blocking it?"
• "Three items in Blocked have no reason logged. Want to go through them quickly?"

Then wait for the answer before suggesting any edits.

Step 6: Offer the format conversion, if it applies

Only if step 3 found the older format, and only after the step 5 question is settled. One sentence, not a sales pitch:

BACKLOG.md uses the older checkbox format. Want me to convert it to headings?

If they say yes:

1. Copy the file first — cp BACKLOG.md /tmp/BACKLOG.bak. The conversion is text surgery on a file that may hold months of context.
2. Drop the redundant # Backlog title; promote ## sections to #.
3. Turn each - [ ] item into a ## heading. The title is the leading **…** run, which may wrap across several lines — join the item's lines before extracting it, or you will swallow the whole body into the heading.
4. Move the **(tag)** prefix onto its own *tag* line under the heading.
5. De-indent the continuation lines by six spaces.
6. Add a blank line before each **Bold lead-in** that starts a new point — these were visual breaks inside a bullet and run together as flowing prose.
7. Capitalise an item body that now starts mid-sentence, where the title and prose used to be joined by an em dash.
8. Fold any # Done list into a pointer to PROGRESS.md — but check every entry is actually recorded there first, by commit SHA rather than by title. Titles get reworded between the two files; SHAs do not.

PROGRESS.md has the same shape problem and is a much simpler fix: drop its # Progress title and promote every ### Entry to ##. Offer it at the same time. Skip fenced code blocks — a # comment on a shell line is not a heading, and shifting it corrupts the command.

Then verify before saying it worked: the item count matches, no - [ ] remains, no heading contains **, and the section structure is what you expect. Report the counts. If anything looks wrong, restore from the copy — do not try to patch a mangled conversion.