| name | docs-codebase |
| description | Technical writing for READMEs, ADRs, API docs, and changelogs. Use when revising or consolidating a repo documentation folder. |
Technical Documentation
Execution-ready patterns for clear, maintainable technical documentation.
Modern best practices (January 2026): docs-as-code, ownership + review cadence, documentation QA gates (links/style/spelling), AI-assisted drafting + review, OpenAPI 3.2.0 where streaming schemas matter, and GEO (Generative Engine Optimization) for AI search.
Quick Reference
Workflow
- Identify the documentation type and audience.
- Find existing patterns in the repo; follow local conventions.
- Start from the closest template in
assets/ and adapt.
- Add ownership + review cadence for critical docs (runbooks, onboarding, API reference).
- Run documentation QA (links, formatting, spelling, examples) before merging.
Docs Folder / LLM-Generated Revamp Mode (Any Repo)
Use this mode when a repo's docs/ folder contains substantial research notes for LLMs and implementation docs generated by LLMs.
- Build an inventory and classify each file by doc type (
Tutorial, How-to, Reference, Explanation).
- Mark lifecycle metadata for non-canonical files:
status: draft | canonical | integrated | superseded
owner: @username
last_verified: 2026-02-24
integrates_into: docs/path/to/canonical-doc.md
delete_by: 2026-03-31
- For each topic/feature, keep exactly one canonical spec/reference and merge all duplicates into it.
- Keep only durable facts/decisions in canonical docs; move exploration detail to short linked evidence notes.
- Keep a compact LLM doc library with root anchors:
AGENTS.md, README.md, and minimal canonical docs under docs/ (instructions, specs, reference-data).
- Delete integrated drafts on schedule; avoid
.archive/ mirrors in docs/ unless retention is mandatory.
Decision Tree
User needs: [Documentation Task]
├─ Repo has a docs folder with many LLM-generated docs? → **Revamp Mode** (inventory → canonicalize → trim)
├─ New project? → **README.md**
├─ Technical decision? → **ADR**
├─ Building API? → **OpenAPI spec** + api-docs-template
├─ New version? → **CHANGELOG.md**
├─ Team collaboration? → **CONTRIBUTING.md**
├─ Documenting code? → **Docstrings** (JSDoc, Python)
└─ Building docs site? → **MkDocs** (Python) or **Docusaurus** (JS)
Cross-Platform AI Documentation
AGENTS.md Standard
Prefer AGENTS.md as the cross-tool source of truth. If a specific tool requires a different filename (example: Claude Code uses CLAUDE.md), keep it aligned via a symlink only when you want identical content across tools.
ln -s AGENTS.md CLAUDE.md
Do / Avoid
Do
- Assign owners and review cadences to critical docs
- Add CI checks for links, style, and staleness
- Prefer small, task-oriented docs over big wiki pages
- Use Keep a Changelog format with semantic versioning
Avoid
- Docs without owners (guaranteed to rot)
- Stale runbooks (dangerous during incidents)
- Copy/paste docs that drift from code
LLM-First Documentation Patterns
When documentation is consumed primarily by AI agents (AGENTS.md, CLAUDE.md, canonical docs for coding assistants), stale docs become a distinct category of bug.
Stale Docs = Agent Bugs
An agent reading stale docs will:
- Attempt to fix problems that are already solved (e.g., "9 open gating gaps" that were all sealed)
- Use wrong model names (e.g., "Claude Haiku" when code uses
gpt-4o)
- Apply wrong limits (e.g., "fully gated" when free tier actually gets 3/week)
- Re-implement features that already exist
Rule: Treat doc updates as part of the feature PR, not as a follow-up task.
Report Integration Lifecycle
Temporary investigation docs (QA reports, research exports, audit findings) must not become permanent false sources of truth.
Every dated report file must carry lifecycle metadata:
---
Status: pending-integration | integrated | superseded
Integrates-into: docs/product/pricing-feature-matrix.md
Owner: @username
Delete-by: 2026-03-15
---
Workflow:
- Create report with
Status: pending-integration
- Extract durable findings into canonical docs
- Mark report
Status: integrated with date
- Delete after
Delete-by date (git history preserves everything)
Living Docs: Audit Tables with Status Columns
Instead of deleting audit findings, add a Status column:
| Gap | Status | Sealed In |
|---|
| Chart aspects visible to free | Sealed | PR #26 |
| Dreams unlimited for free | Sealed | PR #26 |
| Ask Cosmos no rate limit | Open | — |
This preserves the audit trail while showing current state. Agents can quickly scan for Open items.
Two-Pass Consolidation
When consolidating planning docs into canonical docs:
- First pass: Follow the plan — extract content, delete source files, fix cross-references
- Second pass: Audit deleted content against canonical destinations
git show deleted files to recover any unique data missed in planning- Compare code to docs for drift (e.g., feature marked "Planned" but code shows it's implemented)
Even thorough consolidation plans miss unique data that only lived in one source doc.
Canonical Set Rule (No Doc Sprawl)
- One subject/feature should have one canonical doc.
- Derived docs must link to canonical docs instead of restating them.
- If a derived doc is fully integrated, mark it
integrated and remove it by delete_by (default: delete, not archive).
- If two canonical docs overlap, merge and leave a redirect note in the removed file path.
Canonical LLM Library Rule
- Root files are mandatory anchors:
AGENTS.md for agent behavior/instructions and README.md for project navigation.
- The
docs/ folder should expose only a small canonical set for LLM consumption: current instruction sets, current specs, and durable reference data.
- Research logs, exploratory prompts, and intermediate drafts are temporary working files, not library entries.
- Keep discovery breadcrumbs as links from canonical docs; do not duplicate full research dumps.
Anti-Fluff Rewrite Gate
Before merging LLM-generated docs, require:
- explicit audience and decision/use-case for each section
- measurable statements instead of vague claims
- source links + dates for external facts
- removal of duplicated paragraphs and "future ideas" not tied to a tracked decision
Staleness Disclaimers Over Wrong Numbers
For externally-sourced data (competitor pricing, API rate limits, third-party capabilities):
> Prices as of Feb 2026 — verify current pricing at [source].
A staleness disclaimer is safer than a potentially wrong number. Wrong numbers in agent-consumed docs cause incorrect implementation decisions.
Decision Log Collision Prevention
When adding entries to a decision log (e.g., ### D039 — Feature Name):
grep -o '### D[0-9]*' docs/decision-log.md | tail -1
Numbering collisions happen when two decisions are logged in rapid succession without checking.
Backlog Status Sync Pattern (Mandatory)
When implementation status changes (for example backlog milestones completed), sync canonical docs in the same delivery cycle to prevent stale guidance for humans and agents.
Sync Rules
- Update one canonical status source first (feature matrix / roadmap / decision log).
- Propagate only by reference links in secondary docs; avoid duplicate status prose.
- Add concrete completion dates and owner for status changes.
- If temporary reports are integrated, mark lifecycle state (
integrated or superseded) and delete_by.
Release Gate
A feature is not doc-complete until:
- canonical status doc updated,
- dependent docs checked for conflicting claims,
- docs sync checklist completed.
Resources
| Resource | Purpose |
|---|
| references/readme-best-practices.md | README structure, badges |
| references/adr-writing-guide.md | ADR lifecycle, examples |
| references/changelog-best-practices.md | Keep a Changelog format |
| references/api-documentation-standards.md | REST, GraphQL, gRPC docs |
| references/code-commenting-guide.md | Docstrings, inline comments |
| references/contributing-guide-standards.md | CONTRIBUTING.md structure |
| references/docs-as-code-setup.md | MkDocs, Docusaurus, CI/CD |
| references/writing-best-practices.md | Clear communication |
| references/markdown-style-guide.md | Markdown formatting |
| references/documentation-testing.md | Vale, markdownlint, cspell |
| references/ai-documentation-tools.md | Mintlify, DocuWriter, GEO |
| references/production-gotchas-guide.md | Documenting platform issues |
| references/documentation-metrics.md | Doc quality, freshness, coverage scoring |
| references/onboarding-documentation.md | Developer ramp-up guides, Day 1-Week 4 |
| references/runbook-writing-guide.md | Operational runbooks, incident response |
| references/backlog-status-sync-pattern.md | Canonical backlog status sync workflow for multi-doc repos |
Templates
Related Skills
Fact-Checking
- Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.
- Prefer primary sources; report source links and dates for volatile information.
- If web access is unavailable, state the limitation and mark guidance as unverified.
