Lean writing
Produce tight, slop-free prose and code the first time, so nothing has
to be cleaned up later.
Core moves
- Lead with the result. Cut preamble ("Certainly!", "Here is…") and
postamble ("Let me know if…").
- State current truth, not the journey. No diary of what changed, what
you tried, or how you got here — the artifact is the freshest take,
not a log.
- Reuse before you create. Search for an existing file, component,
helper, API, test, or doc section before adding another.
- Smallest coherent change. Keep unrelated cleanup out of it.
- Preserve references when editing. Never orphan a link, citation,
anchor, warning, or a comment that documents an invariant or "why".
- Prefer prose and nested sections over tables. Reach for a table only
when the data is genuinely matrix-shaped and stable.
- One command per code block; keep comments outside the fence.
- No coded rule labels (
[R1], Option B) in text a human reads.
Calibrate to the project
Read ./AGENTS.md and ./CLAUDE.md. When they define a slop rubric or
a house voice, that governs — match it.
Comments
Code comments and docstrings answer to
../../references/comment-policy.md: one or two lines, only for what
the code cannot say, rationale in the commit message. To trim comments
that already exist, use /lean:trim-comments.
Deeper catalog
See ../../references/lean-rubric.md for the full
signature list, preservation rules, and the "add a table / file / test"
decision blocks.
While tightening, don't add slop
Replacements must be concrete and shorter than what they replace. Never
narrate your own edits ("I tightened…", "cleaned up…"). Fix the text,
not a description of the fix.
1---2name: lean-writing-23description: Use when commit messages or prose must stay tight: cut filler, padding, preamble, AI fluff, and stories of attempts; lead with current results.4---56# Lean writing78Produce tight, slop-free prose and code the first time, so nothing has9to be cleaned up later.1011## Core moves1213- Lead with the result. Cut preamble ("Certainly!", "Here is…") and14 postamble ("Let me know if…").15- State current truth, not the journey. No diary of what changed, what16 you tried, or how you got here — the artifact is the freshest take,17 not a log.18- Reuse before you create. Search for an existing file, component,19 helper, API, test, or doc section before adding another.20- Smallest coherent change. Keep unrelated cleanup out of it.21- Preserve references when editing. Never orphan a link, citation,22 anchor, warning, or a comment that documents an invariant or "why".23- Prefer prose and nested sections over tables. Reach for a table only24 when the data is genuinely matrix-shaped and stable.25- One command per code block; keep comments outside the fence.26- No coded rule labels (`[R1]`, `Option B`) in text a human reads.2728## Calibrate to the project2930Read `./AGENTS.md` and `./CLAUDE.md`. When they define a slop rubric or31a house voice, that governs — match it.3233## Comments3435Code comments and docstrings answer to36`../../references/comment-policy.md`: one or two lines, only for what37the code cannot say, rationale in the commit message. To trim comments38that already exist, use `/lean:trim-comments`.3940## Deeper catalog4142See `../../references/lean-rubric.md` for the full43signature list, preservation rules, and the "add a table / file / test"44decision blocks.4546## While tightening, don't add slop4748Replacements must be concrete and shorter than what they replace. Never49narrate your own edits ("I tightened…", "cleaned up…"). Fix the text,50not a description of the fix.
tony