# Literatize

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

- Skill: `digital-stoic-org/literatize` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add digital-stoic-org/literatize`
- Raw SKILL.md: https://api.skillmd.com/api/skills/digital-stoic-org/literatize/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: digital-stoic-org (https://skillmd.com/u/digital-stoic-org)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/digital-stoic-org/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 <path>` (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)
5. **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
6. **Use native comment syntax** (`#` Python, `//` JS/TS, `--` SQL, etc.)
7. **Section dividers**: `# ── N. Section Name` (no trailing padding, adjust prefix to language)
8. **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.