# Assistant Docs

> Create or update README, API, architecture, changelog, or migration docs. Use for explicit documentation work.

- Skill: `laimis91/assistant-docs` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add laimis91/assistant-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/laimis91/assistant-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: laimis91 (https://skillmd.com/u/laimis91)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/laimis91/assistant-docs

---


# Documentation Generator

## Contracts

| File | Purpose |
|---|---|
| [`contracts/input.yaml`](contracts/input.yaml) | doc_type, scope, source_files[], format, conditional feature-preparation evidence and architecture_decision_pack |
| [`contracts/output.yaml`](contracts/output.yaml) | files_updated[], evidence_sources[], doc_coverage, review_items[], safety_notes[], conditional feature-preparation and Architecture Pack traces |

- `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
- Any existing-system feature-preparation document requires exact admissible evidence-row bindings `{evidence_ref, item_id, claim_or_question}` for every behavior claim and carried Product question. Incomplete or mismatched evidence returns `blocked_incomplete_evidence` with `request_complete_evidence` and no documentation write; a fresh-but-incomplete Pack additionally returns `blocked_incomplete_pack` with `request_complete_pack`.
- Infer `architecture_design_mode` and conditional `architecture_decision_pack_status`. A current Pack requires the compact canonical `architecture_decision_pack` projection; resolve selected design and rationale through its current canonical ref and record them in `documented_decision_refs`. Missing, stale, and out-of-scope Pack states require issue/recovery evidence and an `architecture_decision_pack_trace` outcome. Never reconstruct, infer, or invent a missing or stale Architecture Decision Pack.

Migration note: v4 replaces the v3 `feature_preparation_evidence_refs: string[]` transport with exact `{evidence_ref, item_id, claim_or_question}` bindings in the input and validated output trace. v3 consumers must migrate each carried behavior claim or Product question to its exact canonical evidence row; broad artifact-only refs are rejected and return no-write recovery. v3 adds feature-preparation completeness for ordinary and Pack-backed documentation. v2 consumers must treat `blocked_incomplete_evidence` and `blocked_incomplete_pack` as no-write recovery, and provide admissible feature-preparation evidence refs before documenting behavior claims or carried Product questions. Existing v2 behavior keeps files_updated required/non-empty for ordinary and current-Pack documentation, but permits omission for typed no-write recovery. Pack projections require non-empty boundaries and exact five-concern design-pressure coverage; v1 consumers must adapt before accepting v2.

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.
- When documenting an applicable architecture decision, the document resolves selected design and rationale from the fresh Architecture Decision Pack reference, records their documented decision refs, and preserves facts versus assumptions, semantic type/primitive-boundary rationale, and falsifiable quality verification rather than rewriting generic design claims.
- Pack-backed architecture docs return `architecture_decision_pack_trace`: `documented` carries source Pack/decision/evidence refs; missing, stale, and out-of-scope states record only recovery action and review trace, never invented refs.
- 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 every material question when missing audience, scope, target file, doc type, or architecture claim changes the output and cannot be inferred; group questions by topic with why, risk if guessed, and a safe default where available rather than enforcing a numeric quota.
- 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 | File | When to use |
|---|---|---|
| **API Docs** | `api-docs.md` | Endpoints, services, public interfaces |
| **Architecture** | `architecture.md` | System overview, component relationships, data flow |
| **README** | `readme-gen.md` | Project README from codebase analysis |
| **Changelog** | `changelog.md` | Release notes from git history |
| **Migration Guide** | `migration.md` | Breaking changes, upgrade steps |
| **Code Explainer** | `explainer.md` | Deep explanation of specific code for learning |

## 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
   - For existing-system feature preparation, resolve `feature_preparation_evidence_status` before drafting; incomplete evidence is a no-write recovery even when no Architecture Decision Pack applies.
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
- For architecture decisions: do not claim memory, performance, or extensibility benefit without a workload, budget/explicit unknown, measurement method, and failure condition; point to the verification evidence or mark the claim for review.
- 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 every material, non-discoverable question only when the missing answer changes audience, scope, target artifact, public contract wording, or verification; group them by topic and keep them concise.
- 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.