Literatize — Code Annotation for LLM Context
Add section-level comments to code files that capture intent, rationale, and gotchas — optimized for LLM re-entry across ephemeral sessions.
Not literate programming (Knuth). Documentation embedded in code, following code structure. See references/guide.md for theory and examples.
Steps
- Parse arguments: file path (required),
--dry-run (show diff only), --context <path> (design docs, ADRs)
- Read target file and any
--context files
- Identify logical sections: imports, config, classes, functions, routes, main, etc.
- Generate file header block:
- Purpose (1 line)
- Architecture sketch (1 line — data/control flow)
- Key invariants (1 line)
- For each section, add a comment block (2-6 lines):
- What: what this section does (1 line)
- Why: design rationale (1-2 lines) — only if non-obvious
- Gotchas: pitfalls, key decisions — only if relevant
- Flow: data/control flow — only for routes/pipelines
- Use native comment syntax (
# Python, // JS/TS, -- SQL, etc.)
- Section dividers:
# ── N. Section Name (no trailing padding, adjust prefix to language)
- Write file (or show proposed comments if
--dry-run)
Rules
| Do |
Don't |
| Explain intent and decisions |
Describe what code literally does |
| Assume cold-start reader |
Assume prior context |
| Keep blocks 2-6 lines |
Write essays |
| Reference external docs when they exist |
Duplicate info from variable/function names |
| Preserve ALL existing code |
Reformat, refactor, add docstrings/types |
Comment Style
# ════════════════════════════════════════
# Purpose: [what this file does]
# Architecture: [data/control flow sketch]
# Invariants: [key guarantees]
# ════════════════════════════════════════
# ── N. Section Name
# [What + Why + Gotchas as relevant, 2-6 lines]
Dual Audience
- LLMs (primary): Capture decisions not in code (why X not Y, constraints, framework gotchas). Enable re-entry without external docs.
- Humans (secondary): Section headers as navigation, architecture sketch, gotcha prevention.
1---2name: literatize3description: On-demand code annotator for LLM context preservation. Adds section-level comments capturing intent, rationale, and gotchas. Use when "literatize", "add literate comments", "annotate this file", "add section comments".4---56# Literatize — Code Annotation for LLM Context78Add section-level comments to code files that capture intent, rationale, and gotchas — optimized for LLM re-entry across ephemeral sessions.910Not literate programming (Knuth). Documentation embedded in code, following code structure. See [references/guide.md](references/guide.md) for theory and examples.1112## Steps13141. **Parse arguments**: file path (required), `--dry-run` (show diff only), `--context <path>` (design docs, ADRs)152. **Read target file** and any `--context` files163. **Identify logical sections**: imports, config, classes, functions, routes, main, etc.174. **Generate file header block**:18 - Purpose (1 line)19 - Architecture sketch (1 line — data/control flow)20 - Key invariants (1 line)215. **For each section**, add a comment block (2-6 lines):22 - **What**: what this section does (1 line)23 - **Why**: design rationale (1-2 lines) — only if non-obvious24 - **Gotchas**: pitfalls, key decisions — only if relevant25 - **Flow**: data/control flow — only for routes/pipelines266. **Use native comment syntax** (`#` Python, `//` JS/TS, `--` SQL, etc.)277. **Section dividers**: `# ── N. Section Name` (no trailing padding, adjust prefix to language)288. **Write file** (or show proposed comments if `--dry-run`)2930## Rules3132| Do | Don't |33|----|-------|34| Explain intent and decisions | Describe what code literally does |35| Assume cold-start reader | Assume prior context |36| Keep blocks 2-6 lines | Write essays |37| Reference external docs when they exist | Duplicate info from variable/function names |38| Preserve ALL existing code | Reformat, refactor, add docstrings/types |3940## Comment Style4142```43# ════════════════════════════════════════44# Purpose: [what this file does]45# Architecture: [data/control flow sketch]46# Invariants: [key guarantees]47# ════════════════════════════════════════4849# ── N. Section Name50# [What + Why + Gotchas as relevant, 2-6 lines]51```5253## Dual Audience5455- **LLMs** (primary): Capture decisions not in code (why X not Y, constraints, framework gotchas). Enable re-entry without external docs.56- **Humans** (secondary): Section headers as navigation, architecture sketch, gotcha prevention.
digital-stoic-org