# Kb Prune

> Interactive cleanup and consolidation of the knowledge base. Finds stale references, duplicates, orphaned files, frontmatter issues, and opportunities to merge related topics.

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

---


# Knowledge Base Pruning

You are a knowledge base maintenance specialist. Your job is to clean up, consolidate, and organize the project's knowledge base. All changes require user approval.

## Obsidian-Compatible Related Links

When modifying KB files, you MUST keep the `related` frontmatter AND the `## Related` body section (at the end of the file) in sync. When merging files, fixing cross-references, or updating related links, always update both locations. If `related` becomes empty, remove the `## Related` body section entirely.

## Frontmatter Schema

When modifying KB files during pruning (merges, promotions, etc.), always maintain valid frontmatter and, if the file's content actually changed, set `last-updated` to today's date.

```yaml
---
tags: [topic-tag-1, topic-tag-2]       # Required: lowercase tags for discovery
related: [[other-kb-file]]             # Optional: cross-references to related KB files
created: YYYY-MM-DD                    # Required: date created
last-updated: YYYY-MM-DD              # Required: date last modified (update on every write)
pinned: false                          # Optional: true = always loaded. Default false
scope: "src/api/**"                    # Optional: glob pattern(s) for auto-matching. String or array.
---
```

**Resolving today's date (cross-platform, CRITICAL)**: Never guess, infer, or increment prior dates. When this skill writes `last-updated`, resolve today's date **once** at the start of the write phase, then reuse that single value for every write. Try these commands in order and use the first that returns a `YYYY-MM-DD` string:

- **macOS / Linux / WSL / Git Bash** (bash, zsh, sh): `date +%Y-%m-%d`
- **Windows PowerShell / pwsh**: `Get-Date -Format 'yyyy-MM-dd'`
- **Windows cmd.exe**: `powershell -NoProfile -Command "Get-Date -Format 'yyyy-MM-dd'"`
- **Portable fallback** (Node or Python available): `node -e "console.log(new Date().toISOString().slice(0,10))"` or `python -c "import datetime; print(datetime.date.today().isoformat())"`

Only update `last-updated` when the file's content actually changed. If an edit would leave the file byte-identical, do not rewrite it or bump the date.

## Instructions

**CRITICAL**: This command MUST NOT accept any arguments. Ignore any text provided after the command.

### Phase 1: Full KB Audit

Perform a comprehensive audit of the knowledge base:

#### 1a: Parse CLAUDE.md

1. Read CLAUDE.md and find the Knowledge Base section.
2. If no Knowledge Base section exists, inform the user: "No Knowledge Base section found. Run `/kb-init` first." and stop.
3. Parse the reference table (Topic, File, When to Load).
4. Parse the Global Learnings subsection.

#### 1b: Verify File References

For each entry in the table:
1. Check if the referenced file exists.
2. Categorize as **OK** or **STALE** (file missing).

#### 1c: Find Orphaned Files

1. Glob all `.md` files under `docs/kb/` (excluding `docs/kb/README.md`).
2. Identify files not referenced in the CLAUDE.md table. Categorize as **ORPHANED**.

#### 1d: Frontmatter Health Check

For each existing KB file:
1. Check if YAML frontmatter exists.
2. Check if all required fields are present (`tags`, `created`, `last-updated`).
3. Categorize issues:
   - **NO FRONTMATTER** - File has no YAML frontmatter at all.
   - **INCOMPLETE FRONTMATTER** - Missing required fields.
   - **REVIEW SUGGESTED** - `last-updated` is older than 90 days. This doesn't mean the content is wrong — stable knowledge is fine — but it may be worth a quick review to confirm it's still accurate.

#### 1e: Detect Duplicates and Merge Candidates

1. Read all existing KB files.
2. Look for:
   - **Duplicate entries**: KB files with substantially overlapping content.
   - **Merge candidates**: KB files covering closely related topics that could be consolidated (e.g., `api-auth.md` and `api-tokens.md` could merge into `api-auth.md`). Use tags to identify overlap — files with highly overlapping tag sets are likely candidates.
   - **Contradictions**: Rules in different KB files or between KB files and Global Learnings that conflict.

#### 1f: Cross-Reference Integrity

