solo-audit（单独审核）

/audit

Audit the knowledge base for quality issues: missing frontmatter, broken links, tag inconsistencies, orphaned files, and coverage gaps. Works on any markdown-heavy project.

Steps

1. Parse focus area from $ARGUMENTS (optional). If provided, focus on that area (e.g., "tags", "frontmatter", "links"). If empty, run full audit.
2. Find all markdown files: Use Glob to find all.md files, excluding common non-content directories: .venv/, node_modules/, .git/, archive/, .archive_old/.
3. 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:

- Has YAML frontmatter (starts with --- and has closing ---) - Core fields present: title, tags (and any other fields consistently used across the KB) - type and status values (if used) are consistent with the detected schema - tags is a non-empty list Track files missing frontmatter and files with incomplete/invalid frontmatter.

1. Link check: Look for broken internal links:

- Grep for markdown links \[.*\]\(.*\.md\) and verify each target file exists - If a link-checking script exists in the project (e.g., scripts/check_links.py), run it as well

1. Tag consistency audit: Use Grep to find all tags: sections across.md files. Look for:

- Near-duplicate tags (e.g., "ai" vs "AI" vs "artificial-intelligence") - Tags used only once (potential typos) - Very common tags that might be too broad List all unique tags with counts.

1. 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.
2. Content quality: Find documents that appear to be ideas or opportunities (based on detected type field or directory location) and check:

- Documents still in draft status for more than 30 days - Documents missing key metadata fields that other similar documents have - Documents with very little content (< 100 words, excluding frontmatter)

1. Coverage gaps: Check each directory for content:

- Flag any empty or near-empty directories - Look for directories with only 1-2 files (may need more content)

1. Output report: ## KB Audit Report **Date:** [today] ### Summary - Total.md files: X - With frontmatter: X (X%) - Without frontmatter: X ### Frontmatter Issues | File | Issue | |------|-------| | path | Missing field: type | ### Broken Links [list of broken references] ### Tag Analysis - Total unique tags: X - Single-use tags: [list] - Potential duplicates: [list] ### Orphaned Files [files not referenced anywhere] ### Content Quality - Stale drafts (> 30 days): [list] - Missing metadata: [list] - Low-content files: [list] ### Coverage [directory analysis] ### Recommendations 1. [specific action] 2. [specific action] 3. [specific action]

Gotchas

1. Single-use tags are not always typos — a tag used once might be intentional (e.g., event-2026 for a specific event). Flag but don't auto-merge without checking context.
2. Orphaned files may be intentional archives — files in 3-inbox/ or 4-opportunities/ are often standalone by design. Only flag orphans in methodology or principles directories.
3. Frontmatter schemas drift across directories — 0-principles/ uses type: principle, 3-inbox/ uses type: capture. Detect per-directory norms, don't enforce one schema globally.
4. 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. Empty directories may be placeholders — 5-active-projects/ or 6-companies/ might be empty by design (populated by automation). Check registry.yaml or Makefile before flagging.

Common Issues

No markdown files found

Cause: Running in wrong directory or all files excluded. Fix: Ensure you're in the knowledge base root. Check exclude patterns in step 2.

Too many single-use tags

Cause: Inconsistent tagging across documents. Fix: Pick canonical tags from the most-used list. Run audit again after cleanup.

Frontmatter validation errors

Cause: YAML syntax issues (missing quotes, wrong indentation). Fix: Ensure --- delimiters are present. Use type: and status: values consistent with your KB's detected schema.