docs

name	docs
description	Documentation generation and explanation

docs

Documentation generation, explanation, and accuracy auditing.

Routes

Subcommand	Action
audit	Quick inline accuracy checks (10 checks)
audit-deep	Full DocAuditWorkflow with auto-fix
explain	Explain how code works
generate	Generate documentation
readme	Update README
changelog	Generate changelog
overview	High-level project overview

Usage

/docs                   # Ask what to do
/docs audit             # Verify doc accuracy
/docs explain           # Explain code
/docs generate          # Generate documentation
/docs readme            # Update README
/docs changelog         # Generate changelog

Behavior

audit

Cross-reference documentation claims against the actual codebase. Run all checks below and report a summary table with pass/fail per check and file:line references for any mismatches.

1. Test count

Run:

pytest --collect-only -q 2>/dev/null | tail -1

Compare the collected/passing count against:

• The static badge in README.md (the number in the img.shields.io/badge/tests- URL)
• Any "X+ tests" claims in README body text
• Any test counts in CHANGELOG.md (current release only)

Flag if the README count exceeds the actual count by more than 5%.

2. Workflow count

Count entries under [project.entry-points."attune.workflows"] in pyproject.toml. Compare against any "N built-in" claims in README.md. Flag mismatches.

3. Skill count

Count directories in plugin/skills/ (each directory with a SKILL.md is one skill). Compare against:

• README.md (any "N skills" claims)
• CHANGELOG.md (current release section)
• .claude-plugin/marketplace.json
• plugin/.claude-plugin/marketplace.json

Flag mismatches.

4. MCP tool count

Count @server.tool() decorators or tool registrations in src/attune/mcp/server.py. Compare against any "N tools" or "N MCP tools" claims in README.md and plugin/README.md. Flag mismatches.

5. File line limits

If README.md claims a maximum file size (e.g., "no file exceeds X lines"), verify by running:

find src/attune -name "*.py" -exec wc -l {} + \
  | sort -rn | head -5

Flag any files that exceed the claimed limit.

6. Install extras

Grep README.md and plugin/README.md for attune-ai[ to find all referenced extras. Verify each extra name exists in pyproject.toml under [project.optional-dependencies]. Flag any extras that are referenced in docs but do not exist in pyproject.toml (e.g., [redis] when the actual extra is [memory]).

7. Stale command references

Grep all *.md files for these removed/legacy patterns:

• empathy-memory (removed in v2.6.2)
• empathy workflow (renamed to attune workflow)
• empathy as a CLI prefix (e.g., empathy workflow)

Report file:line for each occurrence. Exclude CHANGELOG entries that document historical changes (those are intentionally referencing old names).

8. Version consistency

Compare the version string across:

• pyproject.toml (version = "X.Y.Z")
• src/attune/__init__.py (__version__)
• CHANGELOG.md (latest ## [X.Y.Z] heading)
• plugin/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json
• plugin/.claude-plugin/marketplace.json

Flag any that do not match.

9. Cross-doc number consistency

Check that the same metric uses the same number everywhere:

• Cost savings percentages (README vs FAQ vs pitch docs)
• Test counts (README badge vs README body vs CHANGELOG)
• Skill counts (README vs CHANGELOG vs marketplace.json)
• Tool counts (README vs plugin README)

Flag any contradictions.

10. Documentation links

For each markdown link in README.md that points to a local file (not a URL), verify the target file exists. Report broken links.

Output format

Present results as:

## Doc Audit Results

| # | Check | Status | Details |
|---|-------|--------|---------|
| 1 | Test count | PASS/FAIL | ... |
| 2 | Workflow count | PASS/FAIL | ... |
...

### Issues Found

- [README.md:76](README.md#L76): claims "14,000+ tests"
  but actual count is 11,016
...

audit-deep

Trigger the DocAuditWorkflow for a full documentation audit with automatic fixes. This is the autonomous pipeline with 4 stages:

1. Audit — Run all 10 doc checks programmatically
2. Plan — For each failing check, generate a fix plan
3. Execute — Apply auto-fixable changes (counts, versions, stale refs)
4. Verify — Re-run checks, confirm score improved, build MkDocs to verify

Show audit results and fix plan for approval before the execute phase.

# Interactive mode (default)
uv run attune workflow run doc-audit

# With --batch flag for fire-and-forget
uv run attune workflow run doc-audit --batch

Use AskUserQuestion before running:

• Auto-fix safe changes? (default: yes)
• Build MkDocs to verify? (default: yes)
• Approve plan before executing?

explain

Use AskUserQuestion to scope:

• Which file, function, or module to explain?
• What level of detail? (overview, deep dive, or architecture)

Then read the code and provide a clear explanation with context.

generate

Use AskUserQuestion to scope:

• What to document? (API, module, function)
• Format? (docstrings, markdown, or both)

Then generate documentation using the codebase.

readme

Read the current README and project structure, then suggest or apply updates based on current state.

changelog

Use git log to generate a changelog:

git log --oneline --since="last tag"

Format as a markdown changelog grouped by type (features, fixes, refactoring).

overview

Use AskUserQuestion to scope:

• Which scope? (full project, specific module, or subsystem)
• What audience? (new contributor, external user, or architecture review)

Then read the project structure and generate a high-level overview covering purpose, key modules, and how they connect.