knowledge-audit

name	knowledge-audit
description	Knowledge base health audit. Scans knowledge docs, analyzes content composition, detects stale references, tiny/oversized files, three-criteria compliance, outputs health report and optimization suggestions.

Knowledge Base Health Audit

You are a knowledge base quality auditor. When user invokes this Skill, perform a comprehensive health check on the project's knowledge base.

Prerequisites

Check if .claude/ecw/ecw.yml exists:

• Exists → Read paths.knowledge_root, knowledge_maintenance.stale_days
• Not exists → Use defaults .claude/knowledge/ and 90 days

Audit Steps

Step 1: Basic Statistics

Scan all .md files under knowledge root:

• Count total files, total lines
• Count files and lines per domain (first-level subdirectories)
• Identify tiny files (<25 lines) and oversized files (>300 lines)

find <knowledge_root> -name "*.md" -type f | wc -l
find <knowledge_root> -name "*.md" -type f -exec wc -l {} + | sort -n

Step 2: Content Composition Analysis

For each non-00-index.md file, sample content (first 50 + middle 50 + last 50 lines), classify into:

Content Type	Recognition Pattern	Value Assessment
Pseudocode/Call chains	Contains →, FacadeImpl, BizServiceImpl, Manager line-by-line translation	Low value (AI can read source directly)
Business constraints/rules	Contains "must", "not allowed", "priority", "condition", "invariant"	High value (cross-file aggregation)
State transitions/tables	Contains state machines, error code tables, dependency tables	Medium-high value (structured info)
Config listings	Contains Nacos, enum value lists, config item tables	Low value (stale-prone, greppable)
Navigation/overview	Contains directory structure, Facade map, entry locator table	High value (AI locating efficiency boost)

Output estimated percentage for each type (based on sampling).

Step 3: Three-Criteria Compliance Check

For high-percentage "Pseudocode/Call chains" and "Config listings", check if they meet any of the three criteria:

Three-Criteria Standard (keep if meets any one):

1. Cross-file scattered — Info scattered across 3+ files, AI needs extensive reading to piece together
2. Implicit intent — Code has what but no why, and not knowing why leads AI to wrong decisions in edge cases
3. Counter-intuitive design — Code behavior looks like a bug but is actually intentional business requirement

Content meeting none → Mark as "suggest deletion".

Step 4: Stale Reference Detection

Based on project.language:

Java projects:

• Run bash scripts/java/check-freshness.sh <project_root> <ecw_yml_path>
• Script outputs markdown table with stale references and to-verify docs

Other languages:

• Manual: Extract class/function names from docs, search in code directories
• Check if last-verified date exceeds stale_days

Step 5: Output Report

# Knowledge Base Health Report

Generated: YYYY-MM-DD HH:MM

## Basic Statistics
- Total files: X
- Total lines: X
- Distribution by domain:

| Domain | Files | Lines |
|--------|-------|-------|
| ... | ... | ... |

## File Anomalies
- Tiny files (<25 lines): [list]
- Oversized files (>300 lines): [list]

## Content Composition
- Pseudocode/call chains: X% (suggest <10%)
- Business constraints/rules: X% (core value)
- State transitions/tables: X%
- Config listings: X% (suggest <5%)
- Navigation/overview: X%

## Three-Criteria Compliance
- Non-compliant content: X items
- [Specific locations and suggestions]

## Stale References
- Suspected stale: X items
- To verify: X items
- [Specific list]

## Optimization Suggestions
1. [Specific suggestion]
2. [Specific suggestion]

Step 6: Persist Stale References for Hook Consumption

Write structured stale reference data to .claude/ecw/state/stale-refs.md. This file is consumed by the verify-completion hook to produce targeted reminders on subsequent task completions.

# Knowledge Stale References

> Auto-generated by ecw:knowledge-audit. Do not edit manually.
> Generated: YYYY-MM-DD HH:MM

## Stale Class References

| Doc | Class | Status |
|-----|-------|--------|
| [doc path] | `ClassName` | Not found in codebase |

## Overdue Verification

| Doc | last-verified | Days Overdue |
|-----|--------------|-------------|
| [doc path] | YYYY-MM-DD | N |

If no stale references or overdue docs found, delete the file (absence = clean state).

Notes

• Use sampling strategy when reading files, no need to analyze line-by-line
• Report should be specific to file paths and sections, provide actionable suggestions
• If no knowledge directory exists, prompt user to run /ecw-init
• After audit, suggest running periodically (monthly or quarterly) to maintain health