analyze-docs

analyze-docs

Perform comprehensive documentation analysis optimized for AI agent development workflows. Creates markdown-table-of-contents.md with architectural alignment insights and complexity annotations.

PRIMARY_ANALYSIS_OBJECTIVES

1. Create comprehensive markdown file inventory with AI agent context annotations
2. Analyze CLAUDE.md → AGENTS.md migration needs and custom guidance detection
3. Map C4 architecture levels (DSL L1-3 and PlantUML L4) with alignment status
4. Assess ROADMAP.md implementation progress with complexity scoring
5. Detect codebase-architecture divergences for governance tracking
6. Evaluate /ai_docs staleness and framework coverage
7. Analyze AI platform guidance consistency across CLAUDE.md, AGENTS.md, and Cursor rules

EXECUTION_SEQUENCE

PHASE_1: INTELLIGENT_FILE_DISCOVERY_AND_CLASSIFICATION

# Discover all documentation with context
echo "=== DOCUMENTATION DISCOVERY ==="
find . -name "*.md" -type f | while read file; do
    # Classify by AI agent relevance
    if [[ "$file" == *"CLAUDE.md"* ]] || [[ "$file" == *"AGENTS.md"* ]]; then
        echo "AI_AGENT_CONTEXT: $file"
    elif [[ "$file" == *"README.md"* ]]; then
        echo "HUMAN_CONTEXT: $file"
    else
        echo "MIXED_CONTEXT: $file"
    fi
done

# Discover architecture files with C4 level detection
echo "=== ARCHITECTURE DISCOVERY ==="
find . -name "*.dsl" -type f | while read file; do
    if grep -q "workspace\|container\|component" "$file"; then
        echo "STRUCTURIZR_DSL (C4 L1-3): $file"
    fi
done

find . -name "*.puml" -o -name "*.plantuml" | while read file; do
    echo "PLANTUML (C4 L4): $file"
done

PHASE_2: CLAUDE_MD_MIGRATION_ANALYSIS

# Analyze CLAUDE.md files for custom guidance
echo "=== CLAUDE.MD MIGRATION ANALYSIS ==="
find . -name "CLAUDE.md" -type f | while read file; do
    echo "Analyzing: $file"
    
    # Check if it's a pure pointer
    if grep -q "refer to.*AGENTS.md" "$file" && ! grep -q "^[^#]" "$file"; then
        echo "STATUS: Pure pointer (compliant)"
    else
        echo "STATUS: Contains custom guidance (needs migration)"
        # Extract custom content for migration
        grep -v "refer to.*AGENTS.md" "$file" | grep -v "^#.*AGENTS.md" > "${file}.custom"
    fi
done