Knowledge Bank Lint

Health-check the knowledge bank to detect quality issues that accumulate over time. Without periodic linting, orphan documents pile up, cross-references break, and stale content persists unchallenged.

Knowledge Bank Location: Read from

~/.claude/plugins/config/second-brain/config.json

.

---

Invocation

• Slash command:

  /second-brain:kb-lint

• Skill tool:

  Skill({ skill: "second-brain:kb-lint" })

• Natural language: "Run a health check on the knowledge bank", "Find orphan docs in KB"

---

Workflow

Step 1: SCAN

Run lint checks in order. Each check produces findings with a severity level.

Check 1: Broken WikiLinks (severity: error)

Find WikiLinks that don't resolve to any file in the KB:

./scripts/lint_broken_links.sh "$KB_PATH"

Reuses WikiLink extraction from

knowledge-bank-lookup/scripts/wikilink-utils.sh

and resolution logic.

Check 2: Missing Frontmatter (severity: error)

Find documents missing required frontmatter fields (

title

,

type

,

created

):

./scripts/lint_frontmatter.sh "$KB_PATH"

Reuses frontmatter reading from

skills/common/obsidian_helpers.sh

.

Check 3: Orphan Documents (severity: warning)

Find documents with zero incoming WikiLinks (not referenced by any other document):

./scripts/lint_orphans.sh "$KB_PATH"

Builds a reverse-link index across the entire KB. Excludes structural files (

_meta/

,

_index/

,

_sessions/

).

Check 4: Index Drift (severity: warning)

Find documents that exist on disk but are missing from

_meta/index.md

:

./scripts/lint_index_drift.sh "$KB_PATH"

Compares filesystem against the generated index. Also detects entries in the index that no longer have backing files.

Check 5: Stale Documents (severity: info)

Find documents not modified in 90+ days:

./scripts/lint_stale.sh "$KB_PATH"

Uses file modification timestamps. Excludes

_sessions/

and

daily-log/

(inherently historical).

Step 2: REPORT

Generate a lint report at

_meta/lint-report-YYYY-MM-DD.md

:

---
title: KB Lint Report YYYY-MM-DD
type: lint-report
generated: YYYY-MM-DDTHH:MM:SSZ
---

# KB Lint Report

| Severity | Count |
|----------|-------|
| Error    | N     |
| Warning  | N     |
| Info     | N     |

## Errors

### Broken WikiLinks
- [[Target]] referenced from [[Source]] — target not found

### Missing Frontmatter
- /path/to/doc.md — missing: title, type

## Warnings

### Orphan Documents
- [[Doc Name]] — zero incoming references

### Index Drift
- /path/to/doc.md — exists on disk but missing from index

## Info

### Stale Documents
- [[Doc Name]] — last modified YYYY-MM-DD (N days ago)

Step 3: LOG

Append operation to

_meta/log.md

:

source skills/common/obsidian_helpers.sh
append_kb_log "$KB_PATH" "lint" "kb-lint" "N errors, N warnings, N info findings"

---

Step 4: FIX (optional)

After presenting the report, use AskUserQuestion tool to offer resolution:

• Fix broken WikiLinks — For each broken link, classify as:
  • Stub candidate — the target should exist but hasn't been documented yet. Create a stub file with

    status: stub

    (see below).
  • Near-match — an existing doc with a similar name could resolve it. Add an alias to the existing doc.
  • Bad reference — the WikiLink itself is wrong (typo, template placeholder). Fix or remove it from the source file.
  • Template placeholder — generic WikiLinks like

    [[Related Concept 1]]

    . Remove from source files.
• Fix index drift — Run

  generate_index.sh

  to rebuild

  _meta/index.md

• Fix missing frontmatter — Add required YAML fields to flagged documents
• Skip — Just the report, no fixes needed

See fix-guide.md for stub creation templates, classification heuristics, alias resolution, and template placeholder removal details.

---

Interpreting Results

Severity	Meaning	Action
Error	Data integrity issue	Fix immediately — broken links mislead lookups
Warning	Quality degradation	Fix soon — orphans and drift reduce discoverability
Info	Potential staleness	Review periodically — may need updating or archiving

---

Resources

• KB Schema — Conventions that lint checks enforce
• Fix Guide — Stub creation, alias resolution, template cleanup

---

Completion Criteria

Mode	Complete when
Report only	All 5 checks run, lint report generated, log appended, findings summarized
Report + Fix	All of above, plus chosen fixes applied, index regenerated