Review Knowledge

---
name: review-knowledge
description: >-
  Review and maintain the knowledge base — find stale entries, orphan entries without connections,
  missing links between related entries, and generate topic summaries. Supports the "internalization"
  phase of knowledge management by surfacing knowledge for periodic review and reflection.
license: MIT
allowed-tools: Read, Grep, Glob, Edit, Write
---

# Review Knowledge

## Goal
Maintain knowledge base health and surface entries for review, helping the user internalize accumulated knowledge through periodic reflection.

## When to Use
- User explicitly requests a knowledge review (e.g., "review knowledge", "check knowledge base")
- At the end of a significant work phase or project milestone
- When the user wants to understand the current state of knowledge on a topic
- Periodically (e.g., weekly/monthly) to keep the knowledge base healthy

## Prerequisites
- `.claude/knowledge/entries/` directory exists with entries created by `record-knowledge`
- `.claude/knowledge/CLAUDE.md` tag registry exists

## Review Modes

Invoke with an optional argument to select a mode. If no argument is given, run **health check**.

### 1. Health Check (default)
Scan the entire knowledge base and report:

#### a. Stale Entries
- Entries older than 90 days with `status: active` — may need review for accuracy
- Detect by comparing `created:` date in frontmatter to the current date
- Report: list of entries with age, title, and tags

#### b. Orphan Entries
- Active entries with NO `- see:` links (disconnected from the knowledge graph)
- These represent isolated knowledge that may be hard to discover in future sessions
- Report: list of orphan entries with title and tags

#### c. Missing Connections
- Find pairs of active entries that share 2+ tags but have no `- see:` link between them
- These are likely related but not explicitly connected
- Report: list of suggested connections with shared tags

#### d. Tag Health
- Tags in entries that are not registered in `.claude/knowledge/CLAUDE.md`
- Tags in the registry that are not used by any entry
- Near-duplicate tags (same rules as record-knowledge similarity check)

#### e. Summary Statistics
- Total entries (active / deprecated)
- Average see links per entry
- Most connected entries (highest see link count)
- Most used tags

#### f. Unidirectional Links
- Entry A has a `- see:` link to entry B, but entry B does NOT have a `- see:` link back to entry A
- These represent broken bidirectional links that reduce discoverability from the target entry's side
- Report: list of unidirectional pairs with source entry, target entry, and direction of missing link

#### g. Broken See Links
- For each `- see:` link in entries, verify that the target file exists under `entries/`
- Resolve entries/-relative paths (e.g., `2026/03/slug.md`) and legacy filename-only paths (`slug.md`)
- Report: list of entries with broken see links, including the missing target path

#### h. Broken File References
- For each `- ref:` link pointing to a local file path (not external URLs), verify the target exists
- Resolve relative paths from the entry's location
- Report: list of entries with broken ref links

#### i. Oversized Entries
- Entries exceeding **500 KB**: report as warning (consider splitting)
- Entries exceeding **1 MB**: report as action required (split recommended)
- Entries exceeding **300 lines**: report as suggestion (may benefit from splitting)
- Report: list of oversized entries with size, line count, and tags

#### j. Synthesis Candidates
- Active entries sharing 2+ tags with 3+ entries in the cluster, and no `synthesis` entry exists for that tag combination
- `fragment` entries older than 60 days that have accumulated 2+ `see:` links (hub-forming signal)
- Report with prompt: "These entries may be ready for synthesis. Create one?"

#### k. Superseded Chain Check
- Entries with `status: superseded` must have a valid `superseded_by` path
- Check that the replacement entry exists and is `active`
- Report broken superseded chains

#### l. Missing Overview
- For each tag used by 5+ active entries, check if an `overview` type entry exists for that topic
- An overview entry is identified by `type: overview` in frontmatter
- Report: list of tags with entry count but no overview, suggesting overview creation

### 2. Topic Review (`topic:<keyword or tag>`)
Deep dive into a specific topic:

1. Search entries by tag or keyword
2. Present a structured summary of all related knowledge:
   - Key facts and decisions
   - Known pitfalls
   - Related entries and their connections
3. Ask the user reflective questions:
   - "Is this still accurate based on your current experience?"
   - "Have you encountered new pitfalls not yet recorded?"
   - "Are there entries that should be deprecated?"

