Principle Contextualize And Write For The Reader

---
name: principle-contextualize-and-write-for-the-reader
description: "Contextualize and write for the reader. Apply when writing anything someone else will read later: a design, a handoff, findings, a report, a verification, a brief, a reply."
license: MIT
metadata:
  source: "this kit's own, first written for Orchestrator (github.com/erickb336/orchestrator), from the owner's direction (2026-10-01): \"I should be able to come in and clearly understand problems decisions etc\""
---

<!-- Generated by scripts/build.mjs from the sources; edit the source, then run npm run build. -->

# Contextualize and write for the reader

Put everything you write in context. The owner reads it later, without having watched you work, and should understand the problem, the decisions and what is left.

**Lead with the point.** Open with what this is and what it concludes or asks for, in one or two sentences.

**Place it in the bigger picture.** Say which goal or part of the vision it serves, what came before it and what comes next.

**State the problem and the decisions.** Say what problem it addresses and why that matters. For each decision, give the choice, the options weighed and the reason.

**Say what is needed.** If someone must decide, name the decision and the options. If nothing is needed, say so.

**Keep evidence close.** Point to the file and line, the check or the screenshot behind each claim, and say what you did not verify.

**Use the reader's words.** Name screens, files and features as a person knows them, not by internal ids.

**Stop** when someone new could act on it from this text alone.