---
name: docs
description: "Documentation health check and maintenance across all ideas. Use for periodic maintenance, finding gaps, and keeping docs accurate."
model: claude-haiku-4-5-20251001
allowed-tools: Read, Edit, Glob, Grep
---

# /docs

Documentation health check, validation, and maintenance.

## Usage

```bash
/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
| Project | Brief | Critique | Specs | Issues | Score |
|---------|-------|----------|-------|--------|-------|
| Coordinatr | ✓ | ✓ | 2 | 3 | 85 |
| YourBench | ✓ | ✗ | 1 | 0 | 60 |

### 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
1. Scan all `ideas/*/` directories
2. Check for required files
3. Count specs, issues, research docs
4. Calculate health score per project

### --validate
1. Parse markdown files for links
2. Verify link targets exist
3. Check for required structure
4. Identify orphaned files

### --stale
1. Get file modification dates via git
2. Flag files older than threshold
3. Categorize by severity

### --sync
1. Read current CLAUDE.md
2. Scan all ideas/*/README.md for status
3. Compare and identify differences
4. Propose updates

## When to Use

- Weekly documentation review
- Before presenting ideas
- After adding/removing ideas
- Finding forgotten projects