# Briefs Health

> Audit the briefs for a project when it feels muddled, stalled, or you've lost the thread. Reports what's out of shape and asks one question to drive reprioritization.

- Skill: `naxoc/briefs-health` (Agent Skill)
- Install (CLI): `npx skillmds@latest add naxoc/briefs-health`
- Raw SKILL.md: https://api.skillmd.com/api/skills/naxoc/briefs-health/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: naxoc (https://skillmd.com/u/naxoc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/naxoc/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.