Task

Perform comprehensive documentation readiness review for pull requests, ensuring documentation is accurate, complete, megadoc-compliant, and ready for merge.

Context

This review is performed when:

• PR contains documentation changes
• New features require documentation
• Code changes may affect existing documentation
• Repository is preparing for megadoc inclusion

The review ensures documentation quality before changes reach production.

Review Process

Phase 1: Code-Documentation Alignment

1.1 Identify Code Changes

Analyze PR diff:

• New features added
• Existing functionality modified
• Functions/APIs removed or deprecated
• Configuration changes
• Behavioral changes

Output: List of code changes that require documentation

1.2 Verify Documentation Coverage

For each code change, check:

New features:

• How-to guide exists for using the feature
• API/reference documentation added
• Configuration options documented
• Examples provided
• Integration instructions included

Modified functionality:

• Existing docs updated to reflect changes
• Examples still work with new code
• Parameter descriptions accurate
• Deprecated features marked

Removed functionality:

• Documentation removed or marked deprecated
• Migration guide provided (if breaking change)
• Archived for reference (if needed)

Configuration changes:

• New options documented
• Changed defaults updated
• Deprecated options marked
• Examples updated

1.3 Test Examples

Extract code examples from documentation:

# Find code blocks in docs
grep -A 10 '```' docs/**/*.md

Verify:

• Syntax is correct
• Examples are executable
• Output matches documentation
• Examples use current API
• No deprecated patterns

1.4 Check for Documentation Drift

Compare documentation claims vs code reality:

• Default values in code match docs
• Function signatures match API reference
• Behavior descriptions accurate
• Error messages correct
• Return types documented correctly

Flag discrepancies for correction.

Phase 2: Megadoc Compliance

2.1 Stub Configuration

Check mkdocs.yml:

# Required fields
✅ site_name: { value }
✅ repo_url: { value }
✅ repo_name: { value }
✅ edit_uri: { value }

# Forbidden fields (should NOT be present)
❌ theme:
❌ plugins:
❌ markdown_extensions:

Validation:

• All required fields present
• No forbidden fields
• YAML syntax valid
• Navigation references existing files

2.2 Front Matter Compliance

Check every markdown file:

---
title: { value } # ✅ Required
description: { value } # ✅ Required
owner: { value } # ✅ Required
doc_type: { valid-value } # ✅ Required (how-to|reference|runbook|concept)
lifecycle_status: { value } # ✅ Required (active|experimental|deprecated)
last_reviewed: { YYYY-MM-DD } # ✅ Required
tags: [{ array }] # ✅ Required
---

Validation checklist:

• All files have front matter
• All required fields present
• Valid doc_type value
• Valid lifecycle_status
• Date format correct (YYYY-MM-DD)
• Last_reviewed is recent
• Tags are relevant and accurate

2.3 Diátaxis Organization

Verify correct categorization:

how-to (Task-oriented):

• Focuses on accomplishing a specific goal
• Step-by-step instructions
• Located in docs/how-to/
• Front matter: doc_type: how-to

reference (Information-oriented):

• Lookup/dictionary format
• Technical specifications
• Located in docs/reference/
• Front matter: doc_type: reference

runbook (Procedural):

• Operational procedures
• Incident response steps
• Located in docs/runbooks/
• Front matter: doc_type: runbook

concept (Understanding-oriented):

• Explains architecture/design
• Provides context and background
• Located in docs/ or docs/concepts/
• Front matter: doc_type: concept

Check for misclassifications:

• API documentation labeled as "how-to" → should be "reference"
• Step-by-step guide labeled as "concept" → should be "how-to"
• Troubleshooting procedure labeled as "reference" → should be "runbook"

Phase 3: Content Quality

3.1 Style Guide Adherence

Headings:

✅ Sentence case:

# Getting started

## Installation steps

❌ Title case:

# Getting Started

## Installation Steps

Code blocks:

✅ Annotated:

```yaml
key: value
```

❌ Not annotated:

key: value

