doc

Doc Skill

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Generate and validate documentation for any project. --mode selects the artifact family — the default mode handles code/API docs and code-maps; --mode=readme generates a gold-standard README; --mode=oss scaffolds and audits the open-source doc pack.

Modes

Mode routing (absorbed skills):

When invoked with --mode=readme or --mode=oss, read the corresponding reference above and follow its workflow verbatim. The default-mode steps below apply only when no mode (or the implied code-docs mode) is selected.

Execution Steps (default mode — code/API docs)

Given /doc [command] [target]:

Step 1: Detect Project Type

# Check for indicators
ls package.json pyproject.toml go.mod Cargo.toml 2>/dev/null

# Check for existing docs
ls -d docs/ doc/ documentation/ 2>/dev/null

Classify as:

• CODING: Has source code, needs API docs
• INFORMATIONAL: Primarily documentation (wiki, knowledge base)
• OPS: Infrastructure, deployment, runbooks

Step 2: Execute Command

discover - Find undocumented features:

# Find public functions without docstrings (Python)
grep -r "^def " --include="*.py" | grep -v '"""' | head -20

# Find exported functions without comments (Go)
grep -r "^func [A-Z]" --include="*.go" | head -20

coverage - Check documentation coverage:

# Count documented vs undocumented
TOTAL=$(grep -r "^def \|^func \|^class " --include="*.py" --include="*.go" | wc -l)
DOCUMENTED=$(grep -r '"""' --include="*.py" | wc -l)
echo "Coverage: $DOCUMENTED / $TOTAL"

gen [feature] - Generate documentation:

1. Read the code for the feature
2. Understand what it does
3. Generate appropriate documentation
4. Write to docs/ directory

all - Update all documentation:

1. Run discover to find gaps
2. Generate docs for each undocumented feature
3. Validate existing docs are current

Step 3: Generate Documentation

When generating docs, include:

For Functions/Methods:

## function_name

**Purpose:** What it does

**Parameters:**
- `param1` (type): Description
- `param2` (type): Description

**Returns:** What it returns

**Example:**

result = function_name(arg1, arg2)

**Notes:** Any important caveats

For Classes:

## ClassName

**Purpose:** What this class represents

**Attributes:**
- `attr1`: Description
- `attr2`: Description

**Methods:**
- `method1()`: What it does
- `method2()`: What it does

**Usage:**

obj = ClassName() obj.method1()

Step 4: Create Code-Map (if requested)

Write to: docs/code-map/

# Code Map: <Project>

## Overview
<High-level architecture>

## Directory Structure

src/ ├── module1/ # Purpose ├── module2/ # Purpose └── utils/ # Shared utilities

## Key Components

### Module 1
- **Purpose:** What it does
- **Entry point:** `main.py`
- **Key files:** `handler.py`, `models.py`

### Module 2
...

## Data Flow
<How data moves through the system>

## Dependencies
<External dependencies and why>

Step 5: Validate Documentation

Check for:

• Out-of-date docs (code changed, docs didn't)
• Missing sections (no examples, no parameters)
• Broken links
• Inconsistent formatting

Step 6: Write Report

Write to: .agents/doc/YYYY-MM-DD-<target>.md

# Documentation Report: <Target>

**Date:** YYYY-MM-DD
**Project Type:** <CODING/INFORMATIONAL/OPS>

## Coverage
- Total documentable items: <count>
- Documented: <count>
- Coverage: <percentage>%

## Generated
- <list of docs generated>

## Gaps Found
- <undocumented item 1>
- <undocumented item 2>

## Validation Issues
- <issue 1>
- <issue 2>

## Next Steps
- [ ] Document remaining gaps
- [ ] Fix validation issues

Step 7: Report to User

Tell the user:

1. Documentation coverage percentage
2. Docs generated/updated
3. Gaps remaining
4. Location of report

Key Rules

• Detect project type first - approach varies
• Generate meaningful docs - not just stubs
• Include examples - always show usage
• Validate existing - docs can go stale
• Write the report - track coverage over time

Commands Summary

Examples

Generating API Documentation

User says: /doc gen authentication

What happens:

1. Agent detects project type by checking for package.json and finding Node.js project
2. Agent searches codebase for authentication-related functions using grep
3. Agent reads authentication module files to understand implementation
4. Agent generates documentation with purpose, parameters, returns, and usage examples
5. Agent writes to docs/api/authentication.md with code samples
6. Agent validates generated docs match actual function signatures

Result: Complete API documentation created for authentication module with working code examples.

Checking Documentation Coverage

User says: /doc coverage

What happens:

1. Agent detects Python project from pyproject.toml
2. Agent counts total functions/classes with grep -r "^def \|^class "
3. Agent counts documented items by searching for docstrings (""")
4. Agent calculates coverage: 45/67 items = 67% coverage
5. Agent writes report to .agents/doc/2026-02-13-coverage.md
6. Agent lists 22 undocumented functions as gaps

Result: Documentation coverage report shows 67% coverage with specific list of 22 functions needing docs.

Troubleshooting

Reference Documents

• references/doc.feature — Executable spec: detect project type, generate type-appropriate docs from the repo, validate existing docs against source (soc-qk4b)
• references/readme.feature — Executable spec (--mode=readme): mode detection, problem-first lead, trust block near install, collapse-don't-delete depth, the council gate, anti-pattern detection (soc-qk4b)
• references/oss-docs.feature — Executable spec (--mode=oss): audit existing/missing OSS docs, scaffold missing without overwrite, project-type-tailored (soc-qk4b)

• references/readme-craft.md — --mode=readme: the 8 gold-standard README patterns, interview, generation structure, council validation, anti-pattern table
• references/oss-pack.md — --mode=oss: audit + scaffold the OSS doc pack (CONTRIBUTING/CHANGELOG/AGENTS.md), project-type templates
• references/oss-documentation-tiers.md — OSS doc tier definitions (core/standard/enhanced)
• references/oss-project-types.md — Per-type OSS scaffolding templates (cli/operator/service/library/helm)
• references/oss-beads-patterns.md — AGENTS.md beads-tracker patterns for OSS projects
• references/generation-templates.md
• references/prose-and-report-workmanship.md
• references/project-types.md
• references/validation-rules.md
• references/de-slopify.md — Remove AI writing artifacts from docs
• references/architecture-report.md — Generate technical architecture documents