jmagly/kb-health

KB Health

Audit the knowledge base for structural and content issues. Reports problems and, with --fix, repairs what can be fixed automatically (broken links, missing index entries). Human review is required for content issues (stale claims, empty sections).

Triggers

• "check KB health" → full audit
• "find orphan pages" → orphan check only
• "regenerate KB index" → --index-only
• /kb-health → direct invocation

Parameters

--path <subtree> (optional)

Scope the check to a subdirectory (e.g., --path .aiwg/kb/entities/). Defaults to full KB root.

--kb <path> (optional)

Root of the knowledge base. Default: resolved by aiwg kb path (#965), which reads resolveStorage('kb') and honors any roots.kb override in .aiwg/storage.config. On the default fs backend this is .aiwg/kb/.

KB_ROOT=$(aiwg kb path)
aiwg kb list --prefix entities/
aiwg kb get entities/foo.md

--fix (optional)

Automatically repair issues that are safe to fix without human judgment:

• Remove references to confirmed-missing pages from Sources tables
• Add pages missing from the index
• Normalize slug inconsistencies (spaces → hyphens in filenames)

Does NOT auto-fix: empty required sections, stale claim dates, ambiguous duplicates.

--index-only (optional)

Skip all checks; only regenerate index.md.

---

Checks

1. Orphan Pages

An orphan is a page with no incoming [[wiki-link]] references from any other KB page.

Procedure:

1. Collect all .md files under <kb>/.
2. For each file, extract all [[...]] references.
3. Build an inverted index: page → set of pages that link to it.
4. Pages with zero incoming links are orphans.

Orphans in sources/ are less critical (sources are often terminal nodes). Report them separately.

2. Broken Wiki-Links

For every [[link-target]] found in any KB page:

1. Derive the expected file path (slug → filename in each subdirectory).
2. Check whether the file exists.
3. If not: report as a broken link with the containing file and line number.

With --fix: remove confirmed-broken links from Sources tables. Flag broken links in prose sections for manual review (do not silently remove).

3. Empty Required Sections

Templates define required sections (Overview, Definition, Key Takeaways, etc.). Detect pages where a required section header exists but the body is a placeholder (_..._ or a single empty line).

Report as warnings, not errors. Do not auto-fix content.

4. Stale Pages

A page is considered stale if:

• Its _Last updated: date is more than 180 days ago, AND
• At least one source it references was published after that date (detectable via source summary dates)

Report stale pages as advisory — staleness is informational, not a structural error.

5. Duplicate Slugs

Detect files with the same normalized slug in different subdirectories (e.g., entities/python.md and concepts/python.md). These may be legitimate or accidental duplicates. Report all cases; do not auto-resolve.

---

Index Regeneration

Always regenerate <kb>/index.md at the end of a health check run (or when --index-only is used).

The index lists all KB pages grouped by directory with their first-line description (the > blockquote line from templates):

# Knowledge Base Index

_Generated: YYYY-MM-DD — N pages_

## Entities (N)
- [Entity Name](entities/entity-name.md) — type · domain

## Concepts (N)
- [Concept Name](concepts/concept-name.md) — category · domain

## Sources (N)
- [Source Title](sources/source-slug.md) — type · author · date

## Comparisons (N)
- [A vs B](comparisons/a-vs-b.md) — purpose

## Syntheses (N)
- [Synthesis Title](syntheses/synthesis-slug.md) — type · confidence

---

Report Format

KB Health Report — YYYY-MM-DD
Root: .aiwg/kb/
Pages scanned: N

ERRORS (must fix)
  Broken links: N
    entities/foo.md:12 — [[missing-page]] not found

WARNINGS (review recommended)
  Orphan pages: N
    sources/old-article.md — no incoming links
  Empty sections: N
    concepts/bar.md — Definition section is placeholder
  Stale pages: N
    entities/baz.md — last updated 2024-01-01 (>180 days)

INFO
  Duplicate slugs: N
    entities/python.md and concepts/python.md share slug "python"

Index regenerated: .aiwg/kb/index.md (N entries)

---

Scope Limits

• Read-only by default. --fix enables targeted writes; --index-only writes only index.md.
• Do not delete any pages, even if they appear to be duplicates. Report and let the human decide.
• Maximum pages scanned per run: 500. If KB exceeds this, use --path to scope.

References

• @$AIWG_ROOT/agentic/code/frameworks/knowledge-base/templates/entity-page.md
• @$AIWG_ROOT/agentic/code/frameworks/knowledge-base/templates/concept-page.md
• @$AIWG_ROOT/agentic/code/frameworks/knowledge-base/templates/source-summary.md
• @$AIWG_ROOT/agentic/code/frameworks/knowledge-base/skills/kb-ingest/SKILL.md