doctor

/doctor — Repo Health Check

Purpose

One command that catches all drift, broken promises, stale counts, and missing files. The template should never promise what it doesn't ship.

Checks (run all programmatically)

1. Count Accuracy

Run these and compare with README.md badge/table values:

# Actual counts
AGENTS=$(ls .claude/agents/ | wc -l | tr -d ' ')
SKILLS=$(find .claude/skills -name "SKILL.md" | wc -l | tr -d ' ')
HOOKS=$(ls .claude/hooks/ | wc -l | tr -d ' ')
RULES=$(ls .claude/rules/ | wc -l | tr -d ' ')
TEMPLATES=$(ls .claude/docs/templates/ | wc -l | tr -d ' ')
WIKI_PAGES=$(find wiki -name "*.md" -not -path "wiki/raw/*" -type f | wc -l | tr -d ' ')
RAW_SOURCES=$(find wiki/raw -name "*.md" -type f | wc -l | tr -d ' ')

echo "Agents: $AGENTS"
echo "Skills: $SKILLS"
echo "Hooks: $HOOKS"
echo "Rules: $RULES"
echo "Templates: $TEMPLATES"
echo "Wiki pages: $WIKI_PAGES"
echo "Raw sources: $RAW_SOURCES"

Then grep README.md for the claimed numbers and flag any mismatch.

2. Promised Files Exist

Check every file referenced in .claude/docs/directory-structure.md:

# Tool scripts
for f in tools/setup.sh tools/build.sh tools/lint.sh tools/test.sh; do
    [ -f "$f" ] && echo "✅ $f" || echo "❌ $f MISSING"
done

# Toolchain configs
for f in default.project.json selene.toml stylua.toml wally.toml aftman.toml; do
    [ -f "$f" ] && echo "✅ $f" || echo "❌ $f MISSING"
done

# CI
[ -f ".github/workflows/ci.yml" ] && echo "✅ CI workflow" || echo "❌ CI workflow MISSING"

# Production files
for f in production/decision-log.md production/risk-register.md; do
    [ -f "$f" ] && echo "✅ $f" || echo "❌ $f MISSING"
done

# Core docs
for f in CLAUDE.md README.md LICENSE .gitignore UPGRADING.md; do
    [ -f "$f" ] && echo "✅ $f" || echo "❌ $f MISSING"
done

3. Unresolved Placeholders

# Scan for common placeholder patterns
grep -rn "\[CHOOSE:" CLAUDE.md README.md .claude/docs/ 2>/dev/null
grep -rn "\[TODO:" CLAUDE.md README.md 2>/dev/null
grep -rn "\[PLACEHOLDER" CLAUDE.md README.md 2>/dev/null
grep -rn "TBD\|tbd" CLAUDE.md README.md 2>/dev/null | grep -v "^Binary"