**Links**:
```markdown
✅ Relative:
[Config](./reference/config.md)

❌ Absolute:
[Config](/docs/reference/config.md)

Lists:

✅ Parallel structure:

- Install dependency
- Configure options
- Run application

❌ Inconsistent:

- Install dependency
- Configuration of options
- Running the application

3.2 Grammar and Clarity

Check for:

• Spelling errors
• Grammar mistakes
• Unclear instructions
• Ambiguous pronouns
• Passive voice overuse
• Run-on sentences

Readability:

• Short paragraphs (3-5 sentences)
• Clear headings
• Logical flow
• Progressive disclosure (simple → complex)

3.3 Completeness

For how-to guides:

• Prerequisites listed
• Step-by-step instructions
• Expected outcomes stated
• Troubleshooting hints
• Next steps provided

For reference docs:

• All options documented
• Types specified
• Defaults stated
• Examples provided
• Constraints noted

For runbooks:

• Trigger conditions clear
• Diagnostic steps included
• Resolution procedures detailed
• Verification steps provided
• Escalation path defined

For concepts:

• Clear explanations
• Diagrams where helpful
• Context provided
• Related concepts linked
• Further reading suggested

3.4 Accuracy Verification

Technical accuracy:

• Command syntax correct
• File paths valid
• URLs reachable
• Configuration examples valid
• Code samples syntactically correct

Version accuracy:

• Version numbers current
• Deprecated features marked
• New features indicated
• Compatibility notes accurate

Phase 4: Build and Integration

4.1 Local Build Test

# Test build in isolation
cd {repository}
mkdocs build --strict

Expected: Build succeeds with no errors

Check for:

• No file-not-found errors
• No broken navigation
• No YAML syntax errors
• No markdown rendering issues

4.2 Serve Test

mkdocs serve

Visit http://localhost:8000 and verify:

• Pages render correctly
• Navigation works
• Links function properly
• Code highlighting present
• Search works
• Edit buttons point correctly

4.3 Link Validation

Check internal links:

# Extract and test links
grep -r "](.*\.md)" docs/ | while read link; do
  # Check if target exists
done

Validation:

• All internal links work
• External links are reachable
• Anchor links target valid headings
• No 404 errors

4.4 Integration Test (if megadoc submodule)

Test in megadoc context:

# In ohemr-epic-megadoc
git submodule update --remote submodules/{repo}
mkdocs build --strict

Verify:

• Megadoc build succeeds
• Repository docs appear in navigation
• Navigation structure correct
• Edit links work
• No conflicts with other submodules

Phase 5: Review Checklist

5.1 Documentation Changes Summary

Prepare summary:

## Documentation Changes

### Added

- New how-to guide: {title}
- API reference: {endpoint/feature}
- Configuration option: {option}

### Modified

- Updated {guide} to reflect {change}
- Fixed {error} in {file}
- Clarified {concept} in {file}

### Removed

- Deprecated {feature} documentation
- Archived {old-guide}

### Code-Documentation Alignment

- ✅ All new features documented
- ✅ Modified behavior updated in docs
- ✅ Examples tested and working
- ✅ No documentation drift detected

5.2 Compliance Checklist

Megadoc Compliance:

• ✅ mkdocs.yml stub valid
• ✅ Front matter on all files
• ✅ Diátaxis categorization correct
• ✅ Style guide followed
• ✅ No forbidden fields in stub

Quality Standards:

• ✅ Spelling and grammar correct
• ✅ Technical accuracy verified
• ✅ Examples tested
• ✅ Links validated
• ✅ Complete coverage

Build & Integration:

• ✅ Local build succeeds
• ✅ Serve test passed
• ✅ No broken links
• ✅ Megadoc integration tested (if applicable)

5.3 Feedback for PR Author

If ready to merge:

✅ **Documentation Review: APPROVED**

Excellent work! Documentation is complete, accurate, and megadoc-compliant.

**Highlights**:

- Comprehensive coverage of new {feature}
- Clear examples with proper annotations
- All compliance requirements met
- Build tested successfully

**Ready to merge** ✅

If changes needed:

📝 **Documentation Review: CHANGES REQUESTED**

Great start! A few items need attention before merge:

**Required Changes**:

1. ❌ docs/reference/api.md missing front matter
2. ❌ Code example in getting-started.md has syntax error
3. ❌ Broken link in how-to/deploy.md

**Suggestions**:

1. ⚠️ Consider adding diagram to architecture.md
2. ⚠️ Example in advanced-usage.md could be clearer

**After Fixes**:

- Update PR
- Re-run validation
- Request re-review

If major issues:

⛔ **Documentation Review: MAJOR ISSUES**

Significant issues prevent merge:

**Critical Issues**:

1. ❌ New API endpoint completely undocumented
2. ❌ Breaking changes lack migration guide
3. ❌ mkdocs.yml has invalid YAML syntax
4. ❌ Build fails due to missing files

**Required Actions**:

1. Document all new features
2. Add migration guide for breaking changes
3. Fix mkdocs.yml syntax
4. Create missing documentation files

**Next Steps**:

- Address critical issues above
- Run megadoc-validator
- Request fresh review

Review Templates

Template 1: Feature Addition Review

## Documentation Review: {Feature Name}

### Code Changes

- Added {feature description}
- Modified {affected components}

### Documentation Coverage

- ✅ How-to guide: docs/how-to/{feature}.md
- ✅ API reference: docs/reference/api.md (updated)
- ✅ Examples: Provided and tested
- ✅ Configuration: Documented in reference

### Compliance

- ✅ Front matter complete
- ✅ Diátaxis categorization correct
- ✅ Style guide followed
- ✅ Build succeeds

### Verdict

**APPROVED** - Ready to merge

Template 2: Bug Fix Review

## Documentation Review: {Bug Fix}

### Code Changes

- Fixed {bug description}
- Affected: {components}

### Documentation Impact

- ✅ Updated troubleshooting guide
- ✅ Corrected inaccurate behavior description
- ✅ No new documentation needed

### Compliance

- ✅ Existing docs still compliant
- ✅ Build succeeds

### Verdict

**APPROVED** - Documentation correctly updated

Template 3: Breaking Change Review

## Documentation Review: {Breaking Change}

### Code Changes

- ⚠️ Breaking change: {description}
- Migration required

### Documentation Requirements

- [ ] ❌ Migration guide needed
- [ ] ❌ Changelog entry required
- [ ] ⚠️ Deprecation warnings needed

### Required Actions

1. Create docs/migration/{version}.md
2. Add entry to CHANGELOG.md
3. Mark old functionality as deprecated

### Verdict

**CHANGES REQUIRED** - Must document migration path

Expected Output

Complete Review Report

# Megadoc Readiness Review

**PR**: #{number} - {title}
**Repository**: {repo-name}
**Reviewer**: {name}
**Date**: {YYYY-MM-DD}
**Status**: ✅ APPROVED | 📝 CHANGES REQUESTED | ⛔ MAJOR ISSUES

---

## Executive Summary

{2-3 sentence summary of review outcome}

## Code-Documentation Alignment

### Code Changes

- {List of code changes requiring documentation}

### Documentation Coverage

- ✅ {Coverage item 1}
- ✅ {Coverage item 2}
- ❌ {Missing coverage item}

## Compliance Review

### Megadoc Standards

- ✅ Stub configuration valid
- ✅ Front matter complete
- ✅ Diátaxis organization followed
- ⚠️ {Warning about style issue}

### Quality Standards

- ✅ Grammar and spelling
- ✅ Technical accuracy
- ✅ Example testing
- ❌ {Quality issue}

## Build & Integration

- ✅ Local build: Success
- ✅ Serve test: Passed
- ✅ Link validation: No broken links
- ✅ Megadoc integration: Success

## Issues Found

### Critical (Must Fix Before Merge)

1. {Critical issue 1}
2. {Critical issue 2}

### Important (Should Fix)

1. {Important issue 1}
2. {Important issue 2}

### Minor (Consider Fixing)

1. {Minor issue 1}
2. {Minor issue 2}

## Recommendations

1. {Recommendation 1}
2. {Recommendation 2}

## Verdict

{APPROVED|CHANGES REQUESTED|MAJOR ISSUES}

{Additional context for decision}

## Next Steps

{What should happen next}

Notes

• Perform review before approving PR
• Focus on accuracy, completeness, and compliance
• Provide actionable feedback
• Test documentation changes locally
• Consider both producer and consumer perspectives