SKILL: Documentation Verification

Purpose: Validate 3-Tier documentation system compliance - line limits, cross-references, file counts

Quick Start

When to Use

• After closing plan (/03_close)
• After running /document
• Before committing documentation changes

Quick Reference

bash
1# Pure bash link check (no external deps)
2for file in CLAUDE.md docs/ai-context/*.md; do
3  [ -f "$file" ] || continue
4  grep -oE '@[^][:space:]]+' "$file" | while read ref; do
5    ref_path="${ref#@}"
6    [ ! -e "$ref_path" ] && echo "Broken: $ref in $file"
7  done
8done

Change Detection (MANDATORY FIRST STEP)

Before running verification, check if docs changed:

bash
1# Get changed markdown files (with fallback)
2CHANGED_MD=$(git diff --name-only HEAD~1 -- "*.md" 2>/dev/null || git diff --name-only -- "*.md" 2>/dev/null || echo "FALLBACK_FULL_VERIFY")
3
4# Fallback: If git diff fails, run full verification
5if [ "$CHANGED_MD" = "FALLBACK_FULL_VERIFY" ]; then
6    echo "Cannot detect changes, running full verification"
7    CHANGED_MD=$(find . -name "*.md" -type f ! -path "*/.git/*" ! -path "*/.trash/*")
8fi
9
10if [ -z "$CHANGED_MD" ]; then
11    echo "No markdown files changed"
12    echo "Skipping documentation verification"
13    exit 0
14fi
15
16echo "Changed markdown files:"
17echo "$CHANGED_MD"

Core Concepts

3-Tier System

Tier 1 (3 files, ≤200 lines each):

• CLAUDE.md - Project architecture, features, Quick Start
• docs/ai-context/project-structure.md - Tech stack, file tree
• docs/ai-context/docs-overview.md - Documentation navigation

Tier 2: Component CONTEXT.md files (unlimited)

Tier 3: Feature-specific CONTEXT.md files

Verification Checks

1. Tier 1 Line Limits (Changed Files Only)

Limit: ≤200 lines per file

bash
1TIER1_FILES=(
2  "CLAUDE.md"
3  "docs/ai-context/project-structure.md"
4  "docs/ai-context/docs-overview.md"
5)
6
7for file in "${TIER1_FILES[@]}"; do
8  # Only check if file was changed
9  if echo "$CHANGED_MD" | grep -q "$file"; then
10    LINES=$(wc -l < "$file" | tr -d ' ')
11    if [ "$LINES" -gt 200 ]; then
12      echo "FAIL: $file has $LINES lines (limit: 200)"
13      exit 1
14    fi
15    echo "$file: $LINES lines"
16  fi
17done

On violation: Extract content to Tier 2 CONTEXT.md files

2. Tier 1 File Count (CRITICAL)

Limit: Exactly 2 files in docs/ai-context/

bash
1COUNT=$(find docs/ai-context -maxdepth 1 -name "*.md" -type f | wc -l | tr -d ' ')
2if [ "$COUNT" -ne 2 ]; then
3  echo "FAIL: docs/ai-context/ has $COUNT files (expected: 2)"
4  exit 1
5fi

3. Cross-Reference Validation (Changed Files Only)

bash
1# Only validate changed files
2for file in $CHANGED_MD; do
3  [ -f "$file" ] || continue
4  grep -oE '@\.(claude|docs)/[^][:space:]]+' "$file" 2>/dev/null | while read ref; do
5    ref_path="${ref#@}"
6    ref_path="${ref_path%[\`\*\]\"]}"
7    if [ ! -e "$ref_path" ]; then
8      echo "Broken reference: $ref in $file"
9    fi
10  done
11done

4. Circular Reference Detection

bash
1# Check for self-references (A → A)
2find . -name "*.md" ! -path "*/REFERENCE.md" ! -path "*/.git/*" | while read file; do
3  refs=$(grep -oE '@\.(claude|docs)/[^)[:space:]+' "$file" || true)
4  for ref in $refs; do
5    if [ "${ref#@}" = "$file" ]; then
6      echo "Self-reference: $file"
7    fi
8  done
9done

5. Skill Count Validation

bash
1ACTUAL=$(find .claude/skills -name "SKILL.md" | wc -l | tr -d ' ')
2STATED=$(grep -oE '\*\*[0-9]+ Skills\*\*' README.md | grep -oE '[0-9]+' || echo "0")
3
4if [ "$ACTUAL" -ne "$STATED" ]; then
5  echo "WARNING: Skill count mismatch - README: $STATED, actual: $ACTUAL"
6fi

Integration Pattern

In Commands

markdown
1## Step 3: Documentation Verification
2
3Invoke the `docs-verify` skill to validate documentation compliance.
4
5The skill checks:
6- Tier 1 line limits (≤200 lines)
7- Tier 1 file count (exactly 2 in ai-context/)
8- Cross-reference validity
9- Circular references

Claude reads this skill file and executes the bash commands inline.

Related Skills

three-tier-docs: Full 3-Tier documentation system | vibe-coding: File size standards

Version: claude-pilot 4.4.14