Briefs Done

Briefs: Close Out a Task (or Checkpoint It)

The completion ceremony. /briefs-work sessions may tick every checkbox, but a task only finishes here — deliberately, after the user has reviewed the work. This skill is the only writer of PROGRESS.md.

Two modes:

• Close-out (default): the whole task is done — review, archive, reset.
• Checkpoint: a reviewed-and-committed slice mid-task (e.g. the backend half before the frontend starts). Same review + PROGRESS entry, but CURRENT.md stays active and nothing is reset.

Worth running on a strong model: step 2 is a review pass where plan-aware intelligence catches what the executing model missed.

Step 1: Preconditions and mode

Find the briefs folder (.claude/briefs-path → .briefs/ → ask). Read CURRENT.md. 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.

• No active task → say so, done.
• If code was written, ask for the commit SHA(s) — or offer to read them from git log and confirm with the user. If the work isn't committed yet, stop: "Review and commit first, then rerun /briefs-done." The commit is the proof the user actually looked at it; no SHA, no archive. (Non-code tasks — docs, research, ops — skip this gate; instead confirm the user has seen the result.)
• Pick the mode. If the user said "checkpoint" (or gave a SHA for a subtask), it's a checkpoint. If # Task list still has unchecked items, ask: "Task list isn't finished — checkpoint this slice, or close out anyway?" Only a fully-ticked list defaults to close-out.

Step 2: Review against the plan

In checkpoint mode, scope this review to the committed slice — the ticked items the SHA(s) cover — not the whole plan.

Compare what was actually built (the diff of the named commits, or the produced artifacts) against CURRENT.md's # Approach:

• Every settled decision honored? Every task-list item actually present in the diff, not just ticked?
• Deviations in # Log — reasonable? Any undeclared deviations in the diff?
• ## Hard rules respected?

Report findings as short bullets. If something real is off, stop here — don't archive a task with known gaps. The user decides: send it back to /briefs-work, or accept the gap explicitly (then record it in the PROGRESS entry as a known limitation).

If it's clean, say so in one line and move on.

Step 3: Review notes

Skim # Review notes in CURRENT.md — anything a reviewer or future reader needs (surprising changes, migration notes, manual test steps) gets folded into the PROGRESS entry in step 4. If the user asks for a PR description, build it from these notes: what changed, why, key decisions, what to test manually. (Draft text only — never push, never create the PR.)

Step 4: Write the PROGRESS.md entry

Checkpoint mode: add a short dated entry at the top of PROGRESS.md — ## <Task name> — checkpoint: <slice> (YYYY-MM-DD HH:MM) with the Commit: line and a few lines on what the slice covers. Note the SHA in CURRENT.md's # Log too, then stop here — no BACKLOG sweep, no reset; the task continues. The final close-out entry summarizes the whole task and references its checkpoints rather than repeating them.

Get the timestamp from the clock, not from memory: run date +"%Y-%m-%d %H:%M" and use what it returns. A model guessing at the time writes a plausible wrong one, which is worse than omitting it — entries are read later to reconstruct what happened in what order.

Close-out mode: add a dated entry at the top of PROGRESS.md, preserving the backstory — this is the project's long-term memory, and CURRENT.md is about to be wiped. Use headings so entries fold in Obsidian:

## <Task name> (YYYY-MM-DD HH:MM)
Commit: <sha(s)>
<What was done and why — including the problem/bug backstory from # Context.>
**Scope:** <numbers: files changed, rows affected, endpoints added…>
**Key decisions:** <why X over Y — lift these from ## Decisions (settled)>
**Deviations:** <from # Log, if any — with the accepted-gap notes from step 2>
**How it was tested:** <the fixtures and commands, copy-pasteable>

Carry the test instructions across. If CURRENT.md's Approach names fixtures or commands — specific IDs, a reset recipe, a verification query — copy them into the entry as a runnable block, with the one-line reason each fixture was chosen:

just --justfile=<path> reset
<command> 4821   # the mixed case: 4 images, 4 text blocks, 1 dropped
<command> 5107   # regression — output must stay 3,908 bytes

They are expensive to rediscover: someone picked those IDs because they exercise a specific path, and CURRENT.md is about to be wiped. Include the expected result where there is one — "3,908 bytes", not "check it looks right" — so the next person can tell pass from fail without rerunning the original reasoning. Note any path the fixtures could not cover, and why.

Anything in # Log or the session that's reusable beyond this task (gotchas, commands, references) goes to NOTES.md instead of dying with the reset.

Step 5: Sweep BACKLOG.md

• Delete the finished item. Do not copy it to a # Done list: PROGRESS.md is the record of completed work, and a second hand-maintained copy in BACKLOG.md only drifts from it.
• Ask whether anything deeper in # Backlog should move up now that this is finished.
• Backlogs come in two shapes. Newer ones write each item as a ## heading with a *tag* line; older ones use - [ ] checkbox items with indented continuation lines. Treat both as items. Don't convert the file here — a close-out is the wrong moment for text surgery on months of context. If it is the older shape, add one line at the very end of your report: "BACKLOG.md uses the older checkbox format — /briefs-health can convert it." Say it once and drop it; a repeated nag is worse than the old format.

Step 6: Reset CURRENT.md

Replace CURRENT.md with the blank skeleton:

Working on: **<nothing — pick a task with /briefs-plan>**
Branch: 

# Context

# Approach

# Task list

# Log

# Review notes

Then tell the user what was archived. If queue/ has staged plans, list them and offer to promote one into CURRENT.md now (move the content, delete the queue file, remove the *Planned … → queue/<slug>.md* line from the backlog item now that the plan is live, add the task to BACKLOG.md's # Backlog if missing) — noting that the next /briefs-work session re-verifies the plan against current code before executing. Otherwise, if the top of # Backlog has an obvious candidate, suggest /briefs-plan for it.

File rules for this skill

• PROGRESS.md: this skill is its sole writer.
• CURRENT.md: full access — consolidate, then reset.
• BACKLOG.md: delete the finished task; reorder # Backlog only with the user's answer, not unilaterally.
• NOTES.md: may append learnings rescued from the reset.