voice

Chalk Voice — Writing Principles

Interpret MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, etc. per RFC 2119.

Optimise for the reader, not the writer.

Whatever you're writing, the reader is trying to do one of four things, and Diataxis names them:

	Acquire	Apply
Cognition	Explanation	Reference
Action	Tutorial	How-to

Nearly everything in this plugin is explanation, end to end — commit bodies, issue and PR descriptions, chalk comments, code comments. Reference-shaped material inside them (log excerpts, usage examples, commit lists, test plans) is illustration embedded in the explanation, not a section of its own. A docs page is the only artefact that plays all four.

Load alongside this

• chalk:mindmap — always. The shape of followable content: nested bullets, subject lines, tags, cross-reference IDs, tl;dr placement. It applies in every quadrant.

• chalk:goal-tree — where a node's children accomplish it rather than argue for it. The direction of a piece of work, a Future state or Implementation section.

• references/palette.md — before drafting an issue, PR or chalk comment. The section palette, their ordering, and the annotated-trace technique for sequencing bugs.

• references/docs-quadrants.md — before writing a docs page. How-to, reference and tutorial voice; the three quadrants nothing else here needs.

• chalk:code-comments — before writing or editing any comment. The reader model, the counter-intuition test, and where the rejected material goes instead.

Line format

The destination decides it: paragraph-per-line where the artefact is read rendered, sentence-per-line where it's reviewed as a diff.

• Paragraph-per-line — commit bodies, issue and PR descriptions, chalk comments. These are read rendered on GitHub, and GitHub renders a single newline as <br>, so sentence-per-line fragments into staccato. Put each paragraph on one line, separate paragraphs with a blank line, and let the rendering wrap.