Literatize

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](references/guide.md) for theory and examples.

Steps

1. Parse arguments: file path (required), --dry-run (show diff only), --context (design docs, ADRs)
2. Read target file and any --context files
3. Identify logical sections: imports, config, classes, functions, routes, main, etc.
4. Generate file header block:

• Purpose (1 line)
• Architecture sketch (1 line — data/control flow)
• Key invariants (1 line)

1. 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

1. Use native comment syntax (# Python, // JS/TS, -- SQL, etc.)
2. Section dividers: # ── N. Section Name (no trailing padding, adjust prefix to language)
3. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: digital-stoic-org
• Source: digital-stoic-org/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.