document

name	document
description	Audit your project's documentation health and identify gaps. Scans for README, changelog, API docs, ADRs, runbooks, onboarding guides, and diagrams. Scores coverage against project maturity tier and recommends specific sub-skills to fill missing docs. Use when you need a documentation audit, want to check doc coverage, find missing documentation, or assess documentation quality.
version	2.0.0
category	docs
platforms	["CLAUDE_CODE"]

You are in AUTONOMOUS MODE. Do NOT ask questions. Analyze the project's documentation landscape and produce a comprehensive health report.

INPUT: $ARGUMENTS

If no arguments provided, perform a full documentation audit of the current project. If a specific doc type is mentioned (e.g., "api", "adr", "runbook"), focus the audit on that area and route to the appropriate sub-skill.

============================================================ PHASE 1: AUTO-DETECT PROJECT CONTEXT

Detect the project's tech stack and maturity level:

Step 1.1 -- Tech Stack Detection

Scan for config files to determine the stack:

• package.json, tsconfig.json (Node.js / TypeScript)
• pubspec.yaml (Flutter / Dart)
• Cargo.toml (Rust)
• go.mod (Go)
• pyproject.toml, requirements.txt, setup.py (Python)
• Gemfile (Ruby)
• pom.xml, build.gradle (Java / Kotlin)
• docker-compose.yml, Dockerfile (containerized)
• .github/workflows/ (CI/CD)

Step 1.2 -- Maturity Assessment

Classify the project into a maturity tier:

Tier	Criteria
Greenfield	< 20 commits, no tests, no CI
Active Development	20-200 commits, some tests, basic CI
Mature	200+ commits, test suite, CI/CD, deployments
Production	All of Mature + monitoring, runbooks, on-call

Record the tier -- it determines which docs are expected.

============================================================ PHASE 2: DOCUMENTATION INVENTORY

Scan the project for existing documentation artifacts:

Step 2.1 -- Core Docs

Check for each of these files/directories and record status (present/missing/stale):

Document	Paths to Check
README	README.md, README, readme.md
Changelog	CHANGELOG.md, CHANGES.md, HISTORY.md
Contributing	CONTRIBUTING.md, docs/contributing.md
License	LICENSE, LICENSE.md, COPYING
Code of Conduct	CODE_OF_CONDUCT.md

Step 2.2 -- API Documentation

Check for:

• OpenAPI/Swagger specs: openapi.yaml, openapi.json, swagger.yaml, swagger.json
• docs/api/, api-docs/ directories
• Inline API doc comments (JSDoc @route, Python docstrings with endpoint info)
• GraphQL schema files: schema.graphql, *.graphqls
• Postman collections: *.postman_collection.json

Step 2.3 -- Architecture Docs

Check for:

• docs/adr/, adr/, decisions/ directories
• Architecture diagrams: docs/diagrams/, docs/architecture/
• Mermaid files: *.mmd, *.mermaid
• Draw.io files: *.drawio
• C4 model files

Step 2.4 -- Operations Docs

Check for:

• Runbooks: docs/runbook/, runbook/, playbooks/
• Deployment docs: docs/deployment/, DEPLOYMENT.md
• Incident response: docs/incidents/, INCIDENT.md
• Monitoring: docs/monitoring/, alerts/

Step 2.5 -- Onboarding Docs

Check for:

• CONTRIBUTING.md, docs/onboarding.md, docs/getting-started.md
• .env.example, .env.template (environment setup docs)
• Makefile, scripts/ (developer workflow tooling)
• docs/development.md, DEVELOPMENT.md

============================================================ PHASE 3: GAP ANALYSIS

Score each documentation area based on project maturity tier:

SCORING MATRIX:

Document Type	Greenfield	Active Dev	Mature	Production
README	Required	Required	Required	Required
Changelog	Optional	Recommended	Required	Required
API Docs	Optional	Recommended	Required	Required
ADRs	Optional	Optional	Recommended	Required
Runbook	N/A	Optional	Recommended	Required
Onboarding	Optional	Recommended	Required	Required
Diagrams	Optional	Optional	Recommended	Required
License	Required	Required	Required	Required

For each doc type, assign a status:

• PASS: Document exists and appears current (modified within last 30 days or content matches code)
• STALE: Document exists but may be outdated (last modified 90+ days ago)
• MISSING: Document does not exist but is Required/Recommended for this tier
• N/A: Not expected for this maturity tier

Calculate coverage score: (PASS count / Required+Recommended count) * 100

============================================================ PHASE 4: ROUTE TO SUB-SKILLS

Based on identified gaps, recommend specific sub-skills to run:

Gap	Sub-Skill	Command
Missing/stale README	/readme	Generate comprehensive README
Missing API docs	/api-docs	Auto-generate OpenAPI spec
Missing changelog	/changelog	Generate from git history
Missing ADRs	/adr	Create ADR directory + retrospective ADRs
Missing runbook	/runbook	Generate operations runbook
Missing onboarding	/onboarding	Generate developer onboarding guide
Missing diagrams	/diagram	Generate architecture diagrams

If $ARGUMENTS specifies a particular doc type, execute that sub-skill's work inline rather than just recommending it.

============================================================ PHASE 5: DOCUMENTATION HEALTH REPORT

OUTPUT:

Documentation Health Report

Project Context

• Project: [name from config]
• Tech Stack: [detected stack]
• Maturity Tier: [tier]
• Total Commits: [count]

Coverage Score: [X]%

Documentation Inventory

Document	Status	Path	Last Updated	Notes
README	PASS/STALE/MISSING	path or --	date or --	details
Changelog	...	...	...	...
API Docs	...	...	...	...
ADRs	...	...	...	...
Runbook	...	...	...	...
Onboarding	...	...	...	...
Diagrams	...	...	...	...
License	...	...	...	...

Priority Actions

Ordered list of documentation gaps to address, highest priority first:

1. [MISSING/STALE] [Doc Type] -- [Why it matters for this project] Run: /[sub-skill]
2. ...

Documentation Quality Notes

• [Any observations about existing doc quality, consistency, accuracy]
• [Suggestions for improving existing docs that are present but weak]

============================================================ SELF-HEALING VALIDATION (max 2 iterations)

After producing documentation, validate completeness:

1. Verify all required sections are present and non-empty.
2. Verify internal cross-references and links resolve correctly.
3. Verify no placeholder text remains ("{TODO}", "[TBD]", "...", "etc.").
4. Verify code examples are syntactically valid.

IF VALIDATION FAILS:

• Identify which sections are incomplete or contain placeholders
• Re-generate only the deficient sections
• Repeat up to 2 iterations

============================================================ SELF-EVOLUTION TELEMETRY

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /document — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.

============================================================ DO NOT

• Do NOT create or modify any documentation files in this orchestrator skill. Only audit and report. Sub-skills handle the actual generation.
• Do NOT guess about project features. Only report what you can verify.
• Do NOT count auto-generated files (lock files, build output) as documentation.
• Do NOT recommend docs that are genuinely unnecessary for the project type (e.g., runbooks for a CLI tool with no deployment).

NEXT STEPS:

After reviewing the health report:

• "Run /api-docs to generate OpenAPI documentation for your API."
• "Run /changelog to generate a changelog from git history."
• "Run /adr retrospective to create ADRs from existing codebase decisions."
• "Run /runbook to generate an operations runbook."
• "Run /onboarding to generate a developer onboarding guide."
• "Run /diagram to generate architecture diagrams."