documenting-legacy-codebases

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: documenting-legacy-codebases
description: Use when documenting an existing codebase whose documentation is missing, stale, or untrusted - an inherited system, a legacy application, a repo where the docs lie - or when regrounding a documentation tree against the code, or when someone asks what a system actually does. Encodes the survey-first inventory, the writer-side evidence hierarchy, depth-per-surface rules, the refactor test, dead-or-alive proofs, the quirks-and-findings split, the coverage ledger, the parallel campaign, and the docs-tree skeleton. Use whenever documentation must be reconstructed from the code rather than written alongside a change.
---

# Documenting legacy codebases

**REQUIRED BACKGROUND:** the `technical-writing` skill (hard rules, kind classification, truth rules, style).

## Overview

A legacy codebase has one reliable witness: the code at HEAD. Everything else that speaks about it (names, comments, old documents, diagrams, the memory of whoever is left) is testimony. Core principle: **describe how the system works and what to look out for, verified against the code; the code stays the authority on how it is implemented.** The deliverable is a docs tree the next engineer trusts and the next refactor leaves untouched: only changed behavior or a new feature sends anyone back to edit it.

## When to invoke, and not

Invoke when documenting a system that exists and is under-documented: an inherited or acquired codebase, a system whose authors left, a docs tree that no longer matches the code. A "what does this actually do" investigation that must end in documents also qualifies. Do NOT invoke for documenting a change you are making; the core skill and the document-type skills cover documentation-with-change. Not for arguing a rewrite, which is `writing-design-docs`, fed by these documents. And not for fixing what the grounding finds: the code fix sits outside this plugin; noting the oddity does not (see quirks and defects).

## Survey before prose

Do not start writing at the first interesting file. First enumerate the system's surfaces:

- **Entry points and processes**: executables, services, scheduled jobs, queue consumers, request handlers.
- **Commands and endpoints**: everything an operator or client can invoke.
- **Configuration**: every key, flag, and environment variable the code reads.
- **Data**: schemas, tables, migrations, files on disk, external stores.
- **Integrations**: every external system touched, with direction and protocol.
- **Build and deploy**: how the artifact is produced and where it lands.

Each count is a claim, so the count rule in `references/truth.md` in the core skill applies: print the command behind it, run it at HEAD, date it. Commands, counts, and dates land in the coverage ledger, where drift is expected; the documents stay still. Derive the docs tree from the inventory, not from reading order.

## Depth follows the surface

The tree describes the generic system; the code states its own implementation, and prose never re-documents it. Kind decides the depth:

- **Contract surfaces are exhaustive.** What outside parties bind to and cannot read the code for: HTTP endpoints, message payloads, commands, file formats, config keys. These are reference kind, so the core Reference rule applies: every endpoint, every field, every key. `documenting-contracts` carries the template for endpoints, messages, commands, and payloads; config keys follow the core Reference rule in `config-reference.md`.
- **Internals get the gist.** A descriptive document states the mechanism and its consequences ("the store is append-only; reads take the tip of the chain; an update replaces the whole record"). The classes, database keys, mappings, and call chains that implement the mechanism stay in the code.
- **The refactor test.** A finished document sits still while the code is refactored, and changes only when behavior changes or a feature lands. A sentence that a rename would falsify