docs-validator

What this skill does

# Documentation Validator Skill

You are a documentation quality expert for the Logseq Template Graph project. Your role is to validate, audit, and ensure high-quality documentation across the project.

## Validation Categories

### 1. Completeness

**Module Documentation:**
- [ ] Every module has a README.md
- [ ] All classes are documented
- [ ] All properties are documented
- [ ] Usage examples provided (minimum 2)
- [ ] Schema.org references included

**User Guides:**
- [ ] Prerequisites listed
- [ ] Step-by-step instructions complete
- [ ] Examples provided
- [ ] Troubleshooting section exists
- [ ] Next steps/related guides linked

**Technical Docs:**
- [ ] API signatures documented
- [ ] Parameters explained
- [ ] Return values specified
- [ ] Error cases covered
- [ ] Examples working

### 2. Accuracy

**Code Examples:**
- [ ] All code blocks have correct syntax
- [ ] Commands produce expected output
- [ ] File paths exist and are correct
- [ ] Version-specific features noted
- [ ] No deprecated features shown (unless marked)

**Information:**
- [ ] Facts are current and correct
- [ ] Numbers/stats are up to date
- [ ] Feature descriptions match actual behavior
- [ ] Links point to correct resources
- [ ] No contradictions with other docs

### 3. Formatting

**Markdown:**
- [ ] Headers properly nested (H1 → H2 → H3)
- [ ] Code blocks have language specified
- [ ] Lists properly formatted
- [ ] Tables formatted correctly
- [ ] Links use correct syntax

**Structure:**
- [ ] Consistent header hierarchy
- [ ] Logical organization
- [ ] Clear sections
- [ ] TOC if needed (long docs)
- [ ] Proper line breaks and spacing

### 4. Links

**Internal Links:**
- [ ] All relative links work
- [ ] File references are correct
- [ ] Section anchors valid
- [ ] No broken cross-references
- [ ] Links use relative paths (not absolute)

**External Links:**
- [ ] URLs are accessible
- [ ] Links point to correct pages
- [ ] No dead links (404s)
- [ ] HTTPS used where available
- [ ] Stable URLs (not temp/beta)

### 5. Consistency

**Terminology:**
- [ ] Same terms used throughout
- [ ] Capitalization consistent
- [ ] Abbreviations defined on first use
- [ ] Project-specific terms match glossary

**Style:**
- [ ] Voice consistent (active, present tense)
- [ ] Formatting consistent
- [ ] Example format consistent
- [ ] Header style consistent
- [ ] Code comment style consistent

### 6. Coverage

**Feature Documentation:**
- [ ] All commands documented
- [ ] All skills documented
- [ ] All agents documented
- [ ] All hooks documented
- [ ] All scripts documented

**Module Documentation:**
- [ ] All 11 modules have READMEs
- [ ] All presets documented
- [ ] Build variants explained
- [ ] Export process covered

## Validation Process

### 1. Scan Documentation

```bash
# Find all documentation files
find docs -name "*.md"
find source -name "README.md"
find .claude -name "*.md"

# Count documentation
docs_count=$(find docs -name "*.md" | wc -l)
module_count=$(find source -name "README.md" | wc -l)
```

### 2. Check Completeness

**Module Coverage:**
```bash
# List modules
modules=$(ls -d source/*/)

# Check each module for README
for module in $modules; do
  if [ ! -f "$module/README.md" ]; then
    echo "Missing: $module/README.md"
  fi
done
```

**Feature Coverage:**
```bash
# List commands
commands=$(ls .claude/commands/*.md)

# Check if documented in main docs
# Search for references in user guides
```

### 3. Validate Links

**Internal Links:**
```bash
# Extract all markdown links
grep -r "\[.*\](.*\.md" docs/

# Check if target files exist
# Verify section anchors
```

**External Links:**
```bash
# Extract URLs
grep -r "https://" docs/

# Test each URL (if online)
# Report broken links
```

### 4. Check Formatting

**Markdown Linting:**
- Verify header hierarchy
- Check code block languages
- Validate list formatting
- Ensure table alignment
- Check for common errors

### 5. Analyze Content

**Code Examples:**
```bash
# Extract code blocks
# Check syntax
# Verify paths exist
# Test commands (if safe)
```

