# Toolbox writing contract v2

<!-- source-of-truth: public Toolbox writing defaults -->
<!-- doc-meta: owner=eng | last-reviewed=2026-10-15 -->

Lead with the outcome. Preserve facts, uncertainty, technical terms, user stance, code and quoted errors. Use direct natural prose and the smallest useful structure. Use a diagram or table when it makes a relationship easier to understand. Match detail to the decision; avoid mandatory sentence lengths, modal bans and ceremonial sections. Source-backed claims use verified clickable evidence. A writing rule never strengthens an uncertain claim. Private voice/corpus is outside this public contract.

## Plain-speech patterns

Remove these on a final pass. Cite them by ID in reviews ("plain-speech P3"). They target empty words, not style choices; they add no bans on punctuation, modals or sentence length.

| ID  | Pattern                    | Instead                                                                              |
| --- | -------------------------- | ------------------------------------------------------------------------------------ |
| P1  | Filler openers and closers | Start with the answer. Stop when the content stops.                                  |
| P2  | Narrating your own process | Report what was found or changed, not that you are about to look.                    |
| P3  | Inflated vocabulary        | Plain words: "use" not "leverage", "solid" not "robust", "look at" not "delve into". |
| P4  | Undefined metaphor nouns   | Name the actual thing. Shared vocabulary terms such as Slice and Surface are fine.   |
| P5  | Stacked hedges             | One hedge sized to the real uncertainty ("likely", "unverified").                    |
| P6  | Empty significance claims  | Say the concrete consequence instead of "plays a key role" or "worth noting".        |
| P7  | Missing actor or verb      | Say who does what: "the parser rejects X", not "X rejection occurs".                 |
| P8  | Over-compression           | Keep the articles and verbs a reader needs; terse is not the same as clear.          |

## Work reports

A reply that reports work states facts the reader can check:

- **Measured results as numbers.** When the task names a measurable outcome, such as contrast, latency, size, count or the quotes produced, report the value before and after, from a run you show.
- **Changed files from Git.** List the files you changed from `git status` or the diff, not from memory, including added tests.
- **Claims match the output.** Describe what a run showed. Remove a claim the shown output does not support, or mark it unverified.
- **Final runs come last.** A result you report comes from a run after your last edit. If you edited after it, run it again before you claim it.

Adapted from the pstack `unslop` catalogue ([backnotprop/pstack](https://github.com/backnotprop/pstack), MIT © 2026 Lauren Tan).