### 3. Fix Mode (`fix`)
Interactively fix issues found in the health check:

1. Run health check first
2. For each issue found, take action:
   - **Orphan entries**: Search for related entries and add see links (using the same search procedure as record-knowledge step 4)
   - **Missing connections**: Add see links between suggested pairs (with user-facing notification)
   - **Unidirectional links**: Add the missing reverse `- see:` link to the target entry so both entries link to each other
   - **Broken see links**: Search `entries/` for the target filename — if found at a different path (e.g., migrated to YYYY/MM/), auto-fix the link. If not found, report for manual review
   - **Broken file references**: Report for manual review (target may need to be created or the ref removed)
   - **Oversized entries**: Propose splitting using the split procedure from `record-knowledge` — ask for confirmation before splitting
   - **Synthesis candidates**: Draft a synthesis entry template from the candidate entries — ask for user review before creating
   - **Broken superseded chains**: Report for manual review (the replacement entry may need to be created or the superseded_by path corrected)
   - **Missing overviews**: Generate an overview entry template for the user to review — do NOT auto-create, ask for confirmation first
   - **Unregistered tags**: Auto-add missing tags to the registry in `.claude/knowledge/CLAUDE.md` under the appropriate section
   - **Unused tags**: Report for manual review (do not auto-delete)
3. Report actions taken

## Output Format

```markdown
# Knowledge Base Review — YYYY-MM-DD

## Health Summary
- Total entries: N (active: N, deprecated: N)
- Orphan entries: N
- Stale entries (>90 days): N
- Missing connections: N suggested
- Unidirectional links: N
- Broken see links: N
- Broken file references: N
- Oversized entries: N
- Synthesis candidates: N
- Broken superseded chains: N
- Missing overviews: N
- Tag issues: N

## Stale Entries
| Entry | Age | Tags |
|-------|-----|------|
| [title](slug.md) | N days | #tag1 #tag2 |

## Orphan Entries
| Entry | Tags |
|-------|------|
| [title](slug.md) | #tag1 #tag2 |

## Suggested Connections
| Entry A | Entry B | Shared Tags |
|---------|---------|-------------|
| [title](slug.md) | [title](slug.md) | #tag1 #tag2 |

## Unidirectional Links
| Source | Target | Missing Direction |
|--------|--------|-------------------|
| [title](slug.md) | [title](slug.md) | target → source |

## Broken See Links
| Entry | Broken Target |
|-------|---------------|
| [title](YYYY/MM/slug.md) | `YYYY/MM/missing.md` |

## Broken File References
| Entry | Broken Ref |
|-------|------------|
| [title](YYYY/MM/slug.md) | `../../../path/to/missing` |

## Oversized Entries
| Entry | Size | Lines | Tags | Severity |
|-------|------|-------|------|----------|
| [title](YYYY/MM/slug.md) | 1.2 MB | 542 | #tag1 | action required |
| [title](YYYY/MM/slug.md) | 600 KB | 380 | #tag2 | warning |

## Synthesis Candidates
| Tag Cluster | Entries | Suggestion |
|-------------|---------|------------|
| #tag1 #tag2 | entry-a, entry-b, entry-c | Ready for synthesis |

## Broken Superseded Chains
| Entry | superseded_by | Issue |
|-------|---------------|-------|
| [title](YYYY/MM/slug.md) | `YYYY/MM/missing.md` | Replacement not found |

## Missing Overviews
| Tag | Entry Count | Suggestion |
|-----|-------------|------------|
| #tag1 | N | Consider creating an overview entry |

## Tag Issues
- Unregistered: #tag1, #tag2
- Unused: #tag3
- Near-duplicates: #foo / #foos

**Tip**: Run `scripts/regenerate-tag-registry.py --write` to rebuild the tag registry from entries.
```

## Procedure

1. Glob `.claude/knowledge/entries/**/*.md` to list all entries (recursively, including YYYY/MM/ subdirectories)
2. Read each entry's YAML frontmatter (title, status, created, tags) and scan for `- see:` lines
3. Read `.claude/knowledge/CLAUDE.md` for the tag registry
4. Analyze and generate the report based on the selected mode
5. If `fix` mode: execute fixes autonomously and report what was changed
6. Output the report to the user (do NOT write it to a file unless requested)