---
name: org-literate
description: Prose standard for this repository's literate Org configuration documents — first-person narrative voice, scope per setting, paragraph structure, logical rigor, restraint, and banned LLM-sounding English. Use when writing, rewriting, or reviewing prose in *.org files (configuration.org, modules/, overlays/, README).
---

# Prose Standard for Literate Org Documents

Rules for writing and revising prose in this repository's Org documents.
Adapted from k16shikano's japanese-tech-writing standard
(https://gist.github.com/k16shikano/fd287c3133457c4fd8f5601d34aa817d),
translated to English and to the register of a personal configuration narrative.

## Formatting

- Fill-wrap paragraphs at roughly 85 columns, matching the surrounding text.
- Org markup: =code= for commands, option paths, and file names; `~verbatim~`
  for literal values; `[[url][description]]` for links, with proper nouns kept
  as the description.
- Fragments of code, diffs, logs, and config belong in src blocks, not inline
  prose.
- Bold a repo-specific term at its first definition; refer to it in plain text
  afterwards.

## Voice

This configuration is a story told by its owner. The reader is a guest browsing
someone's dotfiles, not a student reading a manual.

- Narrate decisions in the first person: "I pin this to 0.9 because the 1.x
  series broke tangling", not "the package is pinned due to breakage".
- Describe what software does in plain third person: "niri scrolls windows
  horizontally". First person is for choices, history, and opinions.
- Real history is welcome ("after the second time a brew upgrade broke Emacs,
  I moved everything to Nix") — but only if it actually happened.
- Avoid "we": there is only one author here. Avoid tutorial imperatives
  ("install X, then run Y") unless the section genuinely is a procedure.
- Opinions may be blunt. "zsh's completion setup wore me down" is better
  material than a neutral feature comparison.

## Scope per setting

- Most settings need one or two sentences: what it enables and the visible effect.
- Reserve the full problem-and-alternatives account for non-obvious trade-offs:
  architectural choices, package pins, temporary workarounds, forks.
- Prose explains why and why-not-the-alternative; the code block already shows
  what. Never paraphrase the code line by line.
- When a fact can be stated as configuration, state it in the code block even
  if it only repeats a default. An explicit setting is clearer than a sentence
  about the default.

## Paragraphs and argument

- One topic per paragraph. The first sentence tells the reader what the
  paragraph is about.
- Make the logical link to the previous paragraph explicit at the start
  ("So", "In practice", "But that same failure…").
- Argue in one direction: handle objections first, then state the conclusion
  once. Do not conclude, rebut, and re-conclude.
- When rejecting an alternative, give the concrete reason in one sentence — a
  counterfactual often works ("with zsh I would have needed three plugins for
  this").

## Logical rigor

- Every causal claim carries its mechanism. "Enabling A breaks B" is not an
  explanation; say through what.
- Do not promise unconditionally what only holds conditionally. Prefer
  "usually", "as long as", "when X holds" over blanket guarantees.
- Do not flatten hedges into assertions when revising. "This seems to be a
  scheduler issue" stays hedged unless the surrounding text establishes it.
- One name per concept, document-wide. Once a section introduces a term
  (profile, feature, overlay), keep using it; do not fall back to vague words
  like "the tool" or "the AI".
- Distinct things stay distinct: two pins with two different reasons are not
  "the same workaround applied twice".

## Reader load

- In prose, prefer the plain description ("the launcher") over the exact
  identifier when precision isn't needed; the code block carries the exact
  names.
- Skip decorative precision — dates, sizes, version numbers — unless the number
  itself is the point (a 100 MiB request cap that forced a redesign earns its
  place).
- Before adding a second example or scene, say what the first one didn't cover.
- Keep sentences short. A semicolon joining two clauses is a sign the sentence
  should be two sentences. Colons for elaboration and parentheses for asides
  are fine.

## Restraint

- Bold sparingly: one or two per section, at logical pivots only.
- A dry fact is usually enough. Save the storytelling beat — a short punchy
  sentence, an exclamation — for a genuine turning point: a migration, a fork,
  a disaster. At most once per section.
- No rhetorical questions as transitions, no suspense-building
  ("little did I know…") as a habit.

## Banned LLM English

These phrases add a "sounds thorough" veneer without adding content. Delete or
replace on sight; after drafting, re-read against this list.

- **Previews and wrap-ups**: "In this section we will explore…", "It's important
  to note that…", "It's worth noting…", "In summary", "Overall" (when it only
  restates). State the point directly.
- **Empty adjectives**: "crucial", "essential", "key", "robust", "seamless",
  "comprehensive", "powerful", "cutting-edge" — importance claimed, not shown.
- **Empty verbs**: "delve into", "dive deep", "leverage", "utilize", "harness",
  "streamline", "unlock", "empower", "elevate". Use the plain verb: "use", "run".
- **Connective tics**: chains of "Additionally / Moreover / Furthermore";
  "when it comes to"; "in terms of". If two facts share a role, join them in
  one sentence instead of stacking connectives.
- **Formula contrasts**: "not just X, but Y" and "it's not about X — it's about
  Y" as a reflex; rule-of-three lists ("fast, simple, and reliable") where the
  third item adds nothing.
- **Filler glue**: "This ensures that…", "This allows for…" when the sentence
  only restates the previous one. Keep it only when it adds the mechanism.
- **Contentless intensifiers**: "very", "extremely", "incredibly",
  "significantly".
- Em dashes are fine, but not as the default connector — more than one per
  paragraph reads as generated text. Prefer a comma, parentheses, or two
  sentences.

## Headings

A heading names the component or the question the section answers ("Binary
cache", "Why not cachix"). Not a procedure ("Setting it up"), and not a spoiler
that states the conclusion.

## Honesty

- Do not invent history or motives. If the reason for an old setting is
  forgotten, say so: "I no longer remember why this is here, and I'm afraid to
  remove it" is honest and useful.
- Do not describe as tested what wasn't. "Should also work on darwin, though I
  haven't tried" keeps the reader oriented.
- A workaround is a workaround: name the upstream issue and the condition for
  removing it.