Verify Documentation

Check documentation for consistency and completeness.

Usage

/docs-verify

Checks Performed

1. Rule Count Matches CLAUDE.md

ACTUAL=$(ls .claude/rules/*.md 2>/dev/null | wc -l | tr -d ' ')
LISTED=$(grep -c '^- `.*\.md`' CLAUDE.md)

if [ "$ACTUAL" -eq "$LISTED" ]; then
    echo "✓ Rule count matches: $ACTUAL rules"
else
    echo "✗ Mismatch: $ACTUAL files, $LISTED listed in CLAUDE.md"
    echo "  Actual files:"
    ls .claude/rules/*.md
fi

2. Check for Duplicate Type Definitions

echo ""
echo "Checking for Player struct definitions..."
PLAYER_DEFS=$(grep -l "struct Player" .claude/rules/*.md docs/**/*.md 2>/dev/null)

echo "  Should appear in:"
echo "    - .claude/rules/game-state.md (CANONICAL)"
echo "    - docs/api/types.md (reference to canonical)"
echo ""
echo "  Found in:"
echo "$PLAYER_DEFS" | while read file; do
    if [ ! -z "$file" ]; then
        HAS_CANONICAL=$(grep -c "CANONICAL" "$file" 2>/dev/null || echo "0")
        if [ "$HAS_CANONICAL" -gt 0 ]; then
            echo "    ✓ $file (CANONICAL)"
        else
            echo "    → $file (reference)"
        fi
    fi
done

3. Skill Count Matches

echo ""
SKILL_DIRS=$(ls -d .claude/skills/*/ 2>/dev/null | wc -l | tr -d ' ')
SKILL_ROWS=$(grep -c '^| `/.*`' CLAUDE.md)

if [ "$SKILL_DIRS" -eq "$SKILL_ROWS" ]; then
    echo "✓ Skill count matches: $SKILL_DIRS skills"
else
    echo "✗ Mismatch: $SKILL_DIRS directories, $SKILL_ROWS in table"
    echo "  Skill directories:"
    ls -d .claude/skills/*/
fi

4. Cross-References Valid

echo ""
echo "Checking cross-references in CLAUDE.md..."
grep -oh 'docs/[^)]*\.md' CLAUDE.md | sort -u | while read file; do
    if [ -f "$file" ]; then
        echo "  ✓ $file exists"
    else
        echo "  ✗ $file referenced but not found"
    fi
done

5. Agent Count

echo ""
AGENT_FILES=$(ls .claude/agents/*.md 2>/dev/null | wc -l | tr -d ' ')
echo "Agents: $AGENT_FILES files"
ls .claude/agents/*.md 2>/dev/null | while read file; do
    AGENT_NAME=$(basename "$file" .md)
    echo "  → $AGENT_NAME"
done

6. GitHub Templates Exist

echo ""
echo "Checking GitHub issue templates..."
TEMPLATES=("bug_report.md" "feature_request.md" "task.md" "config.yml")
LABELS_FILE=".github/labels.json"

for template in "${TEMPLATES[@]}"; do
    if [ -f ".github/ISSUE_TEMPLATE/$template" ]; then
        echo "  ✓ $template"
    else
        echo "  ✗ $template missing"
    fi
done

if [ -f "$LABELS_FILE" ]; then
    LABEL_COUNT=$(jq 'length' "$LABELS_FILE" 2>/dev/null || echo "?")
    echo "  ✓ labels.json ($LABEL_COUNT labels defined)"
else
    echo "  ✗ labels.json missing"
fi

Final Report

Generate summary report:

Documentation Verification Report
===================================
Date: [timestamp]

Rules: [X/Y] ✓
Skills: [X/Y] ✓
Agents: [N] ✓
Cross-references: [Status]
GitHub templates: [X/4] ✓

Issues Found: [count]
[List any issues]

Recommendations:
[If issues found, suggest fixes]

Example Output

Documentation Verification Report
===================================

✓ Rule count matches: 8 rules
✓ Player struct found in correct locations
✓ Skill count matches: 19 skills
✓ All cross-references valid
✓ Agents: 6 files
  → architect
  → bug-hunter
  → code-reviewer
  → game-designer
  → play-tester
  → test-runner
✓ GitHub templates: 4/4 ✓
  ✓ bug_report.md
  ✓ feature_request.md
  ✓ task.md
  ✓ config.yml
  ✓ labels.json (16 labels defined)

Issues Found: 0

Last verified: 2026-01-25 18:45:00
Status: All checks passed ✓

Use Cases

Before committing documentation changes:

/docs-verify
→ Ensure all references are consistent

After adding new skill:

/docs-verify
→ Check skill count matches CLAUDE.md

Weekly maintenance:

/docs-verify
→ Catch any drift or inconsistencies

Notes

• Non-destructive: only reads files, never modifies
• Can be run anytime without risk
• Use /docs-update to fix issues found
• Requires jq for JSON parsing (labels.json check)