Audit the knowledge base for quality issues: missing frontmatter, broken links, tag inconsistencies, orphaned files, and coverage gaps. Works on any markdown-heavy project.
\nParse focus area from $ARGUMENTS (optional). If provided, focus on that area (e.g., \"tags\", \"frontmatter\", \"links\"). If empty, run full audit.
Find all markdown files: Use Glob to find all .md files, excluding common non-content directories: .venv/, node_modules/, .git/, archive/, .archive_old/.
Frontmatter audit: First, scan a sample of existing files (first 10-20) to detect the frontmatter schema in use (which fields exist, what values are common for type and status). Then for each markdown file, check:
--- and has closing ---)title, tags (and any other fields consistently used across the KB)type and status values (if used) are consistent with the detected schematags is a non-empty list\nTrack files missing frontmatter and files with incomplete/invalid frontmatter.Link check: Look for broken internal links:
\n\\[.*\\]\\(.*\\.md\\) and verify each target file existsscripts/check_links.py), run it as wellTag consistency audit: Use Grep to find all tags: sections across .md files. Look for:
Orphaned files: Check which files are NOT referenced in any other file's related: field. Files that exist but are never cross-referenced may be orphaned.
Content quality: Find documents that appear to be ideas or opportunities (based on detected type field or directory location) and check:
draft status for more than 30 daysCoverage gaps: Check each directory for content:
\nOutput report:
\n## KB Audit Report\n\n**Date:** [today]\n\n### Summary\n- Total .md files: X\n- With frontmatter: X (X%)\n- Without frontmatter: X\n\n### Frontmatter Issues\n| File | Issue |\n|------|-------|\n| path | Missing field: type |\n\n### Broken Links\n[list of broken references]\n\n### Tag Analysis\n- Total unique tags: X\n- Single-use tags: [list]\n- Potential duplicates: [list]\n\n### Orphaned Files\n[files not referenced anywhere]\n\n### Content Quality\n- Stale drafts (> 30 days): [list]\n- Missing metadata: [list]\n- Low-content files: [list]\n\n### Coverage\n[directory analysis]\n\n### Recommendations\n1. [specific action]\n2. [specific action]\n3. [specific action]\nevent-2026 for a specific event). Flag but don't auto-merge without checking context.3-inbox/ or 4-opportunities/ are often standalone by design. Only flag orphans in methodology or principles directories.0-principles/ uses type: principle, 3-inbox/ uses type: capture. Detect per-directory norms, don't enforce one schema globally.related: field is not authoritative — many valid cross-references exist as inline markdown links [text](path.md), not just YAML related: arrays. Check both.5-active-projects/ or 6-companies/ might be empty by design (populated by automation). Check registry.yaml or Makefile before flagging.Cause: Running in wrong directory or all files excluded.\nFix: Ensure you're in the knowledge base root. Check exclude patterns in step 2.
\nCause: Inconsistent tagging across documents.\nFix: Pick canonical tags from the most-used list. Run audit again after cleanup.
\nCause: YAML syntax issues (missing quotes, wrong indentation).\nFix: Ensure --- delimiters are present. Use type: and status: values consistent with your KB's detected schema.