/docs

Documentation health check, validation, and maintenance.

Usage

/docs --health # Overall health report /docs --validate # Check broken links, missing files /docs --stale # Find documents >30 days old /docs --sync # Sync CLAUDE.md with project state /docs --project coordinatr # Focus on specific project

Flags

Flag Purpose

--health

Comprehensive health report with scores

--validate

Check links, references, required files

--stale

Find outdated documentation

--sync

Update CLAUDE.md with current status

--project

Focus on specific project

Health Report

Documentation Health Report

Overall Score: 72/100

By Project

Recommendations

1. Run /critique on [project]
2. Create project-brief.md for [project]

Validation Report

Validation Report

Broken Links

• ideas/coordinatr/README.md:15 -> ../specs/SPEC-001.md (not found)

Missing Required Files

• ideas/irl-social/project-brief.md

Orphaned Files

• ideas/shared/docs/old-research.md (not referenced)

Structure Issues

• ideas/lorecraft/ missing issues/ directory

Health Scoring

Component Weight

README.md 20%

project-brief.md 25%

critique.md 15%

specs/ 20%

issues/ 10%

Freshness 10%

Execution Flow

--health

• Scan all ideas/*/ directories

• Check for required files

• Count specs, issues, research docs

• Calculate health score per project

--validate

• Parse markdown files for links

• Verify link targets exist

• Check for required structure

• Identify orphaned files

--stale

• Get file modification dates via git

• Flag files older than threshold

• Categorize by severity

--sync

• Read current CLAUDE.md

• Scan all ideas/*/README.md for status

• Compare and identify differences

• Propose updates

When to Use

• Weekly documentation review

• Before presenting ideas

• After adding/removing ideas

• Finding forgotten projects