literate-programming

What this skill does

# Literate Programming Skill

**CRITICAL: This skill MUST be activated BEFORE making any changes to .nw files!**

You are an expert in literate programming using the noweb system.

## Reference Files

This skill includes detailed references in `references/`:

| File | Content | Search patterns |
|------|---------|-----------------|
| `noweb-commands.md` | Tangling, weaving, flags, troubleshooting | `notangle`, `noweave`, `-R`, `-L` |
| `testing-patterns.md` | Test organization, placement, dependency testing | `test functions`, `pytest`, `after implementation` |
| `overview-patterns.md` | Whole-picture overviews, roadmap prose, structural diagrams | `overview`, `diagram`, `tikz`, `roadmap` |
| `git-workflow.md` | Version control, .gitignore, pre-commit | `git`, `commit`, `generated files` |
| `multi-directory-projects.md` | Large project organization, makefiles | `src/`, `doc/`, `tests/`, `MODULES` |
| `project-initialization.md` | New project setup, templates, checklist | `new project`, `initialize`, `pyproject.toml` |
| `preamble.tex` | Standard LaTeX preamble for documentation | `\usepackage`, `memoir` |

## When to Use This Skill

### Correct Workflow

1. User asks to modify a .nw file
2. **YOU ACTIVATE THIS SKILL IMMEDIATELY**
3. You plan the changes with literate programming principles
4. You make the changes following the principles
5. You regenerate code with make/notangle

### Anti-pattern (NEVER do this)

1. User asks to modify a .nw file
2. You directly edit the .nw file  ← WRONG
3. Later review finds literate quality problems
4. You have to redo everything

### Remember

- .nw files are NOT regular source code files
- They combine documentation and code for human readers
- Literate quality is AS IMPORTANT as code correctness
- Bad literate quality = failed task, even if code works

## Planning Changes

When making changes to a .nw file:

1. **Read the existing file** to understand structure and narrative
2. **Plan with literate programming in mind:**
   - What is the "why" behind this change?
   - Why does this approach work, not just why was it chosen?
   - How does this fit into the existing narrative?
   - Does the document need an early whole-picture overview before details?
   - Which overview, intro, roadmap figure, or relevant `README.md`
     summarizes this area, and does this change make it stale?
   - What new chunks are needed? What are their meaningful names?
   - Where in the pedagogical order should this be explained?
3. **Design documentation BEFORE writing code:**
   - Write prose explaining the problem and solution
   - Use subsections to structure complex explanations
   - For substantial `.nw` files, give maintainers the whole before the
     parts. If relationships are hard to hold in prose, add a structural
     figure. See `references/overview-patterns.md`.
4. **Decompose code into well-named chunks:**
   - Each chunk = one coherent concept
   - Names describe purpose, not syntax (like pseudocode)
5. **Write the code chunks**
6. **Regenerate and test**

**Key principle:** If you find yourself writing code comments to explain logic, that explanation belongs in the documentation chunks instead.

## Reviewing Literate Programs

When reviewing, evaluate:

1. **Narrative flow**: Coherent story? Pedagogical order?
2. **Variation theory**: Contrasts used? "Whole, parts, whole" structure?
   Maintainer-facing `.nw` files should orient the reader to the system,
   then drill into parts, then reconnect changes to the whole.
3. **Chunk quality**: Meaningful names? Focused on single concepts?  Bucket
   chunks named with nouns (`<<option completions>>`), not verb phrases
   (`<<wire option completions>>`)?
4. **Explanation quality**: Explains "why" not just "what"?  The
   explanation should also say why the chosen approach works.  Red flags:
    prose that begins "We [verb] the [noun]" matching a function name;
    prose that describes parameter types visible in the signature;
    prose that restates conditionals without explaining why they matter;
    prose that says an approach is better without explaining the mechanism,
    invariant, or constraint that makes it work.
5. **Test organization**: Tests after implementation, not before?
6. **Proper noweb syntax**: `[[code]]` notation in prose? Identifiers in
   chunk titles escaped with `[[...]]`? Valid chunk references?
7. **Overview quality**: For non-trivial files, does the overview identify
   the main parts, how they relate, and where the document will go next?
   Is the level appropriate for a maintainer who knows the language but not
   this codebase?
8. **Visual clarity**: When the structure is distributed, non-linear, or
   hard to track in prose, does the document add a roadmap or diagram?
9. **Overview maintenance**: When structure, flow, chunk organization,
   entry points, or likely edit locations changed, were the overview,
   local intro prose, roadmap figures, and any relevant `README.md` kept in
   sync?
10. **Co-location and consistency**: Are wiring chunks (attribute
   assignments, register/install calls, decorator-style mutation) placed
   next to the entities they mutate, not the helpers they call?  When the
   same task is solved in multiple places in the file, do they share a
   pattern — or does prose explain why a particular site diverges?

## Core Philosophy

Literate programming (Knuth) has two goals:

1. **Explain to human beings what we want a computer to do**
2. **Present concepts in order best for human understanding** (psychological order, not compiler order)

### Variation Theory

Apply `variation-theory` skill when structuring explanations:

- **Contrast**: Show what something IS vs what it is NOT
- **Separation**: Start with whole (module outline), then parts (chunks)
- **Generalization**: Show pattern across different contexts
- **Fusion**: Integrate parts back into coherent whole

When the literate document is student-facing educational LaTeX, keep
pedagogical meta-commentary such as variation/invariance labels and
sequencing rationale out of the visible narrative.  Put that reasoning in
`\ltnote{...}` via the `didactic-notes` skill.

If the `.nw` document generates slides or handouts with live questions, Mentipy
is a suitable tool for embedding those prompts in the LaTeX output.

**CRITICAL**: Show concrete examples FIRST, then state general principles. Readers cannot discern a pattern without first experiencing variation.

## Noweb File Format

### Documentation Chunks

- Begin with `@` followed by space or newline
- Contain explanatory text (LaTeX, Markdown, etc.)
- Copied verbatim by noweave

### Code Chunks

- Begin with `<<chunk name>>=` on a line by itself (column 1)
- End when another chunk begins or at end of file
- Reference other chunks using `<<chunk name>>`
- Multiple chunks with same name are concatenated

### Syntax Rules

- Quote code in documentation using `[[code]]` (escapes LaTeX special chars).
  Never manually escape characters (e.g. `\_`) inside `[[...]]` — noweb
  handles all escaping automatically.  Writing `[[\_]]` double-escapes.
- `[[...]]` works inside `\item[...]` labels (and other moving arguments),
  but separate the inner `]]` from the outer `]` with at least one
  character — typically a space.  The failure mode is **three brackets in
  a row** (`]]]`), where noweb's `]]` terminator and LaTeX's `]` argument
  terminator collide and produce a `Runaway argument? ! Paragraph ended
  before \@item was complete.` error.

  **GOOD** — `]]` is followed by a space or by other text:
  ```latex
  \item[The [[--restart]] flag] explains the idempotence rule.
  \item[ [[shell-basics $]] ] anchors on the nested shell prompt.
  ```

  **BAD** — `[[...]]` butts directly against the closing `]`:
  ```latex
  \item[The required pattern [[shell-basics $]]]   % Runaway argument
  ```

  The same rule applies to any other LaTeX macro argument that is
  delimited with brackets (`\caption[...]`, `\section[...]` short forms,
  et