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 ## Up next or ## Blocked?

BACKLOG.md

• ## Up next: More than 3 items? Flag it — needs pruning. Items that are actually blocked but not labeled as such?
• ## Blocked: Any items missing a reason or date for when they were blocked? Anything that might be unblocked by now?
• ## Backlog: Is it so long it's become a graveyard? Flag if items look ancient or irrelevant.
• # Done: Growing fast but PROGRESS.md isn't? May mean completed tasks aren't being properly logged.
• 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   ⚠ Up next has 6 items — needs pruning
             ⚠ "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:

• "Up next has 6 items. Which 3 actually matter before the deadline?"
• "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.