# Reading Like Prose

> Use when making code a joy to read — a function is hard to follow top to bottom, nesting is deep, the reader has to scroll up to understand, or high-level intent is buried under low-level detail

- Skill: `atgreen/reading-like-prose` (Agent Skill)
- Install (CLI): `npx skillmds@latest add atgreen/reading-like-prose`
- Raw SKILL.md: https://api.skillmd.com/api/skills/atgreen/reading-like-prose/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: atgreen (https://skillmd.com/u/atgreen)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/atgreen/reading-like-prose

---


# Reading-Like-Prose

## Overview

**Core principle:** Code is read far more often than it's written, and mostly by someone with no
context — often you, months later. Structure it for that reader: top-down, one idea at a time, in
the order a person would want to learn it. Good code reads like a well-edited paragraph, not a
puzzle you assemble by jumping around.

## The Three Moves

### 1. One altitude per function

A function should operate at a single level of abstraction. High-level intent and low-level
mechanics in the same body forces the reader to change gears every line.

- The top-level function reads like a **table of contents**: named steps, each a call.
- Details live one level down, each in its own well-named function (see **naming-as-design**).
- If a function mixes "what we're doing" with "how a byte gets shifted," extract the *how*.

### 2. Read top-down, important-first

Order code the way a newspaper orders a story: headline first, details below.

- The thing the reader most wants to know goes **first** — the main path, the answer.
- Supporting detail comes **after**, so the reader never scrolls *up* to understand what they're reading.
- Define-before-use is a compiler's need, not a human's. Where the language allows, order for the human.

### 3. Flatten the happy path

Deep nesting hides the main story inside a staircase of conditions.

- **Return early** on the exceptional cases — guard clauses at the top — so the happy path runs down the left margin, unindented.
- Handle errors and edge cases *and get them out of the way*, rather than wrapping the real work inside them.
- Prefer a flat sequence of steps to a pyramid of `if/else`.

```
# staircase — the real work is buried three levels deep
if user:
    if user.active:
        if user.has_permission:
            do_the_thing()

# prose — exceptions handled and dismissed; the point runs down the margin
if not user:               return denied("no user")
if not user.active:        return denied("inactive")
if not user.has_permission: return denied("forbidden")
do_the_thing()
```

## Quick Reference

| Symptom | Move |
|---|---|
| Reader scrolls up to understand | Reorder important-first |
| Function changes altitude mid-body | Extract the low-level part |
| Three-deep `if` staircase | Guard clauses, return early |
| "What does this whole block do?" | Extract it and name it |
| Detail before the main point | Put the point first |

## Common Mistakes

- **Extracting into badly-named fragments.** Splitting a function into `helper1`/`helper2` moves
  the confusion, it doesn't cure it. Extraction only pays off with names that read (**naming-as-design**).
- **Flattening past clarity.** Ten early returns can be as hard to follow as deep nesting. The goal
  is a readable story, not a metric of zero indentation.
- **Reordering that fights the language.** Some languages need define-before-use. Order for the
  human *within* what the language allows; don't break the build for aesthetics.
- **Turning prose into golf.** Collapsing readable steps into one dense expression is the opposite
  of this skill. Elegance is *low effort to read*, not fewest lines.

## Relationship to Other Skills

This is the **whittler**'s third pass. It depends on **naming-as-design** (extraction is only
worthwhile with good names) and often follows **subtraction-first** (flattening removes structure
outright rather than reorganizing it).