# Prune

> Explicit V3 convergence pass that removes duplicated, fragmented, or low-value reconstructable llmdoc content.

- Skill: `tokenrollai/prune` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tokenrollai/prune`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tokenrollai/prune/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: TokenRollAI (https://skillmd.com/u/tokenrollai)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tokenrollai/prune

---


# /llmdoc:prune

Use this command only when existing `llmdoc/` knowledge needs convergence after growth, duplication, fragmentation, or accumulation of reconstructable implementation inventory.

Load the `llmdoc` skill before broad exploration. CLI commands below run as `npx -y @tokenroll/llmdoc <cmd>`.

## Authorization

An explicit `/llmdoc:prune` invocation authorizes this run to:

- rewrite, merge, or delete stable docs under `llmdoc/`
- update `llmdoc/meta.json`
- write temporary investigation notes under `.llmdoc-tmp/investigations/` when needed

This command does not authorize source-code edits.

## Preconditions

- `git status -- llmdoc/` must be clean before the first formal write.
- Rollback means `git checkout -- llmdoc/` (plus deleting any newly created files under `llmdoc/`); never hand-edit files back.
- If `validate` fails after pruning writes and cannot be repaired in-run, roll back the prune write-set before reporting failure.

## Workflow

1. Run `prune --report`.
   - Use the report as the primary mechanical signal for scale, duplication, and fragmentation.
   - The CLI only reports; it never rewrites docs on its own.
   - A clean duplicate/fragment report does not prove good knowledge density; semantic review remains the recorder's job.

2. Decide the convergence plan with `recorder`.
   - If the plan moves ownership, changes topic boundaries, or merges/splits documents, read [Knowledge Topology and Context Floor](../llmdoc/references/knowledge-topology.md) before rewriting.
   - Read [Startup Configuration](../llmdoc/references/startup-config.md) when the report lists startup preload references. Update or remove affected config entries in the same write set before merging or deleting their documents; `mv` handles direct renames automatically.
   - Merge duplicated docs.
   - Rewrite fragmented docs when a clearer topic boundary exists.
   - Apply the Stable Knowledge Gate sentence by sentence. Remove command/file inventories, current-state evidence, and other facts that a reader can cheaply recover from canonical sources.
   - Preserve decisions and rationale, boundaries, invariants, cross-module contracts, non-obvious failures, and risky repeatable workflows.
   - Keep a transitional fact only when omission would be unsafe, and record the condition that retires it.
   - Delete a document when it has no unique durable knowledge; canonical source, schema, help, or tests are valid destinations for discarded evidence. Do not copy low-value content elsewhere merely to justify deletion.

3. Re-validate the result.
   - Confirm every configured startup preload still targets the surviving owner document.
   - Run `validate`.
   - When ownership or routing changed, run the reference's scoped concept, per-file owner, broad-glob precision, and prerequisite checks; structural validation alone is insufficient.
   - Re-run `prune --report` and compare document/token scale with the first report.
   - Confirm surviving stable concepts retain accurate `code.paths`. Do not attach unrelated paths merely to preserve a coverage metric; call out any intentional coverage reduction.
   - Finalize with `commit -m "<message>"`, which fingerprints the surviving docs and lands the `meta.json` follow-up commit automatically.
   - Report `success` only when durable knowledge density or routing materially improves. Refresh convergence only when scale declines without losing justified mappings; otherwise repair, roll back, or report `no_change` as appropriate.

## State Invariants

- `prune` updates convergence state only on successful validated convergence.
- `prune` must not advance the full baseline unless it explicitly performs a full successful sync as part of the same run.
- Per-document fingerprint updates happen only for the docs that survived or replaced prior docs.

## Result Contract

- `success`: knowledge density or routing materially improved, the result validated, and convergence state was updated when applicable.
- `no_change`: the declared scope was fully verified and no justified convergence action remained.
- `dry_run`: the user asked for a dry run, or only `prune --report`/planning output was produced without writing `llmdoc/`; do not advance state.
- `incomplete`: evidence was insufficient, user input is required, or the request belongs to a different explicit workflow; roll back writes and do not advance state.
- `failed`: prune failed and writes were rolled back.

Always report:

- the `prune --report` signal that justified the run
- which docs were merged, rewritten, or deleted
- the `validate` and `commit` results
- how reconstructable evidence was reduced without losing durable decisions or contracts