/docs-health

description: Documentation health report - analyzes docs for freshness, coverage, naming violations, duplicates, and provides recommendations.

Documentation Health Report

Analyze your documentation for health issues including freshness, coverage, naming violations, duplicates, and spec-code mismatches.

Usage

# Full health report
/docs:health

# Include archived documents
/docs:health --include-archived

# Output as JSON
/docs:health --format json

# Save report to file
/docs:health --output health-report.md

Your Task

Execute the enterprise documentation analyzer:

import { EnterpriseDocAnalyzer, generateEnterpriseReport } from '../../src/living-docs/enterprise-analyzer.js';
import * as fs from 'fs';
import * as path from 'path';

const projectPath = process.cwd();

// Create analyzer
const analyzer = new EnterpriseDocAnalyzer({
  projectPath,
  includeArchived: false, // Set true to include archived docs
});

// Run analysis
console.log('\nAnalyzing Documentation Health...\n');
const report = await analyzer.analyze();

// Generate markdown report
const markdownReport = generateEnterpriseReport(report);

// Display summary
console.log(`
DOCUMENTATION HEALTH REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Overall Score: ${report.healthScore.overall}% (Grade: ${report.healthScore.grade})

Metrics:
  Freshness: ${report.healthScore.freshness}%
  Coverage:  ${report.healthScore.coverage}%
  Accuracy:  ${report.healthScore.accuracy}%

Categories: ${report.categories.length}
Total Documents: ${report.totalDocuments}

Issues Found:
  Spec-Code Mismatches: ${report.mismatches.length}
  Naming Violations: ${report.namingViolations.length}
  Duplicates: ${report.duplicates.length}
  Discrepancies: ${report.discrepancies.length}

Recommendations: ${report.recommendations.length}
`);

// Show recommendations
if (report.recommendations.length > 0) {
  console.log('RECOMMENDATIONS');
  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
  for (const rec of report.recommendations) {
    console.log(`• ${rec}`);
  }
}

// Optionally save full report
const outputPath = path.join(projectPath, '.specweave/docs/ENTERPRISE-HEALTH.md');
fs.writeFileSync(outputPath, markdownReport);
console.log(`\nFull report saved to: ${outputPath}`);

Health Metrics

Overall Score (0-100%)

Weighted combination of:

• **Freshness** (20%): Documents updated in last 30 days
• **Coverage** (30%): Documents with acceptance criteria
• **Accuracy** (50%): ACs without spec-code mismatches + naming compliance

Grade Scale

| Grade | Score Range | Meaning | |-------|-------------|---------| | A | 90-100% | Excellent documentation health | | B | 80-89% | Good, minor improvements needed | | C | 70-79% | Acceptable, several issues | | D | 60-69% | Below standard, action required | | F | <60% | Critical issues, immediate attention |

Issue Types

Spec-Code Mismatches

| Type | Description | |------|-------------| | `ghost_completion` | AC marked complete but no code evidence found | | `partial_implementation` | Very little code evidence (<10 lines) | | `undocumented_code` | Code exists without corresponding spec | | `spec_drift` | Spec and code have diverged |

Naming Violations

| Type | Severity | Example | |------|----------|---------| | `all_caps` | Warning | `CIRCUIT-BREAKER.md` | | `mixed_case` | Warning | `CircuitBreaker.md` | | `date_suffix` | Info | `feature-2025-11-24.md` | | `no_extension` | Error | `readme` (missing .md) |

Duplicates

| Type | Description | |------|-------------| | `exact` | Identical content | | `near_duplicate` | Very similar content (>90%) | | `same_title` | Same normalized title |

Discrepancies

| Type | Description | |------|-------------| | `broken_link` | Link to non-existent file | | `orphaned_reference` | Reference to deleted increment | | `outdated_version` | Old version numbers (v0.x) | | `conflicting_info` | Contradictory information |

Report Sections

1. Health Score Summary

| Metric | Score | Grade |
|--------|-------|-------|
| Overall | 85% | B |
| Freshness | 72% | - |
| Coverage | 65% | - |
| Accuracy | 92% | - |

2. Documentation Categories

| Category | Documents | Last Updated |
|----------|-----------|--------------|
| Feature Specs | 45 | 12/3/2025 |
| Architecture | 148 | 12/3/2025 |
| ADRs | 147 | 12/3/2025 |

3. Spec-Code Mismatches

| AC ID | Type | Confidence | File |
|-------|------|------------|------|
| AC-US1-01 | ghost_completion | 70% | spec-0045.md |

4. Naming Violations

| File | Type | Severity | Expected |
|------|------|----------|----------|
| CIRCUIT-BREAKER.md | all_caps | Warning | lowercase-kebab.md |

5. Recommendations

Actionable suggestions based on analysis:

• Update stale documentation
• Add acceptance criteria
• Fix naming conventions
• Consolidate duplicates
• Run `/docs:organize` for large folders

Output Example

DOCUMENTATION HEALTH REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Overall Score: 78% (Grade: C)

Metrics:
  Freshness: 65%
  Coverage:  42%
  Accuracy:  89%

Categories: 6
Total Documents: 708

Issues Found:
  Spec-Code Mismatches: 12
  Naming Violations: 8
  Duplicates: 3
  Discrepancies: 15

Recommendations: 5

RECOMMENDATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• Documentation freshness is low. Consider reviewing docs over 30 days old.
• Documentation coverage is limited. Add acceptance criteria to more documents.
• 8 files use ALL CAPS naming. Rename to lowercase-kebab-case.
• 3 sets of duplicate documents detected. Consider consolidating.
• "ADRs" has 147 files. Run /docs:organize to generate themed indexes.

Full report saved to: .specweave/docs/ENTERPRISE-HEALTH.md

Integrations

CI/CD Health Check

# .github/workflows/docs-health.yml
name: Documentation Health

on:
  push:
    paths:
      - '.specweave/docs/**'

jobs:
  he