assistant-docs

Documentation Generator

Contracts

• doc_type and scope are required; source_files and format are inferred when absent
• files_updated entries include path, change_type (created/modified), and description
• review_items is non-empty when docs contain inferred, stale, conflicting, or audience-sensitive claims needing confirmation

Covers the developer's documentation weakness by generating accurate, maintainable docs from code.

Core principle: docs should be generated from truth (code), not written from memory.

Goal

Produce documentation that is accurate, maintainable, and traceable to source evidence.

Success Criteria

• Every concrete claim is backed by code, git history, existing docs, or user-provided source material.
• Review-needed items identify inferred or stale claims instead of silently presenting them as fact.
• The selected doc mode, scope, output files, evidence, and remaining gaps are explicit.

Constraints

• Do not invent features, issue numbers, versions, metrics, roadmap status, or examples to make docs sound stronger.
• Ask only when missing audience, scope, target file, or doc type materially changes the output and cannot be inferred from the request or repo.
• If evidence is weak, write generic wording with placeholders or mark the claim for review.
• Prefer local files, repo-native commands, and git history as documentation truth. Do not call external documentation generators, SaaS analyzers, or upload proprietary code without explicit approval.
• Do not include secrets, tokens, private endpoints, customer data, or internal-only details unless the target document is explicitly approved for that audience.

Available Modes

Mode Selection

Input arrives
    │
    ├─ "document the API" / "API docs"      → api-docs.md
    ├─ "architecture doc" / "system design"  → architecture.md
    ├─ "update readme" / "write readme"      → readme-gen.md
    ├─ "changelog" / "release notes"         → changelog.md
    ├─ "migration guide" / "upgrade guide"   → migration.md
    ├─ "explain this" / "doc this code"      → explainer.md
    └─ ambiguous                             → ask user

When the request is clear enough to choose a mode and scope from local context, proceed without ritual questions and record any assumptions in Review needs.

General Protocol

For all modes:

1. Read the code first — never generate docs from assumptions
2. Read existing docs and project instructions — README, docs index, AGENTS/CLAUDE/CONTRIBUTING, changelog, API specs
3. Match existing style — if the project has docs, follow their conventions
4. Verify accuracy — every claim in the doc must be traceable to code, tests, config, git history, or user-provided source
5. Use real examples only — examples must come from actual code/tests or be explicitly labeled as illustrative
6. Mark generated sections — use <!-- generated by assistant-docs --> comments only where the project accepts generated markers
7. Record review needs — list inferred, stale, or audience-sensitive claims instead of burying uncertainty

Output

Return:

• Status - created, updated, reviewed, or no changes needed.
• Files - paths changed with a one-line description for each.
• Evidence - source files, APIs, tests, configs, commits, or examples used as documentation truth.
• Coverage - what the documentation now covers and what remains out of scope.
• Review needs - inferred claims, stale areas, audience-sensitive claims, conflicts, or open questions needing user confirmation.
• Safety notes - any redactions or sensitive/internal details intentionally omitted.

Staleness Detection

When entering a project, check for stale docs:

>> Scanning documentation freshness...
   README.md: last updated 45 days ago, 3 new features since
   API.md: references endpoints that no longer exist
   CHANGELOG.md: missing entries for last 2 releases

Report staleness to user. Offer to update.

Output Quality

• Use the project's existing doc format (markdown, XML docs, etc.)
• For .NET: generate XML doc comments for public APIs when the project uses them
• For APIs: include request/response examples from tests, fixtures, schemas, or clearly labeled illustrative data
• For architecture: include Mermaid diagrams only if the project already accepts Mermaid or the user approves; otherwise use text outlines
• Keep docs concise — verbose docs don't get read
• Prefer links to existing canonical docs over duplicating content

Anti-Patterns

• Don't document obvious code — /// Gets the user on GetUser() adds nothing
• Don't hallucinate features — only document what exists in code
• Don't create docs the project doesn't need — a 50-line script doesn't need architecture docs
• Don't duplicate — if info exists elsewhere, link to it
• Don't leak sensitive context — redact secrets, tokens, private endpoints, and customer data
• Don't treat stale docs as truth — code/config/tests/git/user-provided source outrank old docs

Stop Rules

• Stop and ask one focused question only when the missing answer changes audience, scope, target artifact, public contract wording, or verification.
• Stop and report gaps when required source files, git history, or docs cannot be accessed.
• Do not finalize docs until changed claims have source evidence or are clearly marked for review.