# Documentation Quality Checklist for AI Agents

**Last Updated:** 2026-01-08

Comprehensive quality checklist for AI agents to ensure documentation meets standards and is optimized for discoverability.

## Metadata Completeness

### Required Metadata

- [ ] **"Last Updated" date** present and accurate (check with `date +%Y-%m-%d`)
- [ ] **File name** follows naming conventions (UPPERCASE_WITH_UNDERSCORES.md or [slug]-documentation.md)
- [ ] **File location** follows directory structure standards
- [ ] **Description** present in README files (if applicable)

### Rule File Metadata

- [ ] **description** field present in YAML frontmatter
- [ ] **globs** field present (empty array `[]` if no globs)
- [ ] **alwaysApply** field present (boolean)
- [ ] **Related Documentation** section present at end of file
- [ ] **Related rules** referenced if applicable

## Cross-References Present

### Documentation Files

- [ ] **"Related Documentation" section** present with links to:
  - Related guides
  - Related content docs
  - Related system docs
  - Related Cursor rules (if applicable)

### Rule Files

- [ ] **"Related Documentation" section** present with links to:
  - Related guides
  - Related content docs
  - Related system docs

### Bidirectional Links

- [ ] **Rule → Doc links** verified (rule links to doc)
- [ ] **Doc → Rule links** verified (doc links to rule)
- [ ] **Cross-references** work in both directions when applicable

## Links Validated

### Internal Links

- [ ] **All internal links** verified to exist
- [ ] **Relative paths** correct
- [ ] **Absolute paths** correct (from docs root)
- [ ] **Anchor links** verified (anchors exist in target files)

### External Links

- [ ] **External links** verified (if applicable)
- [ ] **URLs** correct and accessible

### Link Validation Tools

- Run `python3 scripts/documentation/validate-links.py` to check all links
- Review `docs/LINK_VALIDATION_REPORT.md` for broken links
- Fix broken links before committing

## Dates Current

### Date Checks

- [ ] **"Last Updated" date** is current (check with `date +%Y-%m-%d`)
- [ ] **Year references** in content are current (check with `date +%Y`)
- [ ] **No placeholder dates** (2026-01-20, 2026-01-20, etc.)
- [ ] **File modification dates** match "Last Updated" dates (if recently modified)

### Date Validation Tools

- Run `python3 scripts/documentation/update-dates.py --check` to verify dates
- Check for placeholder dates in content
- Update year references annually

## Templates Followed

### Documentation Structure

- [ ] **File structure** follows template from DOCUMENTATION_STANDARDS.md
- [ ] **Sections** match template structure
- [ ] **Content** follows template patterns

### Tool Documentation

- [ ] **Tool docs** follow `docs/guides/tools-pages/TOOL_DOCUMENTATION_TEMPLATE.md`
- [ ] **All required sections** present
- [ ] **Content** matches template structure

### Competitor Documentation

- [ ] **Competitor profiles** follow template (if template exists)
- [ ] **All required sections** present

## AI Discoverability Optimized

### Semantic Search

- [ ] **Headings** are descriptive and searchable
- [ ] **Keywords** included in headings and content
- [ ] **Common queries** addressed in documentation
- [ ] **Links to semantic search index** included (if applicable)

### Cross-References

- [ ] **"Related Documentation" section** present
- [ ] **"Related Cursor Rules" section** present (if applicable)
- [ ] **Cross-references** link to relevant content
- [ ] **Bidirectional links** verified

### File Naming

- [ ] **File name** follows conventions
- [ ] **File name** is descriptive and searchable
- [ ] **File location** follows directory structure

### Content Structure

- [ ] **Clear headings** that describe content
- [ ] **Consistent terminology** throughout
- [ ] **Cross-references** to related content
- [ ] **Metadata** complete and accurate

## Content Quality

### Writing Quality

- [ ] **Clear and concise** - Gets to the point quickly
- [ ] **Active voice** - Uses "Create the file" not "The file should be created"
- [ ] **Examples included** - Shows, doesn't just tell
- [ ] **Cross-referenced** - Links to related documentation

### Code Examples

- [ ] **Code examples** formatted correctly
- [ ] **Code examples** are clear and commented
- [ ] **File paths** are accurate
- [ ] **Syntax** is correct

### Lists and Tables

- [ ] **Consistent formatting** used
- [ ] **Tables** used for structured data
- [ ] **Lists** used for step-by-step instructions

## Validation Checklist

### Before Committing Documentation

- [ ] Run link validation: `python3 scripts/documentation/validate-links.py`
- [ ] Run date check: `python3 scripts/documentation/update-dates.py --check`
- [ ] Verify file naming conventions
- [ ] Check cross-references work
- [ ] Verify "Last Updated" date is accurate
- [ ] Check content quality (clarity, examples, cross-references)
- [ ] Verify AI discoverability (headings, keywords, cross-references)

### Before Committing Rules

- [ ] Verify metadata completeness (description, globs, alwaysApply)
- [ ] Check "Related Documentation" section present
- [ ] Verify glob patterns are correct
- [ ] Check cross-references to documentation
- [ ] Verify rule follows standards

## Related Documentation

- **[Documentation Standards](DOCUMENTATION_STANDARDS.md)** - File naming and structure
- **[Documentation Maintenance Process](DOCUMENTATION_MAINTENANCE_PROCESS.md)** - Update workflows
- **[AI Agent Guide](AI_AGENT_GUIDE.md)** - Complete documentation discovery guide
- **[Semantic Search Index](ai/SEMANTIC_SEARCH_INDEX.md)** - Query → documentation mapping
- **[Rule Discovery Patterns](ai/RULE_DISCOVERY_PATTERNS.md)** - File path → rule mapping