From d4e8664be22d7079e50536761c30db2c1f8eacad Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Tue, 28 Jul 2026 12:16:51 +0100 Subject: [PATCH] feat(writing-for-agents): add the cache leading word for environment truth Single source of truth now reaches past the document into the environment. package.json scripts, config files, directory layout and --help output are authoritative already, so a doc restating them is a cache of a lookup that earns its load only when the lookup is expensive. Co-authored-By: Claude Opus 5 (1M context) --- .changeset/writing-for-agents-environment-cache.md | 5 +++++ docs/productivity/writing-for-agents.md | 2 +- skills/productivity/writing-for-agents/SKILL.md | 1 + 3 files changed, 7 insertions(+), 1 deletion(-) create mode 100644 .changeset/writing-for-agents-environment-cache.md diff --git a/.changeset/writing-for-agents-environment-cache.md b/.changeset/writing-for-agents-environment-cache.md new file mode 100644 index 0000000..fedfbc9 --- /dev/null +++ b/.changeset/writing-for-agents-environment-cache.md @@ -0,0 +1,5 @@ +--- +"mattpocock-skills": minor +--- + +Extend **`writing-for-agents`**' pruning section with a new leading word: **cache**. Single source of truth now reaches past the document into the environment — `package.json` scripts, config files, directory layout, `--help` output are themselves authoritative, so a doc that restates them is a cache of a lookup, earning its load only when the lookup is expensive. The positive target: cache what the agent cannot find by looking (unwritten conventions, the reason behind a choice, gotchas no config confesses), and leave one-file, one-command lookups to the environment, where they cannot go stale. diff --git a/docs/productivity/writing-for-agents.md b/docs/productivity/writing-for-agents.md index 6135e2d..b338109 100644 --- a/docs/productivity/writing-for-agents.md +++ b/docs/productivity/writing-for-agents.md @@ -35,7 +35,7 @@ Once you're thinking in these two loads, most authoring decisions — split or d - **Information hierarchy** — the ladder from in-file step, to in-file reference, to disclosed reference behind a pointer. **Progressive disclosure** is the move down that ladder so the top stays legible; **co-location** decides what sits beside each piece once placed. - **Completion criteria** — the clarity and demand of each step's done-condition, and the **legwork** it drives; the defence against **premature completion**. - **Leading words** — a compact concept already in the model's pretraining (*tight*, *red*, *tracer bullet*) that the agent thinks with while running the document; hunt restatements a single word can retire. -- **Pruning** — single source of truth, relevance, and the no-op test applied sentence by sentence, against **sediment** and **sprawl**. +- **Pruning** — single source of truth, relevance, and the no-op test applied sentence by sentence, against **sediment** and **sprawl**. Single source of truth reaches past the document into the environment: a doc restating what's already in `package.json`, a config file, or `--help` output is a **cache** of a lookup that was never expensive, and it's the copy that goes stale. Cache what the agent can't find by looking — the unwritten convention, the reason behind a choice. ## Where it fits diff --git a/skills/productivity/writing-for-agents/SKILL.md b/skills/productivity/writing-for-agents/SKILL.md index 97bba89..c059d48 100644 --- a/skills/productivity/writing-for-agents/SKILL.md +++ b/skills/productivity/writing-for-agents/SKILL.md @@ -76,5 +76,6 @@ You win twice: fewer tokens, and a sharper hook for the agent to hang its thinki ## Pruning - Keep each meaning in a **single source of truth**: one authoritative place, so changing the behaviour is a one-place edit. **Duplication** — the same meaning in more than one place — costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank. (The accidental inverse of a leading word, which repeats a token on purpose, never the meaning.) +- The **environment** is a source of truth too — `package.json` scripts, config files, the directory layout, `--help` output — and a document that restates it is a **cache**: a copy of a lookup, earning its load only when the lookup is expensive. Cache what the agent cannot find by looking: the unwritten convention, the reason behind a choice, the gotcha no config confesses. Leave the one-file, one-command lookups to the environment, where they cannot go stale. - Check every line for **relevance**: does it still bear on what the document does? A line loses relevance by never bearing on the task (mere exposition, or a branch that should be disclosed) or by going stale as the behaviour or world it describes changes. Shorter documents are easier to keep relevant. Without a pruning discipline the default fate is **sediment**: stale layers that settle because adding feels safe and removing feels risky, until you must core down through them to find what is still live. - Hunt **no-ops** sentence by sentence: an instruction the model already obeys by default pays load to say nothing. The test — does it change behaviour versus the default? — is model-relative, not reader-relative: two people disagreeing about a no-op disagree about the default, and settle it by running the document, not by debate. When a sentence fails, delete the whole sentence rather than trim words from it. The test also grades leading words: a word too weak to beat the default (_be thorough_ when the agent is already thorough-ish) is a no-op, and the fix is a stronger word (_relentless_), not a different technique.