literate-programminglisted
Install: claude install-skill Habitat-Thinking/ai-literacy-superpowers
# Literate Programming
## Overview
Don Knuth's core insight: **code is written for humans to read, and only incidentally for machines to execute.** This skill applies a pragmatic version of that principle — not Knuth's web/tangle toolchain, but the discipline of writing code whose structure and documentation make the reasoning visible to the next reader.
Every file is a piece of writing, not just a collection of declarations.
---
## The Five Rules
### 1. Every file opens with a narrative preamble
The preamble answers three questions:
- **Why does this file exist?** What problem does it solve, and why is it the right place to solve it?
- **What are the key design decisions?** Not a list of functions — the choices that shaped the structure.
- **What does this file deliberately NOT do?** Explicit scope exclusions are as informative as inclusions.
The preamble belongs in the package/module comment block, before any imports. It is prose, not bullet points.
**Before (no preamble):**
```go
package cache
import (
"sync"
"time"
)
type Cache struct { ... }
```
**After (with preamble):**
```go
// Package cache provides a short-lived, in-process store for rendered page
// fragments. Its only job is to reduce redundant template execution on
// repeated requests for the same URL within a single deploy.
//
// We deliberately avoid distributed caching (Redis, Memcached) here. The
// fragments are cheap to recompute, the deploy cadence is high, and the
// operational bu