davila7__claude-code-templates/cli-tool/components/commands/documentation/docs-maintenance.md

allowed-tools: Read, Write, Edit, Bash, Grep argument-hint: [maintenance-type] | --audit | --update | --validate | --optimize | --comprehensive description: Use PROACTIVELY to implement comprehensive documentation maintenance systems with quality assurance, validation, and automated updates

Documentation Maintenance & Quality Assurance

Implement comprehensive documentation maintenance system: $ARGUMENTS

Current Documentation Health

• Documentation files: !find . -name "*.md" -o -name "*.mdx" | wc -l files
• Last updates: !find . -name "*.md" -exec stat -f "%m %N" {} \; | sort -n | tail -5
• External links: !grep -r "http" --include="*.md" . | wc -l links to validate
• Image references: !grep -r "!\[.*\]" --include="*.md" . | wc -l images to check
• Documentation structure: @docs/ or detect documentation directories

Task

Create systematic documentation maintenance framework with automated quality assurance, comprehensive validation, content optimization, and regular update procedures.

Documentation Maintenance Framework

1. Content Quality Audit System

• Comprehensive file discovery and categorization
• Content freshness analysis and aging detection
• Word count, readability, and structure assessment
• Missing sections and incomplete documentation identification
• TODO/FIXME marker tracking and resolution planning

2. Link and Reference Validation

• External link health monitoring with retry logic
• Internal link validation and broken reference detection
• Image reference verification and missing asset identification
• Cross-reference consistency checking
• Automated link correction suggestions

3. Style and Consistency Checking

• Markdown syntax validation and formatting standards
• Heading hierarchy and structure consistency
• List formatting and emphasis style uniformity
• Code block formatting and language specification
• Accessibility compliance (alt text, descriptive links)

4. Content Optimization and Enhancement

• Table of contents generation for long documents
• Metadata updating and frontmatter management
• Common formatting issue correction
• Spelling and grammar validation
• Readability analysis and improvement suggestions

5. Automated Synchronization System

• Git-based change tracking and documentation updates
• Version control integration with branch management
• Automated commit generation with detailed change logs
• Merge conflict resolution strategies
• Rollback procedures for failed updates

6. Quality Assurance Reporting

• Comprehensive audit reports with severity classifications
• Issue categorization and prioritization systems
• Progress tracking and maintenance metrics
• Automated notification systems for critical issues
• Dashboard creation for ongoing monitoring

Implementation Requirements

Audit Configuration

• Configurable quality thresholds and validation rules
• Custom style guide integration and enforcement
• Platform-specific optimization settings
• Team collaboration workflow integration
• Automated scheduling and recurring maintenance

Validation Processes

• Multi-level validation with error categorization
• Batch processing for large documentation sets
• Performance optimization for comprehensive scans
• Integration with existing CI/CD pipelines
• Real-time monitoring and alerting systems

Reporting and Analytics

• Detailed maintenance reports with actionable insights
• Historical trend analysis and improvement tracking
• Team productivity metrics and documentation health scores
• Integration with project management tools
• Automated stakeholder communication

Deliverables

1. Maintenance System Architecture

   • Automated audit and validation framework
   • Content optimization and enhancement tools
   • Quality assurance reporting infrastructure
   • Version control integration and synchronization

2. Validation and Quality Tools

   • Link checking and reference validation systems
   • Style consistency and accessibility compliance tools
   • Content freshness and completeness analyzers
   • Automated correction and enhancement utilities

3. Reporting and Monitoring

   • Comprehensive audit reports with prioritized recommendations
   • Real-time monitoring dashboards and alert systems
   • Progress tracking and maintenance history documentation
   • Integration with team communication and project tools

4. Documentation and Procedures

   • Implementation guidelines and configuration instructions
   • Team workflow integration and collaboration procedures
   • Troubleshooting guides and maintenance best practices
   • Automated scheduling and recurring maintenance setup

Integration Guidelines

Implement with existing documentation platforms and development workflows. Ensure scalability for large documentation sets and team collaboration while maintaining quality standards and accessibility compliance.