documenting-codelisted

# Documenting Code Update only useful documentation. Start from code facts, identify the reader, and make the smallest doc change that helps that reader act correctly. ## Role-gated action Detect capability from tools, not prose: - Write-capable role: edit docs and run validation. - Read-only role: apply nothing; emit proposed edits in the output contract. ## Reader model Choose the reader before writing. Human reader: - Make docs scannable: clear title, short overview, focused sections, examples. - Keep docs short. Link to detail instead of creating long reads. - Use Mermaid diagrams only when they answer a real structure, flow, lifecycle, ownership, or trade-off question. - Match the existing docs style. Do not invent fonts, colors, or custom visual treatment unless the docs system already supports it. Agent reader: - Write terse operational instructions for LLMs. - Prefer headers, bullets, numbered steps, and exact contracts. - Remove generic knowledge, duplicate rules, pretty formatting, diagrams, tables, long rationale, and advice the model already knows. - If the task is to review or score agent instructions, use `reviewing-instructions`. Code reader: - Comments and docstrings explain contracts, constraints, invariants, side effects, error behavior, and non-obvious decisions. - Delete comments that paraphrase code. - Avoid comments in tests unless they explain non-obvious external behavior or why an edge case matters. ## Language references Load