| name | documentation-structure-validator |
| description | Validate documentation structure, check for missing sections, verify markdown syntax, ensure consistency with templates. Use when user mentions docs validation, structure check, README review, documentation quality, or wants to verify documentation completeness. |
| allowed-tools | Read, Grep, Glob |
Documentation Structure Validator
Validate documentation files for completeness, structure, and consistency.
Instructions
- Identify the documentation type (README, ADR, API docs, guide)
- Load the appropriate template from templates.md
- Check for required sections and common issues
- Review markdown syntax and formatting
- Generate a validation report with:
- ✅ Passed checks
- ⚠️ Warnings
- ❌ Critical issues
- 💡 Recommendations
Validation Checklist
README Files
Architecture Decision Records (ADR)
API Documentation
Common Issues
Refer to validation-rules.md for detailed rules and examples.
Usage Examples
Example 1: Validate README
User: "Check if the README is complete"
Claude: *reads README.md, compares against template, generates report*
Example 2: Validate ADR
User: "Validate the architecture decision docs in /docs/decisions/"
Claude: *validates each ADR file against ADR template*
Example 3: Batch validation
User: "Check all markdown files in /docs/"
Claude: *scans all .md files, validates each based on type*
Output Format
# Documentation Validation Report
**File**: path/to/file.md
**Type**: README
**Date**: YYYY-MM-DD
## Summary
- Total checks: 15
- Passed: 12 ✅
- Warnings: 2 ⚠️
- Critical: 1 ❌
## Critical Issues ❌
1. Missing installation instructions
## Warnings ⚠️
1. No contributing guidelines link
2. Code examples not syntax-highlighted
## Passed ✅
- Title present
- Description clear
- Usage examples included
...
## Recommendations 💡
1. Add badges for build status and license
2. Include table of contents for easier navigation
3. Add troubleshooting section
Tips
- For templates, see templates.md
- For validation rules, see validation-rules.md
- Always provide actionable feedback
- Prioritize critical issues over style preferences
- Link to examples when suggesting improvements
