compound-refresh

Audit the knowledge stores against the current codebase and prune what no longer earns its place. Two stores: the project's AGENTS.md, always, and docs/solutions/ when the loop config enables it. The loop config is docs/agents/cantrips-loop.md; when that doc is absent, the solutions store is off. The opt-in docs/adr/ store stays out of scope by design — supersession is its own hygiene mechanism. Every change is gated on the user, or on a deputy engaged in their place.

Scope

An argument narrows the sweep to matching docs/solutions/ docs — try it as a filename, then a frontmatter area/tags value, then a content keyword. No argument → every doc plus AGENTS.md. AGENTS.md is in scope on every run: when the solutions store is off, or no doc matches the argument, say so in one line and audit AGENTS.md alone.

Audit docs/solutions/

The format contract is ../compound/solutions-format.md. For each doc in scope, cross-check its claims against the current code — cited paths and names still exist, the fix still matches how the code works today, snippets reflect the current implementation — and against its sibling docs for overlap and contradiction. Verdict per file:

• Keep — still accurate and useful. No edit: reported as reviewed, zero churn.
• Update — the problem is still real but the doc drifted, from moved paths and renamed names up to a fix the current code now contradicts. On approval: evidence-backed in-place edits; on a contradicted fix, rewrite the doc to the current truth and present it as the rewrite it is.
• Consolidate — two docs overlap so heavily a maintainer must read both to get the truth. On approval: merge unique content into the canonical (broadest, most current) doc, delete the other.
• Delete — both the implementation and the problem domain are gone, or the doc is fully redundant. On approval: delete the file — git history is the archive.

Judgment rules:

• Match docs to reality, never the reverse. When code and doc disagree, the doc changes; whether the code should have changed is outside this skill.
• Age alone is clean. A two-year-old doc that still matches the code is a Keep; age only prompts a closer look.
• Unverifiable is not false. A claim the repo cannot corroborate — a schema fact, an operational practice, an environment behavior — is not thereby wrong; repos rarely witness their own operations. Never delete content, or strip it during a merge, solely because no in-repo artifact confirms it. Act only on contradiction, where the code demonstrably does otherwise; an unverifiable-but-plausible claim is a Keep with the verification gap noted in the report.
• A met retirement condition is contradicting evidence, not age. Where a doc declares retire_when, check the condition through the source it names; the result and the date checked land in the report, never in the doc. A met condition reaches the gate as a contradiction, and while the code still carries the workaround the verdict is Update: the doc rewritten to say its premise is gone. An unmet condition decides nothing on its own; one whose source cannot be reached is recorded as unchecked, a Keep with the gap noted.
• Redundant needs a quoted artifact. A doc is fully redundant only when a named in-repo artifact states its reasoning in its own text — a test, a code comment, AGENTS.md, a sibling doc — and the verdict quotes it; topical overlap is not coverage. Reasoning only partly recoverable → Update instead: cut what the artifact states, point at it in one line, and keep the measured facts, cross-file invariants, and rejected alternatives nothing else records.
• Shared code is not shared problem. Two accurate docs on different sub-problems stay separate even when they cite the same file.
• Contradictions between docs outrank staleness — they actively mislead. Resolve them first, via Consolidate or Update.
• Before a Delete, check the problem domain and the inbound links. Implementation gone but the domain still alive (the app still handles what the doc addresses) → Update to the current truth instead. Other markdown citing the doc substantively (relying on it for content not stated inline) → Update instead; decorative "see also" citations are cleaned up alongside the delete.
• Skip cosmetic churn. Typos and wording polish are edits without evidence value.

Audit AGENTS.md

Read the project's AGENTS.md (or the substantive file when one of AGENTS.md/CLAUDE.md merely includes the other) through three lenses:

• Bloat — lines that stopped earning their always-loaded cost: no-ops the model does by default, sediment from finished migrations, duplication of what rules files or skills already say. An outgrown glossary section is bloat with a home — propose graduating it to CONCEPTS.md, per /compound's convention.
• Contradictions — entries that conflict with each other, with rules files, or with what the code actually does.
• Staleness — references to renamed, moved, or deleted files, tools, or workflows.

Propose the smallest edit that fixes each finding. Before applying any AGENTS.md edit, read ../writing-for-agents/SKILL.md and hold the edit to it.

Gate, report, close

Present the verdicts: Keeps as one summarized list; every Update, Consolidate, Delete, and AGENTS.md edit individually with its evidence, for the user to approve, adjust, or reject. Where this session engaged a deputy through /deputy and has not dismissed it, what is put to the user here goes to the deputy instead, as ROUNDS.md says, and the deputy's reply is printed verbatim under a one-line header before anything acts on it; otherwise it goes to the user as written. Apply only approved changes.

Close with counts (kept / updated / consolidated / deleted / AGENTS.md findings) and a one-liner per touched file. Changes applied → close with a flow pointer (the message's final paragraph, a blockquote in full italics opening Next: — or Next steps: over one bullet per pointer — each pointer naming its skill the way this skill was itself invoked, same prefix and namespace, and ending in a one-clause rationale after an em dash): /commit (user-invoked) — to land the refreshed docs. Where this session engaged a deputy through /deputy and has not dismissed it, a choice is put to the deputy as ROUNDS.md says and rendered as the one step it chose, any other closing is rendered as written, and each rendered step that names a skill is then taken: one marked (user-invoked) by notifying the user where the harness has a tool for it and waiting for them to type it, any other by invoking it, notifying nobody.