gh-mgiovani-cc-arsenal/commands/docs/check.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Validate documentation freshness, completeness, and quality	[focus]	Read Grep Glob Bash(git *, find *)

Check Documentation Quality

Validate documentation freshness, completeness, and quality against current codebase state.

Your Task

1. Parse Arguments:

   • Extract optional focus area from $ARGUMENTS
   • Focus areas: core, data, infrastructure, all
   • Default: check all documentation

2. Scan Documentation:

   • Find all documentation files in docs/
   • Identify documentation types present
   • Check for ADRs and RFCs

3. Analyze Project (determine what docs should exist):

   • Technology stack detection
   • Database presence
   • Deployment configurations
   • Project type (library, app, service)

4. Perform Validation Checks:

   A. Relevance Check:

   • Determine which docs are relevant to this project
   • Identify missing documentation for detected technologies
   • Example: If database models found, should have data-model.md

   B. Freshness Check:

   • Compare doc last-modified dates with related code changes
   • Use git to check recent changes:

   # Check when files were last modified
   !`git log -1 --format="%ai" -- docs/architecture.md 2>/dev/null`
   
   # Check recent changes to codebase
   !`git log --since="7 days ago" --oneline --name-only | head -50`
   

   • Flag docs that haven't been updated after significant code changes

   C. Completeness Check:

   • Verify all required sections are present
   • Check for unreplaced placeholders: {{PLACEHOLDER}}
   • Ensure diagrams exist where expected
   • Verify ADRs have all sections (Status, Context, Decision)
   • Verify RFCs have all sections (Summary, Motivation, Proposal)

   D. Quality Check:

   • Validate Mermaid diagram syntax
   • Check for broken internal links (references to non-existent files)
   • Verify markdown formatting
   • Check for empty sections

5. Calculate Scores:

   Freshness Scoring (per document):

   • Fresh (90-100): Updated within last 7 days or no related code changes
   • Good (70-89): Minor code changes since last update
   • Stale (50-69): Significant code changes since last update
   • Outdated (<50): Major code changes or very old

   Completeness Scoring (per document):

   • Complete (90-100): All sections present, no placeholders
   • Good (70-89): Most sections present, minor gaps
   • Incomplete (50-69): Several missing sections
   • Poor (<50): Major sections missing

   Quality Scoring (per document):

   • Excellent (90-100): No issues, all diagrams valid
   • Good (70-89): Minor formatting issues
   • Fair (50-69): Several issues
   • Poor (<50): Major problems, broken diagrams

   Overall Score:

   • Average of all document scores
   • Weight by importance (core docs > others)

6. Generate Report:

   • Status summary with overall score
   • List of documents by status (Good, Needs Attention, Missing)
   • Quality issues with specific locations
   • Actionable recommendations

Validation Checks Detail

Missing Documentation

# Check for expected docs
!`ls -1 docs/ 2>/dev/null | grep -E "architecture|onboarding|data-model|deployment"`

# Check for ADRs
!`ls -1 docs/adr/*.md 2>/dev/null | wc -l`

# Check for RFCs
!`ls -1 docs/rfc/*.md 2>/dev/null | wc -l`

Stale Documentation

# Get last modification date of docs
!`find docs -name "*.md" -exec stat -f "%Sm %N" -t "%Y-%m-%d" {} \; 2>/dev/null || find docs -name "*.md" -exec stat -c "%y %n" {} \;`

# Get recent code changes
!`git log --since="30 days ago" --name-only --pretty=format: | sort -u | grep -v "^$" | head -30`

Placeholder Check

# Find unreplaced placeholders
!`grep -r "{{.*}}" docs/ --include="*.md" 2>/dev/null`

Broken Links

# Find markdown links
!`grep -r "\[.*\](" docs/ --include="*.md" -h | grep -o "\[.*\](.*)" | head -20`

Usage

Check all documentation:

/docs:check

With specific focus:

/docs:check core
/docs:check data
/docs:check focus on database documentation

Quick check:

/docs:check quick

Output Format

Status Summary

Documentation Health Report

Overall Score: 85/100

✅ Good (3 docs):
  • docs/architecture.md (Score: 95/100)
    - Last updated: 2 days ago
    - All sections complete
    - Diagrams valid

  • docs/onboarding.md (Score: 92/100)
    - Last updated: 1 week ago
    - Comprehensive and current

  • docs/adr/ (5 records, Score: 88/100)
    - All ADRs properly formatted
    - Recent decisions documented

⚠️ Needs Attention (2 docs):
  • docs/data-model.md (Score: 65/100)
    - Outdated: Models changed 5 days ago (docs/data-model.md:1)
    - Missing ER diagram
    → Recommendation: Run /docs:diagram er

  • docs/deployment.md (Score: 58/100)
    - Missing deployment steps for new services
    - Placeholder not replaced: {{DEPLOYMENT_STEPS}} (line 42)
    → Recommendation: Run /docs:update deployment

❌ Missing (2 docs):
  • docs/security.md
    - Security middleware detected but not documented
    → Recommendation: Run /docs:init or /docs:diagram security

  • docs/api-documentation.md
    - 15 API endpoints found but not documented
    → Recommendation: Run /docs:init

🔧 Quality Issues:
  • docs/data-model.md:42 - Invalid Mermaid syntax
  • docs/architecture.md:15 - Broken link to [non-existent.md]
  • docs/deployment.md:23 - Unreplaced placeholder {{DEPLOYMENT_STEPS}}

Detailed Report

For each documentation file:

• Filename and path
• Score breakdown (Freshness + Completeness + Quality)
• Last Updated: Timestamp
• Specific Issues: With line numbers
• Recommendations: Actionable next steps with commands

Recommendations Format

Based on findings, suggest specific actions:

Priority Recommendations:

1. HIGH: Update data model documentation
   Command: /docs:diagram er
   Reason: Schema changed 5 days ago, ER diagram missing

2. MEDIUM: Fix deployment documentation placeholders
   Command: /docs:update deployment
   Reason: Contains unreplaced placeholders

3. LOW: Add security documentation
   Command: /docs:diagram security
   Reason: Good practice for complete documentation

Important Notes

• Non-destructive: Only reads, never modifies documentation
• Git-aware: Uses git history to assess freshness
• Context-aware: Understands project type and relevant docs
• Actionable: Provides specific commands to fix issues
• Incremental: Can be run frequently

Example Checks

Core Documentation

• architecture.md exists and current?
• onboarding.md exists and comprehensive?
• ADRs directory exists with properly formatted ADRs?

Data Documentation

• data-model.md exists if database detected?
• ER diagrams present and valid?
• Schema matches current models?

Infrastructure Documentation

• deployment.md exists if Docker/K8s detected?
• Security.md exists?
• Dependencies documented?

When to Run

Run this command:

• Before onboarding new team members
• During documentation reviews
• After major refactoring
• As part of pre-release checklist
• When documentation feels stale
• Regularly (weekly or bi-weekly)

Best Practices

• Run regularly: Make it part of your workflow
• Address issues: Don't let documentation debt accumulate
• Automate: Consider running in CI for documentation PRs
• Prioritize: Fix high-impact issues first
• Track scores: Monitor documentation health over time

---

Dependencies: Requires git for freshness checking Output: Comprehensive health report with scores and recommendations