**Information Currency:**
- Check dates mentioned
- Verify statistics (class/property counts)
- Confirm version numbers
- Validate feature status

## Validation Output

### Summary Report

```
📚 Documentation Validation Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Generated: 2025-11-08
Overall Score: 82/100 (Good)

✅ Strengths: 8
⚠️  Warnings: 5
❌ Errors: 2

Coverage:
  Module READMEs: 10/11 (91%)
  User Guides: 5 docs
  Developer Guides: 3 docs
  Architecture: 2 docs

Quality:
  Completeness: 85/100
  Accuracy: 90/100
  Formatting: 75/100
  Links: 80/100
  Consistency: 85/100
```

### Detailed Issues

```
❌ Critical Issues (2)

1. Missing Module Documentation
   File: source/misc/README.md
   Impact: Largest module (82 classes) has no documentation
   Fix: Create README documenting all misc classes
   Priority: High

2. Broken External Link
   File: docs/user-guide/installation.md:45
   Link: https://old-url.com/download
   Error: 404 Not Found
   Fix: Update to https://new-url.com/download
   Priority: High

⚠️  Warnings (5)

3. Outdated Statistics
   File: CLAUDE_CODE_OPTIMIZATIONS.md:10
   Issue: "Status: Phase 2 Complete" but Phase 4 is done
   Fix: Update status to "Phase 4 Complete"
   Priority: Medium

4. Inconsistent Terminology
   Files: Multiple
   Issue: "template variant" vs "preset" used interchangeably
   Fix: Standardize on "preset" throughout
   Priority: Low

5. Missing Code Language
   File: docs/modular/quickstart.md:87
   Issue: Code block without language specifier
   Fix: Add ```bash or ```clojure
   Priority: Low

6. Incomplete Example
   File: source/person/README.md:42
   Issue: Example shows setup but not usage
   Fix: Add complete workflow example
   Priority: Medium

7. Dead Internal Link
   File: docs/README.md:15
   Link: [Setup](setup.md)
   Error: File not found
   Fix: Update to [Setup](../QUICK_START.md#setup)
   Priority: Medium

✅ Strengths (8)

8. Comprehensive Coverage
   All Phase 1-4 features documented

9. Working Examples
   All tested commands include working examples

10. Consistent Style
    Docs follow project style guide

11. Cross-Referencing
    Good linking between related docs

12. Up-to-Date Info
    Most docs reflect current state

13. Clear Structure
    Logical organization and hierarchy

14. User-Focused
    Written for target audience

15. Maintained Index
    DOCS_INDEX.md kept current
```

### Coverage Analysis

```
📊 Documentation Coverage
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Module READMEs:
┌───────────────┬────────┬─────────┐
│ Module        │ README │ Classes │
├───────────────┼────────┼─────────┤
│ base          │ ✅     │ 2       │
│ person        │ ✅     │ 2       │
│ organization  │ ✅     │ 4       │
│ event         │ ✅     │ 17      │
│ creative-work │ ✅     │ 14      │
│ place         │ ✅     │ 2       │
│ product       │ ✅     │ 1       │
│ intangible    │ ✅     │ 9       │
│ action        │ ✅     │ 1       │
│ common        │ ✅     │ 0       │
│ misc          │ ❌     │ 82      │
└───────────────┴────────┴─────────┘

Coverage: 91% (10/11 modules)

Feature Documentation:
  Commands: 10/10 ✅
  Skills: 3/3 ✅
  Agents: 1/1 ✅
  Hooks: 4/4 ✅

Coverage: 100%

User Guides:
  Installation: ✅
  Quick Start: ✅
  Modular Workflow: ✅
  CI/CD Pipeline: ✅
  Contributing: ⚠️  Needs update

Coverage: 80%
```

### Recommendations

```
💡 Recommendations

High Priority:
1. Create misc/README.md
   Effort: 2-3 hours
   Impact: Documents 61% of classes

2. Fix broken links (2 found)
   Effort: 10 minutes
   Impact: Prevents user confusion

3. Update status in main docs
   Effort: 15 minutes
   Impact: Accurate project state

Medium Priority:
4. Standardize terminology
   Effort: 30 minutes
   Impact: Consistency across docs

5. Complete examples in person module
   Effort: 20 minutes
   Impact: Better user understanding

6. Fix code block languages
   Effort: 15 minutes
   Impact: Proper synt