/done — close a journal entry

Contract

Goal. Be the single closure entry point for every kind of journal entry this repo keeps. When a piece of work lands — a followup is done, an upstream-version signal is acknowledged or completed, the in-flight cursor shipped — the user types /done <thing> and the skill detects what kind of thing it is, finds the existing entry in the right journal (docs/progress.md or docs/signals-backlog.md), and applies the closure writes (bullet-remove + Recently-shipped move / signal-field flip / cursor promote) directly via Edit — no per-invocation diff-then-confirm gate (see Success criteria). Companion to /log: same journal system, different moment — /log captures NEW entries; /done closes EXISTING ones. It ships at the Sonnet tier rather than the cheapest because the signals-backlog.md dual-lifecycle — acknowledging a perpetual upstream watch vs completing a one-off signal — carries a counterintuitive rule (acknowledge is not completion; the auto-fetched last_checked field is off-limits) that rewards careful instruction-following over a tier that just does the "obvious" closure.

Inputs. $ARGUMENTS is <slug-or-keyword>, required. The literal token running is a reserved keyword that maps to the ## Currently running cursor and short-circuits the polymorphic match. Otherwise the input is matched polymorphically, first hit wins: a case-insensitive substring against open-followup bullet text in docs/progress.md, then an exact ### <slug>: heading match in docs/signals-backlog.md. If $ARGUMENTS is empty, the skill lists the top pending followups + the action_pending signals and asks which one. If the input matches more than one entry, the skill surfaces the candidates and asks — it never silently picks.

Outputs.

• The closure writes applied directly via Edit: for a followup — remove the bullet from ## Open followups (restore the (none) placeholder if the area empties), prepend a dated - YYYY-MM-DD — <text> entry to ## Recently shipped, bump last-updated:; for a signal — the auto-managed-vs-manual field updates (see Success criteria); for running — promote the cursor paragraph to a dated ## Recently shipped bullet, clear the cursor body, bump last-updated:.
• A one-line confirmation after the writes, so the user can see what landed.
• A verification pass (npm run lint:docs) confirming the file stays lint-clean (staleness gate + signals schema).
• No commit. /done is edit-only — it surfaces "edited <path> — review and commit when ready." The commit (carrying the actual code change that closed the work) is the user's call.

Success criteria.

