document— agent skill

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:

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):

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:

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:

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

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]

1. ...

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."