| name | knowledge-wiki-lint |
| description | Audit and repair the knowledge wiki. Detects orphan summaries (source deleted), broken wikilinks, and orphan concept files. Run periodically after accumulating new content or reorganizing source files. |
Knowledge Wiki Lint
Health-check and repair the wiki. Runs four checks in sequence — each builds on a clean state left by the previous one. JavaScript handles all file-system detection; the LLM handles any repair that requires judgment.
Setup
1. Establish the working directory
The knowledge base root is the directory containing this skill's .claude/ folder. Determine it by resolving the path of the .claude/ directory upward — the parent of .claude/ is KNOWLEDGE_PATH.
Use KNOWLEDGE_PATH for all subsequent steps.
Check 1 — Orphan Summaries
Deletes summary files whose source document has been moved or deleted.
2. Find orphan summaries
Run:
node {KNOWLEDGE_PATH}/scripts/find-orphan-summaries.mjs
Output is a JSON object keyed by orphan summary file path (relative to KNOWLEDGE_PATH). Each value has a source field with the path the summary expected to find, or null if the frontmatter had no source field.
If the object is empty ({}), skip to Check 2 and print Check 1: no orphan summaries.
3. Delete orphan summary files and remove their index entries
For each key in the output:
- Delete the file at
{KNOWLEDGE_PATH}/{key}.
- Derive the summary's rel-path by stripping the
Wiki/Summaries/ prefix and the .md extension from the key. Example: Wiki/Summaries/Posts/Foo.summary.md → Posts/Foo.summary. Then run:
node {KNOWLEDGE_PATH}/scripts/wiki-index.mjs delete-summary "{rel-path}"
After processing all orphans, delete any now-empty directories under Wiki/Summaries/:
find {KNOWLEDGE_PATH}/Wiki/Summaries -type d -empty -delete
Check 2 — Broken Summary → Concept Links
Creates missing concept files referenced by summaries.
4. Find and repair broken summary → concept links
Run:
node {KNOWLEDGE_PATH}/scripts/find-broken-summary-links.mjs
Output is a JSON object keyed by missing concept file path. Each value has a referencedBy array listing the summary files that link to that missing concept.
If the object is empty ({}), skip to Check 3 and print Check 2: no broken summary → concept links.
For each missing concept:
4a. Read referencing summaries
Read each file listed in the referencedBy array.
4b. Create the concept file
Create {KNOWLEDGE_PATH}/{key} following exactly the format and instructions in .claude/skills/knowledge-wiki-concept/SKILL.md under step 3b ("If the concept file does NOT exist"). Draw on all referencing summary files to write the article.
4c. Update the index
Derive the slug from the concept file path (basename without .md), and the display name from the # Title line of the file just created. Then follow step 3c of .claude/skills/knowledge-wiki-concept/SKILL.md.
Check 3 — Broken Concept → * Links
Removes dead bullet points from concept files that link to missing targets.
5. Find and remove dead bullet points
Run:
node {KNOWLEDGE_PATH}/scripts/find-broken-concept-links.mjs
Output is a JSON object keyed by concept file path. Each value has a brokenLinks array of raw wikilink target strings (the text between [[ and ]]) that resolve to missing files.
If the object is empty ({}), skip to Check 4 and print Check 3: no broken concept links.
For each concept file in the output:
- Derive the slug (basename of the concept file path without
.md). Example: Wiki/Concepts/foo-bar.md → foo-bar.
- For each string in
brokenLinks, inspect the target to determine which command to run:
Double-quote all arguments to protect special characters.
Check 4 — Orphan Concepts
Deletes concept files that nothing links to.
6. Find and delete orphan concepts
Run:
node {KNOWLEDGE_PATH}/scripts/find-orphan-concepts.mjs
Output is a JSON object keyed by orphan concept file path.
If the object is empty ({}), skip to Check 5 and print Check 4: no orphan concepts.
For each key in the output:
- Delete the file at
{KNOWLEDGE_PATH}/{key}.
- Derive the slug (basename of
{key} without .md). Run:
node {KNOWLEDGE_PATH}/scripts/wiki-index.mjs delete-concept "{slug}"
Check 5 — Dead Index Links
Removes entries from Wiki/index.md that point to files that no longer exist on disk.
7. Remove dead index links
Run:
node {KNOWLEDGE_PATH}/scripts/wiki-index.mjs remove-dead-links
Output is a JSON object { "concepts": N, "summaries": N } with the count of deleted entries in each section. The script writes the updated index automatically.
If both counts are zero, print Check 5: no dead index links. and skip to Check 6.
Otherwise record the counts for the final summary — no further action required.
Check 6 — Missing Summary Index Entries
Adds index entries for summary files on disk that have no Wikilink in Wiki/index.md.
8. Find summaries missing from the index
Run:
node {KNOWLEDGE_PATH}/scripts/wiki-index.mjs find-missing-summaries
Output is a JSON array of rel-paths (e.g. ["AvocadoToast/foo.summary"]).
If the array is empty, print Check 6: no summary index entries missing. and skip to Check 7.
9. Generate and insert missing summary entries
For each rel-path in the array:
- Read the summary file at
{KNOWLEDGE_PATH}/Wiki/Summaries/{rel-path}.md.
- Generate a one-line English description of the source document from the
## Summary section.
- Run:
node {KNOWLEDGE_PATH}/scripts/wiki-index.mjs upsert-summary "{rel-path}" "{description}"
Check 7 — Missing Concept Index Entries
Adds index entries for concept files on disk that have no Wikilink in Wiki/index.md.
10. Find concepts missing from the index
Run:
node {KNOWLEDGE_PATH}/scripts/wiki-index.mjs find-missing-concepts
Output is a JSON array of slugs (e.g. ["autonomous-driving"]).
If the array is empty, print Check 7: no concept index entries missing. and skip to Check 8.
11. Generate and insert missing concept entries
For each slug in the array:
- Read the concept file at
{KNOWLEDGE_PATH}/Wiki/Concepts/{slug}.md.
- Extract the display name from the
# Title line of the file.
- Generate a one-line English description from the file's opening prose.
- Run:
node {KNOWLEDGE_PATH}/scripts/wiki-index.mjs upsert-concept "{slug}" "{display-name}" "{description}"
Check 8 — Stale Dismissed Merge Pairs
Removes entries from the merge dismissal list in Wiki/.state.json whose concept files no longer exist.
12. Prune stale dismissed pairs
Run:
node {KNOWLEDGE_PATH}/scripts/wiki-state.mjs prune-merge-pairs
Output is a single integer: the number of pairs pruned. If 0, print Check 8: no stale dismissed pairs.
Final Steps
13. Print summary
Knowledge Wiki Lint
Check 1 · Orphan Summaries
Deleted {N} orphan summary file(s):
- {Display Name} (source: {source})
[or: No orphan summaries found.]
Check 2 · Broken Summary → Concept Links
Created {N} missing concept file(s): {Display Name}, ...
[or: No broken summary → concept links found.]
Check 3 · Broken Concept → * Links
Removed {N} dead bullet point(s) from {M} concept file(s).
[or: No broken concept links found.]
Check 4 · Orphan Concepts
Deleted {N} orphan concept file(s): {Display Name}, ...
[or: No orphan concepts found.]
Check 5 · Dead Index Links
Removed {N} dead link(s) from Wiki/index.md ({M} concept(s), {K} summary(s)).
[or: No dead index links found.]
Check 6 · Missing Summary Index Entries
Added {N} missing summary entr(y/ies) to Wiki/index.md.
[or: No summary index entries missing.]
Check 7 · Missing Concept Index Entries
Added {N} missing concept entr(y/ies) to Wiki/index.md.
[or: No concept index entries missing.]
Check 8 · Stale Dismissed Merge Pairs
Pruned {N} stale pair(s).
[or: No stale dismissed pairs.]