1. For each KB file with `related` references in frontmatter:
   - Check that referenced files exist.
   - Check for one-way references (A links to B but B doesn't link to A).
   - Check that the `## Related` body section matches the `related` frontmatter (flag **OUT OF SYNC** if they differ or if the body section is missing).
2. Categorize as **BROKEN LINK**, **ONE-WAY REFERENCE**, or **OUT OF SYNC**.

#### 1g: Review Global Learnings

Global learnings are stored in `docs/kb/_global-learnings.md`. If this file doesn't exist, check for a legacy `### Global Learnings` inline section in CLAUDE.md — if found, flag it as **NEEDS MIGRATION** and suggest running `/kb-upgrade`.

1. Read `docs/kb/_global-learnings.md` (or the legacy inline section if the file doesn't exist).
2. Check for entries that are:
   - **Outdated**: No longer relevant based on current codebase state (check if referenced files/patterns still exist).
   - **Duplicated**: Same information exists in a KB file AND in Global Learnings.
   - **Promotable**: A global learning that's actually topic-specific and should be moved to a KB file.

### Phase 2: Present Findings

Display a comprehensive audit report:

```
Knowledge Base Audit Report
============================

## Issues Found

### Stale References ({count})
These CLAUDE.md table entries point to files that no longer exist:
- {Topic} -> {file path} (MISSING)

### Orphaned Files ({count})
These KB files exist but aren't referenced in CLAUDE.md:
- {file path} (tags: {tags})

### Frontmatter Issues ({count})
- {file path} — NO FRONTMATTER
- {file path} — Missing fields: tags, created
- {file path} — Last updated 120 days ago (review suggested, may still be valid)

### Merge Candidates ({count})
These KB files have overlapping content and could be consolidated:
- {file1} + {file2} -> Suggested merge into {target}
  Overlapping tags: {shared tags}
  Reason: {brief explanation}

### Cross-Reference Issues ({count})
- {file1} references [[{file2}]] but {file2} doesn't reference [[{file1}]] (one-way)
- {file1} references [[{file2}]] but {file2} doesn't exist (broken)

### Duplicate/Redundant Entries ({count})
- Global learning "{entry}" duplicates content in {kb file}

### Contradictions ({count})
- {file1} says "{rule1}" but {file2} says "{rule2}"

### Promotable Global Learnings ({count})
- "{learning}" could move to {suggested kb file} (tags: {suggested tags})

## Summary
- {ok_count} healthy KB files
- {total_issues} issues found
```

If no issues found:
> "Knowledge base is clean. No issues found across {file_count} KB files and {learning_count} global learnings."

### Phase 3: Propose Actions

If issues were found, present a remediation plan:

Use AskUserQuestion:
- Question: "Here's my recommended cleanup plan. How would you like to proceed?"
- Show the proposed actions grouped by type
- Options: "Apply all recommendations" | "Let me review each one" | "Cancel"
- Header: "KB Cleanup Plan"

If "Let me review each one", present each proposed action individually:
- For stale references: "Remove row for '{Topic}' from CLAUDE.md table?"
- For orphaned files: "Register '{file}' in CLAUDE.md, or delete it?"
- For frontmatter issues: "Add/fix frontmatter for '{file}'?" (show proposed frontmatter)
- For merge candidates: "Merge '{file1}' and '{file2}' into '{target}'?"
- For cross-reference issues: "Add missing reverse reference? / Remove broken reference?"
- For duplicates: "Remove duplicate from Global Learnings (kept in KB file)?"
- For contradictions: "Which rule is correct: '{rule1}' or '{rule2}'?"
- For promotable learnings: "Move '{learning}' from Global Learnings to '{kb file}'?"

### Phase 4: Execute Approved Actions

Apply only the user-approved changes:

1. **Stale references**: Remove rows from the CLAUDE.md table.
2. **Orphaned files**: Either register them (add table row, fix frontmatter) or delete the file, per user choice.
3. **Frontmatter fixes**: Add/complete frontmatter on affected files. Update `last-updated`.
4. **Merges**: Combine content from source files into target file, merge tags and related references in frontmatter, remove source files, update CLAUDE.md table. Update `last-updated`.
5. **Cross-reference fixes**: Add missing reverse references or remove broken links. Sync the `## Related` body section with the `related` frontmatter on all modified files. Update `last-updated` on modified files.
6. **Duplicates**: Remove the redundant entry from whichever location the user chose.
7. **Contradictions**: Update the incorrect entry with the correct rule. Update `last-updated`.
8. **Promotions**: Move the learning from `docs/kb/_global-learnings.md` to the target KB file, add table reference if needed. Update `last-updated` on `_global-learnings.md`.
9. **Legacy migration**: If inline `### Global Learnings` content was found in CLAUDE.md, migrate it to `docs/kb/_global-learnings.md` and remove the inline section.

After all changes:
- Re-sort the CLAUDE.md reference table alphabetically by Topic.
- Remove any placeholder text if real entries now exist.
- Ensure no empty sections remain.

### Phase 5: Update Index and Log

1. **Update `docs/kb/_index.md`**: If this file exists, update it to reflect all changes — remove entries for deleted files, update summaries for merged files, add entries for newly registered orphans. Update `last-updated` in its frontmatter.
2. **Append to `docs/kb/_log.md`**: If this file exists, append:
   ```
   ## [YYYY-MM-DD] prune | KB cleanup and consolidation
   - Stale refs removed: {count}
   - Orphans registered/deleted: {count}
   - Frontmatter fixes: {count}
   - Merges: {count}
   - Cross-ref fixes: {count}
   ```

### Phase 6: Confirmation

Display a summary of all changes made:
- Files created/updated/deleted
- Frontmatter fixes applied
- Cross-references added/removed
- CLAUDE.md table rows added/removed/updated
- Global learnings added/removed/moved
- Final KB file count and health status