Structures code files for readability-first: adds narrative preambles explaining purpose, design decisions, exclusions; docs focus on reasoning over signatures. For new files, functions, types, or rewrites.
npx claudepluginhub habitat-thinking/ai-literacy-superpowers --plugin ai-literacy-superpowersThis skill uses the workspace's default tool permissions.
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.
Creates READMEs, architecture docs, code comments, and API documentation using templates and best practices for beginner-friendly codebases.
Routes documentation tasks to code comments (audit/cleanup) or system docs (READMEs, API docs, architecture). Use for writing, auditing, or improving any docs.
Generates or updates documentation for code, APIs, or systems including READMEs, API references, inline comments, technical guides, and ADRs.
Share bugs, ideas, or general feedback.
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 preamble answers three questions:
The preamble belongs in the package/module comment block, before any imports. It is prose, not bullet points.
Before (no preamble):
package cache
import (
"sync"
"time"
)
type Cache struct { ... }
After (with preamble):
// 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 burden of a networked cache is not justified at current traffic.
// If that changes, this package is the right place to swap the strategy.
//
// We do not attempt cache invalidation on content change — that problem
// belongs to the deployment pipeline, not the request path.
package cache
A comment that restates the function name or its parameter types adds no value. The code already shows WHAT. Documentation's job is to explain WHY — the design choice, the tradeoff, the constraint that shaped this particular approach.
Before (restates the signature):
// getUserByID returns the user with the given ID from the database.
func getUserByID(id string) (*User, error) {
After (explains reasoning):
// getUserByID loads from the read replica, not the primary. For the auth
// hot-path this is acceptable because user records change rarely and a
// replication lag of a few seconds is not observable by a human login flow.
// Write operations that need immediate consistency call the primary directly.
func getUserByID(id string) (*User, error) {
Apply the same standard to type definitions: explain why the type exists and what invariants it maintains, not just what its fields are.
Arrange code so that a reader encounters concepts in the order they need them to build understanding — not in the order the compiler requires. This usually means:
In Go and Kotlin this sometimes means forward references — that is fine. Readability for the human outweighs convention.
Name the file's single concern in the first sentence of the preamble. If you cannot state it in one sentence, the file has too many concerns and should be split.
A file's concern is not its list of contents ("this file contains the parser, the renderer, and the helper functions"). It is its intellectual role ("this file transforms a flat markdown string into a navigable hierarchy of sections").
Inline comments are for explaining decisions, constraints, and non-obvious consequences — not for narrating code that can speak for itself.
| ❌ Describes WHAT | ✅ Explains WHY |
|---|---|
// increment counter | // counter is used by the rate limiter, not just for metrics |
// check if user is nil | // nil user is valid here — unauthenticated requests are allowed |
// loop over items | // process in reverse so removals don't shift the indices we haven't visited |
// return error | // surface the parse error; callers need the line number to show a useful message |
| Rule | Signal that it's missing |
|---|---|
| Narrative preamble | File opens directly with imports or a type declaration |
| Reasoning-based docs | Function comment could be generated from the signature alone |
| Logical order | Helper functions appear before the code that uses them |
| Single stated concern | Preamble lists contents rather than naming the file's role |
| WHY comments | Inline comment restates the next line in different words |
| Rationalization | Reality |
|---|---|
| "The function name is self-explanatory" | Names say WHAT. Documentation explains WHY the design is this way, not another way. |
| "I'll add documentation later" | Documentation written after implementation is biased toward describing what was built. LP documentation shapes what gets built. |
| "The preamble would be too long" | A preamble proportional to the decisions made is never too long. A file with no decisions worth naming should not exist. |
| "This is obvious" | Obvious to you now ≠ obvious to the next reader. Obvious things change; the reason they were obvious does not. |
| "I'll write a docstring" | A docstring that restates the signature satisfies a tool, not a reader. |
| "The code is the documentation" | The code shows the mechanism. LP documentation shows the reasoning. Both are needed. |
import or a type/function declaration, no preamble