docs-codebase

What this skill does

# 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

| Documentation Type | Template | When to Use |
|-------------------|----------|-------------|
| **Project README** | [readme-template.md](assets/project-management/readme-template.md) | New project, onboarding |
| **Architecture Decision** | [adr-template.md](assets/architecture/adr-template.md) | Technical decisions |
| **API Reference** | [api-docs-template.md](assets/api-reference/api-docs-template.md) | REST/GraphQL APIs |
| **Changelog** | [changelog-template.md](assets/project-management/changelog-template.md) | Version history |
| **Contributing Guide** | [contributing-template.md](assets/project-management/contributing-template.md) | Open source, teams |

## Workflow

1. Identify the documentation type and audience.
2. Find existing patterns in the repo; follow local conventions.
3. Start from the closest template in `assets/` and adapt.
4. Add ownership + review cadence for critical docs (runbooks, onboarding, API reference).
5. 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.

1. Build an inventory and classify each file by doc type (`Tutorial`, `How-to`, `Reference`, `Explanation`).
2. Mark lifecycle metadata for non-canonical files:

```yaml
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
```

3. For each topic/feature, keep exactly one canonical spec/reference and merge all duplicates into it.
4. Keep only durable facts/decisions in canonical docs; move exploration detail to short linked evidence notes.
5. Keep a compact LLM doc library with root anchors: `AGENTS.md`, `README.md`, and minimal canonical docs under `docs/` (`instructions`, `specs`, `reference-data`).
6. Delete integrated drafts on schedule; avoid `.archive/` mirrors in `docs/` unless retention is mandatory.

## Decision Tree

```text
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.

```bash
# If `CLAUDE.md` does not exist and you want identical content:
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:

```yaml
---
Status: pending-integration | integrated | superseded
Integrates-into: docs/product/pricing-feature-matrix.md
Owner: @username
Delete-by: 2026-03-15
---
```

Workflow:
1. Create report with `Status: pending-integration`
2. Extract durable findings into canonical docs
3. Mark report `Status: integrated` with date
4. 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:

1. **First pass:** Follow the plan — extract content, delete source files, fix cross-references
2. **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):

```markdown
> 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`):

```bash
# Always check the latest entry number before adding
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 huma