docs-analyzer

name	docs-analyzer
description	Analyzes code changes and identifies documentation gaps. Scans git history, catalogs existing docs, and generates comprehensive analysis reports.
allowed-tools	Read, Grep, Glob, Bash
user-invocable	true

Documentation Analyzer Skill

Purpose

This skill specializes in analyzing codebases to identify documentation gaps and assess the impact of code changes on existing documentation. It provides structured reports to guide documentation updates.

When to Activate

Use this skill when:

• Starting documentation review for a project
• Analyzing impact of recent code changes
• Auditing documentation completeness
• Preparing for documentation updates
• User requests documentation analysis

Core Workflow

Step 1: Catalog Existing Documentation

Scan and catalog all documentation files in the repository:

Documentation Files to Find:

• README.md (root and subdirectories)
• docs/ directory contents
• CONTRIBUTING.md
• CHANGELOG.md
• *.md files throughout the codebase
• API documentation (OpenAPI/Swagger specs)
• Architecture diagrams and documentation

Use Glob and Read tools:

# Find all markdown files
Glob: "**/*.md"

# Find documentation directories
Glob: "**/docs/**/*"

# Find API specs
Glob: "**/*.{yaml,yml,json}" (for OpenAPI specs)

Catalog Output:

• List of all documentation files found
• Brief description of each file's purpose
• Last modified date (from git)
• Current state assessment (complete, outdated, missing sections)

Step 2: Analyze Git History

Use Bash tool to analyze recent code changes and identify affected components.

Git Commands to Run:

# Get recent commits (last 10-50 depending on activity)
git log --oneline -20

# Get detailed diff for recent changes
git diff HEAD~10..HEAD --stat

# Identify changed files by type
git diff HEAD~10..HEAD --name-only

# Get commit messages for context
git log HEAD~10..HEAD --pretty=format:"%h - %s"

Analyze:

• Files modified (by extension and directory)
• Commit messages (feature, fix, refactor indicators)
• Areas of codebase affected (frontend, backend, infrastructure, etc.)

Step 3: Identify Affected Components

Based on file changes, determine which components were modified:

Backend Projects (Django, FastAPI, Express, etc.):

• API endpoints (routes, views, controllers)
• Data models (ORM models, schemas)
• Database migrations
• Background tasks
• Services and business logic
• Authentication/authorization
• Middleware

Frontend Projects (React, Vue, Angular, etc.):

• Components
• State management
• Routing
• API integrations
• UI/styling
• Build configuration

Infrastructure (Terraform, Kubernetes, etc.):

• Resource definitions
• Configuration changes
• Deployment scripts
• CI/CD pipelines

Use Grep to Search:

# Find API endpoint definitions
Grep: pattern="@app\\.(get|post|put|delete)" (FastAPI)
Grep: pattern="class.*ViewSet|class.*APIView" (Django)
Grep: pattern="router\\.(get|post)" (Express)

# Find model definitions
Grep: pattern="class.*\\(models\\.Model\\)" (Django)
Grep: pattern="class.*\\(BaseModel\\)" (Pydantic/FastAPI)

# Find component definitions
Grep: pattern="function.*Component|const.*Component" (React)
Grep: pattern="export default.*defineComponent" (Vue)

Step 4: Detect Documentation Gaps

Compare code changes against existing documentation to identify gaps.

Gap Categories:

1. Missing Documentation:

   • New features without README updates
   • New API endpoints not documented
   • New models/schemas without descriptions
   • New components without usage examples

2. Outdated Documentation:

   • API docs referencing removed endpoints
   • Installation instructions outdated
   • Configuration examples missing new options
   • Architecture diagrams not reflecting current structure

3. Incomplete Documentation:

   • API docs missing request/response examples
   • README missing setup instructions
   • No architecture overview
   • Missing deployment guide
   • Absence of Mermaid diagrams for complex flows

4. Inconsistent Documentation:

   • README contradicts code
   • API docs show wrong endpoint paths
   • Environment variables documented differently than used

Step 5: Assess Documentation Impact

For each gap, determine severity and priority:

Severity Levels:

• 🔴 Critical: Blocks users from using the project (missing setup, wrong install commands)
• 🟡 High: Significantly impacts understanding (missing API docs, outdated architecture)
• 🟢 Medium: Helpful but not blocking (missing examples, incomplete guides)
• 🔵 Low: Nice-to-have (additional diagrams, expanded explanations)

Priority Factors:

• User impact (external users vs internal team)
• Feature visibility (public API vs internal utility)
• Change magnitude (major refactor vs minor fix)
• Documentation type (critical README vs supplementary guide)

Step 6: Generate Analysis Report

Create a structured report with findings:

Report Format:

# Documentation Analysis Report

## Summary
- Total documentation files: X
- Files analyzed: Y
- Gaps identified: Z
- Last commit analyzed: [commit hash]

## Existing Documentation
### Complete ✅
- [file path]: [brief description]

### Outdated ⚠️
- [file path]: [what's outdated]

### Missing ❌
- [expected file]: [why it's needed]

## Code Changes Detected
### Modified Components
- [component type]: [list of components]

### Impact Areas
- [area]: [description of changes]

## Documentation Gaps

### Critical 🔴
1. **[Gap Title]**
   - **Affected File**: [file path or "Not exists"]
   - **Issue**: [description]
   - **Code Reference**: [file:line or component]
   - **Recommendation**: [what to add/update]

### High Priority 🟡
[same format as above]

### Medium Priority 🟢
[same format as above]

### Low Priority 🔵
[same format as above]

## Recommendations

### Immediate Actions
1. [action item]
2. [action item]

### Suggested Updates
- **[file path]**: [specific section to update]
- **New files**: [files to create]

### Diagrams Needed
- [diagram type]: [what it should show]
 [diagram type]: [what it should show]


 Review this report
 Prioritize gap remediation
 Invoke docs-bootstrapper for missing structure (if needed)
 Update documentation with approved changes

Output Specification

The report should be:

• Actionable: Clear recommendations for each gap
• Prioritized: Ordered by severity
• Specific: Reference exact files, lines, components
• Comprehensive: Cover all gap categories
• Structured: Easy to scan and understand

Integration with Other Skills

This skill is designed to work with:

• docs-manager: Invoked by docs-manager to get analysis before updates
• docs-bootstrapper: Identifies when bootstrapping is needed
• mermaid-expert: Identifies where diagrams are needed

Example Usage

Scenario: User made changes to authentication system

docs-analyzer actions:

1. Catalogs existing docs: README.md, docs/api.md, docs/auth.md
2. Analyzes git history: Finds changes in auth/ directory
3. Identifies affected components: AuthService, LoginEndpoint, User model
4. Detects gaps:
   • README missing new OAuth setup
   • API docs show old token format
   • No sequence diagram for auth flow
5. Generates report with priorities
6. Returns structured report to caller

Guidelines

Do:

• ✅ Analyze git history comprehensively
• ✅ Catalog all documentation files
• ✅ Provide specific file/line references
• ✅ Prioritize gaps by user impact
• ✅ Generate actionable recommendations
• ✅ Return structured, parseable reports

Don't:

• ❌ Make assumptions about what documentation should contain
• ❌ Skip cataloging existing docs
• ❌ Generate vague recommendations
• ❌ Ignore commit messages and git context
• ❌ Overwhelm with low-priority items
• ❌ Make documentation changes (read-only analysis)

Standalone Usage

While designed for orchestration, this skill can be invoked directly:

User: /docs-analyzer

Skill: Analyzes codebase and generates comprehensive documentation gap report

This allows developers to audit documentation health independently from the update workflow.