kb-prune

name	kb-prune
description	Find and deprecate outdated content — surfaces low-confidence, stale, and unprovenienced pages for deprecation. Use when the user wants to prune, clean up, or remove outdated content. Also triggers on "kb-prune" or "/kb-prune".

kb-prune

Find and deprecate outdated, low-confidence, and unprovenienced wiki pages. Surfaces candidates for review and handles deprecation safely.

Step 1: Resolve KB

python3 ~/.config/kb/scripts/kb_resolve.py --mode mutating

Capture the KB root path. Abort if resolution fails.

Step 2: Find Prune Candidates

Run the lint checker in prune-candidate mode:

python3 ~/.config/kb/scripts/kb_lint_checks.py "{{KB_ROOT}}" --prune-candidates

This returns pages matching any of these criteria:

• Low confidence: confidence below 0.3.
• Stale: last_verified older than 90 days with stability: volatile or evolving.
• No provenance: Empty or missing source_ids (no raw source backing the page).
• Orphaned: No inbound wikilinks from any other page.
• Superseded: Another page lists this page in its supersedes field.

Step 3: Categorize Candidates

Split candidates into two groups:

Auto-deprecation candidates (not human_reviewed)

Present these in a table:

## Prune Candidates

| # | Page | Reason | Confidence | Last Verified | Human Reviewed |
|---|------|--------|-----------|---------------|----------------|
| 1 | wiki/entities/foo.md | low confidence (0.2) | 0.2 | 2025-01-15 | false |
| 2 | wiki/concepts/bar.md | no provenance | 0.5 | 2025-03-01 | false |

Manual-review-only (human_reviewed: true)

Present separately with a clear label:

## Requires Manual Review (human_reviewed: true)

These pages matched prune criteria but cannot be auto-deprecated:

| Page | Reason | Confidence | Last Verified |
|------|--------|-----------|---------------|
| wiki/entities/baz.md | stale (180 days) | 0.4 | 2024-10-01 |

Print: "These pages require manual review. Edit them directly to deprecate or update."

Step 4: LLM Review of Candidates

For each auto-deprecation candidate:

1. Read the page content.
2. Check if the page has meaningful content worth preserving despite matching prune criteria.
3. Check if other pages depend on it (inbound wikilinks).
4. Make a recommendation: deprecate, keep (with reason), or update (needs refresh, not deprecation).

Present recommendations to the user:

### Recommendations

1. wiki/entities/foo.md — DEPRECATE (low confidence, no inbound links)
2. wiki/concepts/bar.md — KEEP (3 pages link to it, content still relevant)
3. wiki/summaries/old.md — DEPRECATE (source retracted, superseded by newer summary)

Step 5: Deprecate Approved Pages

For each page the user approves for deprecation:

1. Move the file from its current location to wiki/deprecated/<filename>.
2. Add a tombstone header to the top of the deprecated file:

<!-- DEPRECATED: {{DATE}} -->
<!-- Reason: {{REASON}} -->
<!-- Original location: {{ORIGINAL_PATH}} -->

3. Update inbound wikilinks across all wiki pages:
   • Find all pages containing [[deprecated-page-name]].
   • Replace with ~~[[deprecated-page-name]]~~ (deprecated {{DATE}}) or remove the link if the context allows.
   • Skip wikilink updates in human_reviewed: true pages — warn instead.

Step 6: Regenerate Index

python3 ~/.config/kb/scripts/kb_index.py "{{KB_ROOT}}"

Step 7: Append Log

Add a row to log.md:

| {{DATE}} | prune | {{N}} candidates found, {{D}} deprecated, {{K}} kept, {{M}} need manual review |

Final Output

Print:

• Total candidates found.
• Pages deprecated (list with paths and reasons).
• Pages kept (list with reasons).
• Pages requiring manual review (human_reviewed).
• Suggestion: "Run kb-lint to verify KB health after pruning."