• The closure is applied directly via Edit — no per-invocation diff-then-confirm gate. The skill is dead-simple closure; trust it, and if outputs go wrong, run /audit-skill done to fix the SKILL.md. Per-invocation confirmation is the wrong corrective loop for systematic issues — it adds friction every session and the user can always git reset --soft HEAD~1 to recover a rare mis-closure.
• Closure writes reflect reality, not optimism. If the journal claim depends on the work actually shipping, don't /done it until the work has landed.
• Closed followups are REMOVED from ## Open followups (moved to ## Recently shipped), never annotated in place with a ✅-style marker — git is the shipping history; the open section tracks open work.
• Auto-managed signals (jellyfin-server-stable, jellyfin-server-rc, roku-os) are ACKNOWLEDGED — clear the stale flag, set latest_acknowledged to the current latest_upstream, flip action_pending→watching if set — and are NOT flipped to completed (they are perpetual), and last_checked is left untouched (it is the aggregator's field). Only manually-managed signals flip to completed.
• Disambiguation surfaces candidates and asks ONLY when the input genuinely matches more than one entry; unambiguous pointers apply directly. The skill never silently picks among ambiguous matches, but it also doesn't gate unambiguous ones with a confirmation prompt.
• Pure local-file edits — the only remote-ish call is the lint verify, which reads but never writes.

Failure modes to avoid.

• Pre-marking optimistically. "I think it shipped, let me close it." If the closure depends on the work landing, wait until it has — a premature /done is a future audit failure.
• Flipping a perpetual signal to completed (or touching last_checked). The signals dual-lifecycle trap: for an auto-managed slug, /done means "I reviewed the new upstream" — acknowledge, don't complete; never bump last_checked (the aggregator owns it). Flipping it to completed corrupts the watchlist that drives /catchup banners and /server-upgrade.
• Replacing a closed followup with a ✅-marked line. Closed work is REMOVED from the open section and moved to Recently shipped. A ✅ annotation in the open list breaks the open/closed distinction and fails the docs-lint.
• Silent ambiguous-pointer resolution. When the input matches multiple candidates, surface them and ask. Picking the first match, the most recent, or the highest-priority is silent corruption — the user knew which one they meant.
• Adding friction prompts in place of audit-driven fixes. If closures consistently land wrong, the corrective loop is /audit-skill done → fix the SKILL.md → re-dogfood — NOT bolting a per-invocation confirmation prompt back on. Per-session friction is a worse pathology than rare mis-closures (git reset --soft HEAD~1 recovers those).
• Committing from inside /done. The skill is edit-only; the commit (with the code change that closed the work) is the user's call. Bundling a journal closure into the skill's own commit is the wrong shape here.
• Editing progress.md / signals-backlog.md with raw Write/Edit outside this skill. /done (closure) and /log (capture) are the only sanctioned write paths for these journals.

When NOT to use.

• The work hasn't actually shipped yet — capture it via /log followup first; close via /done later when it lands.
• An open GitHub issue closed in the PR → gh issue close <N> (or "Closes #N" in the commit body). /done doesn't touch GitHub state.
• A tech-debt entry to remove → /tech-debt-scan walks tech-debt entries one-by-one and applies removals.
• A decision entry to revise → decisions are append-only; file a new /log decision with **supersedes**: <old-slug> (which flips the old entry to superseded).
• The capture is a NEW entry, not a closure of an existing one. That's /log, not /done.

Implementation

The completion side of the capture/completion ritual. /log adds; /done closes. Operates on progress.md (followups → recently shipped) and signals-backlog.md (status flip). Tech-debt removal stays via /tech-debt-scan; GitHub issues stay via gh issue close.

Auto-close-loop note: the running cursor close-loop fires automatically when a PR merges to main via .github/workflows/journal-sync.yml. You only need to invoke /done running manually when the work shipped via a path that bypasses the workflow (direct push to main, squash-merge with a heavily edited title, the workflow being skipped by label). For the normal /pr → review → merge path, the cursor close happens for you.

Inputs

$ARGUMENTS: a slug or keyword identifying what's done. Must be present.

• For followups: the input is matched as a case-insensitive substring against bullet text under ## Open followups. So /done aggregator perf matches - Verify aggregator perf on slow networks.
• For signals: the input is matched as an exact ### <slug>: heading in signals-backlog.md. So /done jellyfin-server-stable matches ### jellyfin-server-stable: Jellyfin server stable channel.

If $ARGUMENTS is empty: list pending followups (top 5) + signals with status: action_pending (top 5) and ask which one.

The capture rule

Same as /log: this skill is the ONLY sanctioned write path for docs/progress.md and docs/signals-backlog.md completion edits. Agents do NOT use raw Write / Edit on those files outside this skill — closures flow through /done, captures through /log. Within the skill, the closure applies directly (no per-invocation confirmation prompt); systematic wrongness is fixed via /audit-skill done, and git reset --soft HEAD~1 recovers a rare mis-closure. (A sub-agent invoking /done is the exception — it surfaces the proposed edit and never auto-applies, because its context dies at exit; see Sub-agent invocation.)

Step 1 — Match polymorphically

The literal token running is a reserved keyword that maps to the Currently-running cursor (Step 2-R below); it short-circuits the polymorphic match. Otherwise, search in this order; first hit wins:

Running keyword (progress.md ## Currently running)

If $ARGUMENTS is exactly the token running (case-insensitive, optionally with trailing whitespace): proceed to Step 2-R. Skip the followup / signal searches entirely — running never matches a followup bullet by accident because it isn't typical bullet text, and reserving it as a keyword keeps the contract clean.

Followup match (progress.md)

grep -in '<keyword>' docs/progress.md

Restrict matches to lines BETWEEN ## Open followups and the next ## heading. Skip any (none) placeholder lines. If exactly 1 bullet matches, proceed. If 0 matches, fall through to signal match. If >1 matches, surface all matches and ask which one.

Signal match (signals-backlog.md)

grep -n '^### <slug>:' docs/signals-backlog.md

Exact match on the ### <slug>: heading. If 1 hit, proceed. If 0 hits, fall through to the no-match branch.

No match

Tell the user no journal entry matched, then suggest:

• For internal tech debt: /tech-debt-scan (handles add + remove for docs/architecture/tech-debt.md)
• For GitHub issues: gh issue close <N> (the closed issue is its own audit trail)
• For arbitrary file edits: just edit the file directly — /done is journal-scoped

Step 2-F — Followup completion (when a followup matched)

Compose the diff:

1. Remove the matched bullet from the area subsection under ## Open followups. If removing the bullet leaves the area subsection empty, restore the (none) placeholder line. If the bullet was the LAST line of the file, make sure the file still ends with a single newline — removing a final line takes its newline with it, and markdownlint's MD047 fires on the next edit rather than on this one, so the breakage surfaces attached to unrelated work.
2. Prepend a new bullet at the top of ## Recently shipped: - YYYY-MM-DD — <followup text> using today's ISO date and the followup's text verbatim.
3. Bump last-updated: in the frontmatter to today.

Verbatim has one exception, and it is not a style call. A followup that states a PROBLEM rather than a deliverable — "X has no sanctioned way to do Y", "Z cannot be verified" — reads as a live complaint when copied verbatim under a today's date, i.e. it asserts the problem still exists on the very day it was fixed. That fails this skill's own "closure writes reflect reality, not optimism" criterion in the honest direction rather than the optimistic one, but it fails it. For those, write a one-line RESOLUTION naming what shipped and the followup it closes, which is the shape docs/progress.md already uses — see its run-meta.json and registry-restore entries. Deliverable-shaped bullets ("Expand automated store screenshots to all ~99 locales") are unaffected: verbatim is already the resolution, and rewriting them would just be drift.

Apply directly via Edit (no confirmation prompt — trust the skill; /audit-skill done is the corrective loop for systematic issues).

Step 2-S — Signal completion (when a signal matched)

Two distinct lifecycles depending on whether the signal is auto-managed or manually-managed.

Auto-managed slugs (jellyfin-server-stable, jellyfin-server-rc, roku-os)

These signals are perpetual — the upstream isn't going to stop existing. /done here means "I've reviewed the new upstream version", which clears the stale flag. It does NOT flip status to completed.

Compose the diff:

1. Find the ### <slug>: block in signals-backlog.md.
2. Read the row's current **latest_upstream**: value.
3. If **latest_acknowledged**: already equals **latest_upstream**:, tell the user "nothing to acknowledge — already up to date" and stop.
4. Otherwise update fields:
   • **latest_acknowledged**: → the current **latest_upstream**: value
   • If **status**: is action_pending, flip to watching (the work that the action_pending tracked has presumably shipped).
5. Bump file frontmatter last-updated: to today.

Note: this skill does NOT bump **last_checked**: — that's the aggregator's territory and reflects "last time we asked upstream", not "last time we acknowledged". Don't overwrite it.

Manually-managed slugs (any other slug added via /log signal)

The original close-loop lifecycle — flip status to completed and the row stays as a historical record.

Compose the diff:

1. Find the ### <slug>: block in signals-backlog.md.
2. Update fields:
   • **status**: → completed
   • **latest_acknowledged**: → the current **latest_upstream**: value (so the historical record is consistent)
   • Optionally update **latest_upstream**: and **current**: if the user provides new values; otherwise leave unchanged.
3. Bump file frontmatter last-updated: to today.

Apply directly via Edit (no confirmation prompt — trust the skill; /audit-skill done is the corrective loop for systematic issues).

Note: a signal in completed status stays in the file as a record of past work. If the file accumulates many completed rows over time, archive them by hand (move to a "## Completed" subsection) — not yet automated.

Step 2-R — Running cursor completion (when $ARGUMENTS == running)

The in-flight cursor shipped — promote it to ## Recently shipped and clear the cursor.

Compose the diff:

1. Read the current paragraph between ## Currently running and the next ## heading in docs/progress.md. If the paragraph is empty (already cleared), tell the user "no Currently-running cursor to close" and stop — don't pad Recently shipped with a blank entry.
2. Prepend a new bullet at the top of ## Recently shipped: - YYYY-MM-DD — <currently-running text> using today's ISO date and the paragraph verbatim. If the paragraph is multi-line, collapse internal whitespace to single spaces so the bullet stays one line.
3. Replace the ## Currently running body with a blank-line pair (clears the cursor; leaves the section heading intact).
4. Bump last-updated: frontmatter to today.

Apply directly via Edit (no confirmation prompt — trust the skill; /audit-skill done is the corrective loop for systematic issues).

If the in-flight work was multi-step and only part of it shipped, ask the user: "Promote the whole cursor to Recently shipped, or replace it with a follow-on description?" The latter is /log running "<new text>" — /done running only handles full closure.

Step 3 — Verify

npm run lint:docs

Both edits should keep the file lint-clean: progress.md staleness gate passes (last-updated bumped to today); signals schema validator passes (all required bullets still present, valid status enum).

Step 4 — Don't commit

/done drafts + applies but does NOT git commit. Surface "edited <path> — review and commit when ready." The commit (with the actual code change that closed the followup or moved the signal) is the user's call.

Sub-agent invocation

Read .claude/skills/done/SKILL.md and surface the proposed completion edit for $ARGUMENTS=; do NOT apply the edit — return the proposed diff for the parent to confirm.