dotfiles: Skill for Claude Code

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.