prune

name	prune
description	Explicit V3 convergence pass that removes duplicated, fragmented, or low-value reconstructable llmdoc content.
argument-hint	[--scope <topic|path...>] [summary]

/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 before rewriting.
   • 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.

   • 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