@jeffober/thatch 0.1.19 → 0.1.20

package/README.md

@@ -2,24 +2,14 @@
 
 [![CI](https://github.com/sysread/thatch/actions/workflows/ci.yml/badge.svg)](https://github.com/sysread/thatch/actions/workflows/ci.yml)
 
-## Synopsis
+Persistent memory and useful dev skills for AI coding agents. Works with
+**OpenCode** (as a plugin), **Claude Code** (as a local MCP server), and
+**Cursor** (as a local MCP server).
 
-Persistent memory and useful dev skills for AI coding agents that requires zero
-manual config.
-
-Works with **OpenCode** (as a plugin), **Claude Code** (as a local `stdio` MCP
-server), and **Cursor** (as a local `stdio` MCP server).
-
-Each session inherits the accumulated knowledge of every session before it —
-project architecture, conventions, gotchas, user preferences — so your agent
-starts with context instead of a blank slate. Stores are per-repo with a shared
-`global` store.
-
-On top of the memory layer, thatch ships a suite of skills for managing
-memories, performing in-depth, structured code reviews, managing the software
-development life cycle, and researching your code base.
-
-No API keys, no cloud services; everything runs on your machine.
+Each session inherits the accumulated knowledge of every session before it:
+project architecture, conventions, gotchas, user preferences. Your agent
+starts with context instead of a blank slate. No API keys, no cloud services;
+everything runs on your machine.
 
 ## Quick start
 
@@ -30,304 +20,86 @@ No API keys, no cloud services; everything runs on your machine.
 { "plugin": ["@jeffober/thatch"] }
 ```
 
-On next start, OpenCode npm-installs thatch (putting the `thatch` CLI on your
-PATH as a side effect) and its tools are available immediately.
-
-Set this environment variable so the extraction nudge can run the fact-extractor
-as a **background** sub-agent instead of blocking your turn:
+On next start, OpenCode npm-installs thatch and its tools are available
+immediately. For background extraction sub-agents:
 
 ```bash
 export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
 ```
 
-Without it, opencode hides the task tool's `background` parameter and every
-extraction nudge runs synchronously. Put it in your shell rc, `mise.toml`
-`[env]`, or `.envrc`.
-
-**Self-hosting** (local development):
-
-```jsonc
-{ "plugin": ["./path/to/thatch/src/index.ts"] }
-```
-
-Or place the repo under `.opencode/plugins/` and OpenCode auto-loads it.
+Then **prime your project memory** with by running `thatch prime` in your project directory.
+This will launch an `opencode` session to build an initial map of the code base and its architecture to seed the memory.
 
-### Claude Code
+### Claude Code and Cursor
 
-**Install thatch globally:**
+Install globally, then run setup in your project:
 
 ```bash
 npm install -g @jeffober/thatch
-```
-
-This puts the `thatch` binary on your PATH. It requires [Bun] to be installed
-(`curl -fsSL https://bun.sh/install | bash` if you don't have it).
-
-**Set up Claude Code in your project:**
-
-```bash
 cd /path/to/your/project
-thatch setup --claude
-```
-
-`setup` does four things:
-1. Writes `.mcp.json` — registers the MCP server (Claude Code spawns `thatch mcp` as a stdio process)
-2. Appends instructions to `CLAUDE.md` — session startup, when to write, what to store
-3. Installs hooks in `.claude/settings.json` — `SessionStart` runs `thatch reminder` (recall nudge + hygiene), `PostToolBatch` feeds the extraction queue, `UserPromptSubmit` peeks the queue and nudges you to save new knowledge
-4. Installs skill files to `~/.claude/skills/` — memory workflow skills (project primer, fact extractor, dedup classifier, session reflection), code review skills (6 review specialists + synthesizer + context + workflow research), walkthrough skills, and writing skills. See [Skills](#skills) below.
-
-Restart Claude Code and thatch's tools are available as `mcp__thatch__*`.
+thatch setup --claude    # or --cursor
 
-**Global setup** (all projects at once, no per-project config):
-
-```bash
-thatch setup --claude --global
+# set up in your global config for all projects
+thatch setup --claude --global  # or --cursor --global
 ```
 
-This writes to `~/.claude/CLAUDE.md` and `~/.claude/settings.json`, then prints
-the `claude mcp add` command to register the MCP server at user scope.
-
-**Local development** (from a thatch repo checkout):
-
-```bash
-cd /path/to/thatch
-bun run bin/thatch setup --claude
-```
-
-When `thatch` is not on PATH, setup uses the absolute path to `bin/thatch` in
-the hooks and MCP config. When it is on PATH (npm global install), setup uses
-the bare `thatch` command so the config survives updates.
+`setup` installs the MCP server config, hooks, instructions, and skills.
+Restart your editor and thatch's tools are available as `mcp__thatch__*`.
+Requires [Bun] on PATH.
 
 ### Other MCP-compatible harnesses
 
-Thatch works as a `stdio` MCP server with any MCP client. Register it in your
-harness's MCP config by pointing to the `thatch` binary:
-
 ```json
 {
   "mcpServers": {
-    "thatch": {
-      "command": "thatch",
-      "args": ["mcp"]
-    }
+    "thatch": { "command": "thatch", "args": ["mcp"] }
   }
 }
 ```
 
-No `setup` step is needed for bare MCP usage; `setup` installs hooks and
-instructions specific to Claude Code and Cursor. For other harnesses, add the
-MCP server config above and include thatch's tools/instructions in your agent's
-system prompt manually (see [docs/dev/mcp-parity.md](docs/dev/mcp-parity.md)
-for the prompt text). [Bun] must be on PATH.
-
-## Tools
-
-| Tool (opencode) | Tool (MCP) | What it does |
-|------------------|------------|-------------|
-| `thatch_memory_remember` | `mcp__thatch__memory_remember` | Save a memory with an embedding for later recall |
-| `thatch_memory_recall` | `mcp__thatch__memory_recall` | Semantic search across project + global stores |
-| `thatch_memory_list` | `mcp__thatch__memory_list` | List labels and metadata in a store |
-| `thatch_memory_show` | `mcp__thatch__memory_show` | Read full content by exact label |
-| `thatch_memory_forget` | `mcp__thatch__memory_forget` | Delete a memory |
-| `thatch_store_list` | `mcp__thatch__store_list` | List all stores |
-| `thatch_find_duplicates` | `mcp__thatch__find_duplicates` | Surface pairs of suspiciously similar memories |
-| `thatch_dedup_mark_checked` | `mcp__thatch__dedup_mark_checked` | Record a reviewed pair so it stops being re-reported |
-| `thatch_extraction_done` | `mcp__thatch__extraction_done` | Acknowledge extraction nudge was dispatched to a sub-agent; drains the buffer |
-| `thatch_prediction_query` | `mcp__thatch__prediction_query` | Query the user decision model for scored predictions matching a context |
-| `thatch_prediction_update` | `mcp__thatch__prediction_update` | Create, reinforce, or weaken a prediction about user preferences |
-| `thatch_prediction_list` | `mcp__thatch__prediction_list` | List all predictions with matchers, confidence, evidence, and provenance |
-| `thatch_prediction_delete` | `mcp__thatch__prediction_delete` | Delete a prediction created in error (cascades to edges and provenance) |
-
-## Prediction engine
-
-Thatch maintains a statistical model of the user's decision-making preferences.
-When the user sends a prompt, the engine embeds it (sharing the embedding
-already computed for memory recall) and searches for **matchers** — context
-patterns that describe situations where the user has expressed preferences.
-Matching matchers fire linked **predictions** (scored by cosine similarity,
-edge weight, and Bayesian confidence), and a nudge is injected alongside the
-recall nudge:
-
-```text
-[thatch] User decision model
-- [0.72 conf, 4 tests] When X: you tend to Y
-- [0.50 conf, 0 tests] When Z: you may prefer W
-```
-
-The nudge is descriptive, not directive. The system prompt instructions tell
-the agent to follow strong predictions, surface uncertainty when confidence is
-thin, and update the model when the user responds. Predictions use a Bayesian
-posterior with a Beta prior (K=5, P0=0.5); signals are `confirm`,
-`disconfirm`, `soft` (weak disconfirm, weight 0.25), and `create`.
-
-The MCP path (Claude Code, Cursor) fires predictions via the same sideband
-socket used for recall nudges. The `flush-predictions` CLI subcommand provides
-standalone prediction-only output for testing.
-
-## Skills
-
-Thatch ships skills that encode operational methodology — practices your
-agent follows to maintain its own memory and review code systematically.
-
-### Memory workflows
-
-| Skill | What it does |
-|-------|-------------|
-| `thatch-project-primer` | Bootstrap a project's memory store by investigating the codebase and writing foundational memories |
-| `thatch-fact-extractor` | Extract durable facts from recent tool interactions and persist them to memory |
-| `thatch-dedup-classifier` | Classify and consolidate similar memories surfaced by `thatch_find_duplicates` |
-| `thatch-session-reflection` | Record what was learned during a session — project facts, user preferences, tool tips |
-
-### Code review
-
-| Skill | What it does |
-|-------|-------------|
-| `thatch-review-pedantic` | Mechanical correctness — spelling, naming, doc accuracy, specs, stale artifacts |
-| `thatch-review-acceptance` | Behavioral and product review — UX coherency, behavioral delta, integration effects |
-| `thatch-review-state-flow` | Data flow and contracts — module boundaries, implicit state machines, error propagation |
-| `thatch-review-no-slop` | AI writing anti-pattern detection — change narration, fourth wall breaks, hedging |
-| `thatch-review-breadcrumbs` | Comment narrative — do comments form a coherent outline of the code's behavior? |
-| `thatch-review-mark-and-sweep` | Mechanical change completeness — whole-repo sweep for stragglers after renames, flag removals, API substitutions |
-| `thatch-review-synthesizer` | Verify specialist findings against actual code, deduplicate, produce severity-grouped report |
-| `thatch-review-context` | Gather project/feature context (PRs, tickets, TODOs, deferred work) before a review |
-| `thatch-workflow-research` | Research code workflows affected by a change or planned change, before reviewing or planning |
-| `thatch-change-walkthrough` | Explain a change as a teaching walkthrough with file:line citations |
-| `thatch-code-walkthrough` | Explain a feature, module, or workflow as a teaching walkthrough; also drafts high-level docs |
-
-### Writing
-
-| Skill | What it does |
-|-------|-------------|
-| `pr-description` | Draft PR descriptions using instructional-design scaffolding with bold/italic emphasis for scanning |
-| `ticket-description` | Draft ticket or issue descriptions (Linear or Jira) with instructional-design scaffolding |
-| `split-overlarge-pr` | Split already-completed work from an overlarge PR into human-reviewable, release-safe PRs |
-
-### opencode-only
-
-| Skill | What it does |
-|-------|-------------|
-| `thatch-code-review` | Multi-agent review coordinator — triage, partition, dispatch specialists in parallel |
-
-The six review specialists run independently and can be used standalone. The
-synthesizer verifies their findings against the actual code — reading each
-cited location to confirm the evidence matches — before producing a final
-report. The coordinator (opencode only) orchestrates the full pipeline by
-dispatching specialist sub-agents in parallel.
-
-## CLI
-
-The `thatch` CLI ships with the package (installed to your npm global bin by
-`npm install -g`). It requires [Bun] on your PATH — the bin script uses
-`#!/usr/bin/env bun` and all internal modules depend on `bun:sqlite`.
-
-```bash
-thatch stores                    List all stores
-thatch list   [store]            List memory labels in a store
-thatch show   <label> [store]    Display a memory by label
-thatch forget <label> [store]    Remove a memory by label
-thatch search <query> [store]    Semantic search (cosine similarity)
-thatch prime                     Prime project memory (runs via opencode, Cursor, or claude)
-thatch mcp                       Start the stdio MCP server (for Claude Code and Cursor)
-thatch reminder [--json]         Print session-start reminder (for hooks)
-thatch hygiene                   Print the hygiene report (standalone)
-thatch buffer-batch              Append Claude Code PostToolBatch output to extraction queue
-thatch buffer-tool               Append Cursor postToolUse output to extraction queue
-thatch flush-tools [--json]      Peek extraction queue; print extraction + recall nudges
-thatch flush-predictions [--json]  Query predictions for the prompt (hook or standalone)
-thatch setup --claude [--cursor] [--global] Install config + instructions + hooks + skills
-```
-
-Stores default to the repo detected from `git remote`. Use `global` for the
-global store. Use `all` with `search` to search project + global together.
+Include thatch's instructions in your agent's system prompt manually; see
+[docs/dev/mcp-parity.md](docs/dev/mcp-parity.md) for the prompt text.
 
-### Priming a new project
+## What's inside
 
-`thatch prime` bootstraps your project's memory store by having the agent
-investigate the codebase and write foundational memories:
+- **Memory tools**: save, search, list, show, and forget memories with
+  semantic search (local embeddings, SQLite, brute-force cosine).
+- **Prediction engine**: a statistical model of user decision-making
+  preferences. When a prompt matches learned contexts, predictions fire
+  alongside the recall nudge.
+- **Skills**: 20 skills for memory workflows, structured multi-specialist
+  code review, change walkthroughs, and writing tasks (PR descriptions,
+  tickets, PR splitting).
 
-```bash
-cd /path/to/your/project
-thatch prime
-```
-
-This detects `opencode`, Cursor, or `claude` on your PATH and runs the
-`thatch-project-primer` skill, which guides the agent to:
-
-1. Recall any existing project memories
-2. Investigate docs, layout, architecture, commands, and conventions
-3. Write focused memories with clear labels
-4. Reconcile contradictions with existing knowledge
-5. Run dedup to check for overlap
-
-After priming, your agent has context about the project's purpose, structure,
-tech stack, development commands, and conventions — reducing the need to
-re-research these topics in future sessions.
-
-## How it works
-
-Thatch auto-detects your repo identity from `git remote get-url origin`
-(e.g., `sysread/thatch`). Memories are embedded with
-[bge-small-en-v1.5][bge] (384-dimensional vectors, ~34 MB model, cached
-locally) and stored in `~/.config/thatch/thatch.db` (SQLite, WAL mode).
-Search is brute-force cosine similarity — fast enough for thousands of entries.
-
-### Memory capture
-
-Thatch doesn't call an LLM to extract facts. Instead, it buffers recent tool
-interactions and nudges the host agent to persist durable knowledge itself,
-using the `thatch-fact-extractor` skill. The agent's own model decides what's
-worth remembering — keeping thatch dependency-free and the agent in control.
-On OpenCode, the plugin hooks `tool.execute.after` and `chat.message` to
-buffer and peek (the buffer persists until the agent writes a memory). On
-Claude Code, `PostToolBatch` and `UserPromptSubmit` hooks drive a file-backed
-queue with the same peek-not-drain semantics. Both paths produce the same
-payload for the fact-extractor skill.
-
-## OpenCode vs Claude Code vs Cursor parity
-
-| Feature | OpenCode (plugin) | Claude Code (MCP + hooks) | Cursor (MCP + hooks) |
-|---------|-------------------|--------------------------|---------------------|
-| Tools | Plugin tool registration | MCP `tools/list` + `tools/call` | MCP `tools/list` + `tools/call` |
-| System prompt | Injected at runtime with repo name | Static CLAUDE.md (repo auto-detected by MCP server) | Static AGENTS.md (repo auto-detected at startup) |
-| Session-start reminder | `session.created` event | `SessionStart` hook → `thatch reminder` | `sessionStart` hook → `thatch reminder --json` |
-| Compaction context | `experimental.session.compacting` hook | **Gap**: no equivalent (CLAUDE.md persists) | **Gap**: no equivalent |
-| Extraction nudge | `tool.execute.after` + `chat.message` | `PostToolBatch` + `UserPromptSubmit` (file-backed queue) | `postToolUse` + `beforeSubmitPrompt` (file-backed queue) |
-| Prediction auto-fire | `chat.message` hook, separate try/catch from recall | `flush-tools` tier 2 (sideband socket) | `flush-tools` tier 2 (sideband socket) |
-| Setup detection at startup | n/a (plugin auto-installs) | `checkSetup` in MCP server: detects missing/broken instructions | Same as Claude Code |
-| Skills | 19 (18 shared + coordinator) | 18 (shared only) | 18 (shared only) |
-| Store detection | `worktree` param from plugin | `CLAUDE_PROJECT_DIR` env var | `CURSOR_PROJECT_DIR` then `CLAUDE_PROJECT_DIR` |
-
-See [docs/dev/mcp-parity.md](docs/dev/mcp-parity.md) for the full analysis.
+See the [user guide](docs/user/README.md) for the full tool list, CLI
+commands, configuration, environment variables, and detailed setup for each
+host.
 
 ## Privacy
 
 Everything is local. The embedding model downloads once from Hugging Face Hub
 and is cached. No data leaves your machine.
 
-## Docs
-
-- [User guide](docs/user/README.md) — setup, tools, configuration
-- [Development](docs/dev/README.md) — architecture, module responsibilities, data flow
-- [MCP parity](docs/dev/mcp-parity.md) — OpenCode plugin vs Claude Code MCP feature comparison
-- [QA & tests](docs/qa/README.md) — test conventions, categories, use case format
-- [Plans](docs/plans/) — numbered design documents capturing decisions
-
 ## Development
 
 ```bash
-bun install        # deps
-bun test           # full suite: zero network, zero external deps
-bun test --watch   # watch mode
+bun install
 mise run check     # typecheck + bun test + markdownlint (the CI gate)
 ```
 
 Tests never reach outside the sandbox: temp-directory SQLite files, mock
-embeddings, no network. `mise run check` is the full quality gate; `mise run
-typecheck` or `mise run lint-md` run those alone.
+embeddings, no network.
+
+## Docs
+
+- [User guide](docs/user/README.md) -- setup, tools, configuration, CLI
+- [Development](docs/dev/README.md) -- architecture, module responsibilities
+- [MCP parity](docs/dev/mcp-parity.md) -- OpenCode plugin vs MCP feature comparison
+- [QA & tests](docs/qa/README.md) -- test conventions, use cases
+- [Design docs](docs/in-progress/) -- in-progress design notes
 
 ## License
 
 MIT
 
 [Bun]: https://bun.sh
-[bge]: https://huggingface.co/BAAI/bge-small-en-v1.5

package/artifacts/skills/pr-description.md

@@ -1,25 +1,35 @@
 ---
 name: pr-description
-description: Draft a PR description using instructional-design scaffolding (SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES) with bold and italic emphasis on the phrases that carry the meaning, so a reviewer skimming only the emphasized fragments still gets the story. Use when the user asks you to write, draft, or update a PR description or PR body, or when running `gh pr create` and no body has been supplied. Do NOT use for commit messages, release notes, or changelog entries.
+description: Draft a PR description (SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES) with bold and italic emphasis on the phrases that carry the meaning, so a reviewer skimming only the emphasized fragments still gets the story. Use when the user asks you to write, draft, or update a PR description or PR body, or when running `gh pr create` and no body has been supplied. Do NOT use for commit messages, release notes, or changelog entries.
 ---
 
 # Writing PR descriptions
 
+## Core principle
+
+Write for humans. Not for LLMs. Not to impress. Not to pad.
+
+Every sentence earns its place or gets cut. Plain English over jargon. Concrete over abstract. Short over long. A description a human reads and understands beats one that looks thorough but says nothing.
+
+If a word does not help a human understand the diff, it is dead weight. If a sentence restates the previous one, one is redundant. If a phrase sounds smart but you cannot explain it in simpler words, it is a buzzword. Cut, replace, or simplify.
+
+Target a 7th-grade reading level. Not because the reader is dumb, but because plain prose is faster to read and harder to misread. Short sentences, common words, one idea each. The concepts stay technical; the language stays simple.
+
 ## The reader
 
 You are writing for a senior engineer who knows the tech stack and general engineering vocabulary but has never touched this feature, subsystem, or branch. They may not know subsystem-specific jargon or acronyms: a crypto term like DEK, an auth term like the SAML assertion, a scanning term like a ScanRun, a results term like the frozen materialized view. Their goal is to review the diff. Your goal is to raise their baseline understanding just enough that the diff becomes self-explanatory, without making them check out the branch or open a design doc.
 
-The description is not a design doc, changelog, or implementation journal. It is a scaffold that front-loads the context the reviewer needs, didactically layered so they absorb it in the order that makes the diff land.
+The description is not a design doc, changelog, or implementation journal. It is a short, structured brief that gives the reviewer the context they need, in the order that makes the diff make sense.
 
-This is **instructional design**, not documentation. Each section has a cognitive goal for the reader:
+Each section has one job:
 - SYNOPSIS: orient to the class of change and affected area.
 - PURPOSE: make the reader agree there is a problem worth solving.
 - DESCRIPTION: teach the system's current behavior and how this change alters it.
-- WALK-THROUGH (when needed): walk the reviewer through the changed workflow step by step.
+- WALK-THROUGH (when needed): walk the reviewer through the new workflow step by step.
 - NOTES: flag scope limits, intentional regressions, and things AI reviewers will misread.
 - robots.txt (when needed): dense, machine-addressed context that heads off recurring false positives from automated reviewers.
 
-Layer the knowledge so each section builds on the previous one. The reader should never encounter a concept in layer N that was not introduced in layer N-1.
+Each section builds on the previous one. The reader should never encounter a concept in section N that was not introduced in section N-1.
 
 AI-authored PRs tend to be large. The description is the reader's lever against that: a good one lets them say "small description, easy to scan" and then read the code critically. A bad one makes them skip the description, wade through the diff cold, and miss intent.
 
@@ -29,13 +39,13 @@ Sections, in order: SYNOPSIS, PURPOSE, DESCRIPTION, WALK-THROUGH (conditional),
 
 **SYNOPSIS, PURPOSE, and DESCRIPTION are mandatory** - even for a one-line, single-concern change. A tiny PR gets short sections, not fewer sections. WALK-THROUGH and NOTES appear only when warranted; omit them when empty. robots.txt appears only after an automated reviewer has produced a false positive worth heading off (see its section); it is always the final section.
 
-**Scale the body to the diff's conceptual size**, not its structure's capacity. A 2-file, single-concern change (add a flag, guard a branch, rename a symbol, bump a constant) is a few lines per section. SYNOPSIS one line, PURPOSE one to three, DESCRIPTION one short paragraph, NOTES if needed. The layered DESCRIPTION machinery below is for changes with real before/after mechanics to teach; when the diff is self-evident once you know the intent, collapse it. If your draft for a small change runs past ~15 lines of body, you are padding. Cut until each remaining line earns its place. Most of this skill's apparatus exists to tame large PRs; applying it wholesale to a small one produces exactly the bloat the skill warns against.
+**Scale the body to the diff's conceptual size**, not its structure's capacity. A 2-file, single-concern change (add a flag, guard a branch, rename a symbol, bump a constant) is a few lines per section. SYNOPSIS one line, PURPOSE one to three, DESCRIPTION one short paragraph, NOTES if needed. The layered DESCRIPTION machinery below is for changes with real before/after mechanics to teach; when the diff is self-evident once you know the intent, collapse it. If your draft for a small change runs past ~15 lines of body, you are padding. Cut until each remaining line earns its place. Most of this skill's guidance exists to tame large PRs; applying it wholesale to a small one produces exactly the bloat the skill warns against.
 
 ### SYNOPSIS
 
 One to two lines. Orient only. The reader should come away knowing the class of change (bugfix, refactor, feature, revert, infra, cleanup) and the affected area.
 
-SYNOPSIS may use subsystem-specific terms as scan anchors (that is its job). It does not define them. The first teaching section (PURPOSE or DESCRIPTION) picks up that burden. An outsider who does not know the terms should still be able to orient from the plain-English nouns around them.
+SYNOPSIS may use subsystem-specific terms as scan anchors (that is its job). It does not define them. The first teaching section (PURPOSE or DESCRIPTION) picks up that burden. An outsider who does not know the terms should still be able to orient from the plain-English nouns around them. Do not force all project context into SYNOPSIS; it is a TLDR, not the teaching section.
 
 Include a ticket link if one exists. Format: `Ticket: [PLAT-139](https://<host>/browse/PLAT-139)` on its own line directly under the SYNOPSIS text.
 
@@ -77,9 +87,9 @@ How much structure DESCRIPTION needs depends on the change's conceptual size.
 2. **What this PR changes.** For each decision point named in layer 1, say what it does now. Keep parallelism: same names, same order. The reader's mental model from layer 1 is the load-bearing structure here.
 3. **Why that fixes PURPOSE.** One or two sentences linking the mechanics in layer 2 to the harm named in PURPOSE. If the fix has limits (doesn't cover case Z, follow-up needed), call them out here in one line.
 
-The didactic spine: PURPOSE names a harm, layer 1 names the mechanism, layer 2 changes the mechanism, layer 3 shows the harm is gone. Names carry through. The reader builds one model, not four.
+The structure is simple: PURPOSE names a harm, layer 1 names the mechanism, layer 2 changes the mechanism, layer 3 shows the harm is gone. Names carry through. The reader builds one model, not four.
 
-**Large change with a workflow or lifecycle**: keep DESCRIPTION to root-cause and design concept only (what is wrong, what is the approach). Use a separate WALK-THROUGH section for the step-by-step mechanics.
+**Large change with a workflow or lifecycle**: keep DESCRIPTION to root-cause and design concept only (what is wrong, what is the approach). Use a separate WALK-THROUGH section for the step-by-step mechanics of the new flow.
 
 Organize by **workflow or data-flow**, not by touched symbol. A bullet list of API changes reads as disconnected touchpoints. A walkthrough following one object through the system reads as a story. If the change touches a request lifecycle, follow the request. If it touches a data pipeline, follow the data.
 
@@ -87,22 +97,44 @@ Organize by **workflow or data-flow**, not by touched symbol. A bullet list of A
 
 When the change has a sequence of steps - a lifecycle, a workflow, a data flow through the system - split the mechanics into a numbered WALK-THROUGH. Keep DESCRIPTION to root-cause + design concept only.
 
-Default to a numbered outline. A flat list of steps, with an occasional inline branch ("if the path is not in the registry, return a 404; otherwise continue to step 6"), covers almost every workflow. The bar for a diagram or Mermaid chart is high: reach for one only when the flow genuinely needs two dimensions to read - a graph network with many nodes and edges, or a workflow that recurses, forks, and rejoins in ways a linear outline cannot follow without constant back-references. If the flow is one or two levels deep and does not recurse or redirect, an outline is clearer and cheaper to maintain than a diagram.
+Each numbered step describes the **existing behavior** at that stage of the workflow - what the reviewer already knows or can see in the current code. A sub-bullet below it describes what this PR changes, prefixed with **NOW**. For stages that are entirely new (no existing behavior to describe), use `N/A` as the numbered step.
 
-Each numbered step states what changed at that stage of the workflow. Bold the **key phrase** that identifies the step (the scan anchor). The rest of the step is plain prose.
+This before/now pattern lets the reviewer anchor on what they already understand, then see the delta right below it. They never have to reconstruct the current state from inversions.
+
+If the PR changes more than one workflow, split WALK-THROUGH into one subheading per workflow. Do not force unrelated processes into one numbered list. Each workflow gets its own 3-6 step before/now list. Keep subheads concrete: `### Request validation`, `### Background retry`, `### Finalization`, not `### Backend changes`.
 
 Format:
 
-1. **Request enters the handler** - the new guard checks the tenant scope before dispatching.
-2. **Validation runs** - the validator now rejects empty payloads that previously passed through.
-3. **Database write** - the write happens inside the transaction boundary, not after it.
+```md
+### Workflow name
+
+1. **Existing behavior at this stage** - one sentence describing how the code works today.
+   - **NOW** - _what this PR changes about this stage._
+
+2. **N/A**
+   - **NOW** - _a new stage that did not exist before._
+```
+
+Default to a numbered outline. A flat list of steps, with an occasional inline branch ("if the path is not in the registry, return a 404; otherwise continue to step 6"), covers almost every workflow. The bar for a diagram or Mermaid chart is high: reach for one only when the flow genuinely needs two dimensions to read - a graph network with many nodes and edges, or a workflow that recurses, forks, and rejoins in ways a linear outline cannot follow without constant back-references. If the flow is one or two levels deep and does not recurse or redirect, an outline is clearer and cheaper to maintain than a diagram.
+
+Bold the **key phrase** that identifies each step (the scan anchor). The rest is plain prose. Italicize the NOW sub-bullet content so it visually separates from the numbered step above it.
 
 Rules:
+- Aim for 3-6 steps. If you have more, you are over-decomposing. Group related stages into one step. A step is a phase the reviewer can hold in their head, not a single function call.
+- The numbered step is one sentence describing existing behavior. The NOW sub-bullet is one sentence describing the change. If either needs two sentences, the step is doing too much; split the concept differently or move detail to DESCRIPTION.
 - One step per workflow stage, in execution order.
-- State what changed, not what you did. "The handler now checks tenant scope" not "I added a tenant scope check."
+- No blank line between the numbered step and its NOW sub-bullet. GitHub treats a blank line as a list break, so the sub-bullet renders as a separate paragraph instead of a child of the step. Indent the sub-bullet to align under the text of the numbered item (3 spaces after `1.`), and keep them tight:
+
+  ```markdown
+  1. **Step** - existing behavior.
+     - **NOW** - _what changed._
+
+  2. **Next step** - existing behavior.
+  ```
+
 - Cut parenthetical API-symbol asides. The diff carries symbol detail.
 - Cut rationale asides from steps. If the why matters, it goes in DESCRIPTION layer 3 or NOTES.
-- Italics for orientation asides: _This is where the deadlock lived._
+- If a stage is unchanged by this PR, omit it from the walkthrough. Only include stages where the NOW sub-bullet has something to say, or where the existing behavior is needed to understand a later change.
 
 ### NOTES
 
@@ -147,7 +179,7 @@ Human reader: this section is written for automated reviewers, not people. It wi
 
 After the human-warning line, human-legibility rules are suspended. Write for LLM consumption in whatever is densest: no prose scaffolding, no bold, no one-idea-per-sentence, no plain-ASCII constraint. Fragments, symbol soup, and abbreviations are all fine. The only goal is maximum context per token for a machine reader.
 
-What goes here is *explanation and intent*, never suppression. Do not write "ignore the finding about X." Write what X actually does, the invariant it upholds, and the upstream or downstream fact the bot missed, so the bot can re-evaluate and clear its own false positive. A blanket "skip checking X" is a rubber-stamp lever and a prompt-injection surface; refuting a specific misread with a verifiable fact is not.
+What goes here is _explanation and intent_, never suppression. Do not write "ignore the finding about X." Write what X actually does, the invariant it upholds, and the upstream or downstream fact the bot missed, so the bot can re-evaluate and clear its own false positive. A blanket "skip checking X" is a rubber-stamp lever and a prompt-injection surface; refuting a specific misread with a verifiable fact is not.
 
 Entries accumulate. Each review round that surfaces a new false positive adds an entry, so the section grows into a standing set of clarifications that pre-empt the same misreads on the next round.
 
@@ -157,7 +189,7 @@ Omit the whole section unless there is at least one real false positive to addre
 
 ## Emphasis for scanning: bold and italics
 
-Bold and italicize the "save points" - the phrases that carry meaning - not whole sentences. A reader who skims *only* the bold and italic fragments should get the story; full prose is for when they want detail.
+Bold and italicize the "save points" - the phrases that carry meaning - not whole sentences. A reader who skims _only_ the bold and italic fragments should get the story; full prose is for when they want detail.
 
 **What to bold:** phrases that name the **change itself** - the component, the failure mode, the mechanism, the behavior after the change. These are the nouns and verbs that would appear in a diff of the design, not a diff of the code. "There is a **circular wait** in the **KeyManager**" names the failure mode and the component. "**store the result in the in-memory cache**" names the action and the destination.
 
@@ -193,18 +225,26 @@ These are hard rules, not suggestions.
 5. **No authoring-sequence narration.** Never describe the order you assembled things in, which commit does what, or what a later commit will add. Describe the PR as it stands. Pending work goes in a `Remaining work:` bullet list under NOTES.
 6. **Italics for orientation asides.** Use `_italics_` for a one-phrase aside that orients the reader: _This is where the deadlock lived_. Not for emphasis.
 7. **Plain ASCII only.** No smart quotes, smart apostrophes, em dashes, en dashes, ellipsis glyphs, or arrow glyphs. Use plain hyphens (sparingly) for asides; semicolons are often better.
-8. **No buzzwordy abstractions.** If a phrase sounds like it is trying to sound smart, cut or replace it. Name the code and behavior directly. "identity contract" -> "the struct field that identifies the owner". "canonical hash" -> "the SHA-256 we compute on ingestion".
-9. **Avoid loaded language.** Use neutral, current terminology unless the repo's established name is different. Prefer allowlist/blocklist over whitelist/blacklist, primary/replica over master/slave, and precise role names over moralized labels like "bad" or "evil".
-10. **No parenthetical API-symbol asides in WALK-THROUGH steps.** The diff carries symbol detail. If the reader needs the function name, they will find it in the diff.
+8. **No buzzwordy abstractions.** If a phrase sounds like it is trying to sound smart, cut or replace it. Name the code and behavior directly. "identity contract" -> "the struct field that identifies the owner". "canonical hash" -> "the SHA-256 we compute on ingestion". "shared seam" -> "shared helper" or "boundary" depending on what is meant. "leverage" -> "use". "utilize" -> "use". "facilitate" -> "help". If you cannot say what a phrase means in plain English, it does not belong. Buzzwords are the number-one signal that an AI wrote the description; do not send that signal.
+9. **Translate project-private labels.** If a phrase only makes sense to people already working on this project, replace it or explain it before using the label. This includes roadmap names, subsystem nicknames, architecture slogans, ticket shorthand, internal stack names, and labels invented by the current branch. Name the behavior first: what reads, writes, blocks, retries, ignores, repairs, or changes. The reader should understand the sentence before they learn the nickname.
+10. **Prefer concrete terms over ambiguous ones.** If a word can mean more than one thing in this PR, qualify it or replace it with the concrete behavior. Do not rely on the reader guessing the local meaning. Ordinary words can be ambiguous when the code gives them a special role: claim, owner, active, current, generation, repair, coalesce, terminal, source, scope, sync, publish, resolve. "Publish the value" is vague. "Persist the value in the database so the UI can display it" is concrete.
+11. **Clarity wins over compression.** Brevity means fewer claims, not denser claims. If a sentence needs hidden facts to make sense, split it. Keep the connective tissue that makes the idea parse on first read; cut a less important claim instead. Do not compress a missing explanation into a noun stack.
+12. **Explain operations before naming them.** Process words like refresh, repair, coalesce, project, projection, reconcile, classify, normalize, aggregate, route, resolve, hydrate, and fan out are not explanations by themselves. Name the object, the action, and the effect. "The cache refreshes in the background" is vague. "The worker waits up to 5 seconds, then reloads each stale cache key once" is clear. "Projection" is vague unless the sentence says what input is read and what output is computed or stored.
+13. **Do not inherit code wording blindly.** Code comments, function names, metrics labels, and existing PR text often use shorthand for people already in the area. Treat that wording as a clue, not prose to copy. If the code says "coalesce", the description may need "waits up to 5 seconds, then runs once for all requests seen during that window". Prefer the clearest reader-facing behavior over the code's nickname.
+14. **Name both sides of a contrast.** If the PR changes timing, ownership, source of truth, error handling, or ordering, state the old behavior and the new behavior close together. "Retries are synchronous now" is not enough. "The handler used to return before retrying failed webhook deliveries. It now retries once before returning, so callers see the final delivery result" gives the reader a reference point.
+15. **Show causal links.** If a sentence uses "so", "because", "therefore", "prevents", or "allows", make the middle step visible. "The importer uses stable IDs, so duplicate rows do not inflate counts" hides the mechanism. "Some rows arrive with both a display name and a stable ID. The importer counts the stable ID first and ignores the duplicate display-name row, so one item stays one count" explains the cause.
+16. **Avoid loaded language.** Use neutral, current terminology unless the repo's established name is different. Prefer allowlist/blocklist over whitelist/blacklist, primary/replica over master/slave, and precise role names over moralized labels like "bad" or "evil".
+17. **No parenthetical API-symbol asides in WALK-THROUGH steps.** The diff carries symbol detail. If the reader needs the function name, they will find it in the diff.
 
 ## Length and style
 
-Target: the reader can take in the whole description in under 60 seconds. Err on the shorter side.
+Target for most PRs: the reader can take in the whole description in under 60 seconds. Err on the shorter side.
 
 Scale the body to the diff's conceptual size:
 - Trivial 2-file change: ~15-line ceiling. SYNOPSIS one line, PURPOSE one to three, DESCRIPTION one short paragraph, NOTES if needed.
 - Moderate refactor: one tight paragraph or bullet set per section.
-- Large change with WALK-THROUGH: as long as the walkthrough needs, but no longer. Each step earns its place.
+- Large change with WALK-THROUGH: as long as the flow needs, but no longer. Aim for 3-6 steps; more means you are over-decomposing. Each step earns its place.
+- Enormous PR: accept that the reader may need more than 60 seconds. Keep the same rules, but spend the extra words on context, concrete behavior, and reviewer safety. Do not chase a tiny body by compressing meaning.
 
 If your draft for a small change runs past ~15 lines of body, you are padding. Cut until each remaining line earns its place.
 
@@ -234,6 +274,23 @@ Do not turn this into a code-review checklist. The PR description does not need
 
 When there is no ticket, skip this step. The rest of the process works the same; PURPOSE is seeded from the diff and commit messages instead.
 
+## Project context for stacked work
+
+Some PRs are slices of a larger project. The diff alone may not explain the project terms it uses. Before drafting, read enough context to define those terms correctly.
+
+Read project context when the PR body, ticket, branch name, commit messages, code comments, or diff mentions:
+- a related PR, parent PR, follow-up PR, or stacked branch;
+- a deferred piece of the design;
+- an upstream dependency;
+- a project-specific term whose local meaning is not obvious from the diff;
+- a roadmap label, subsystem nickname, architecture slogan, or branch-local name.
+
+Use available source material: linked tickets, linked PRs, nearby docs, code comments, commit messages, and project memory. Build a private term map: term -> plain behavior -> source. Do not dump the map into the PR description. Use it to write the shortest useful explanation.
+
+If a term controls the reader's understanding of the PR and you cannot resolve it from available context, stop and ask the user. Do not guess. Do not write around the missing definition with vaguer words.
+
+Do not add a `## CONTEXT` section by default. Put a one- or two-sentence context bridge in PURPOSE or DESCRIPTION only when the reviewer needs it to understand this PR's delta.
+
 ## Link verification
 
 Before posting or updating a PR body, verify every link you can. Broken links in PR descriptions waste reviewer time and make the surrounding prose less trustworthy.
@@ -268,48 +325,61 @@ One line each. Fold into NOTES as bullets.
 
 ### Small change (collapsed DESCRIPTION)
 
-    ## SYNOPSIS
-    Narrow the **rotation advisory lock** to DB writes only; release across KMS I/O.
+```md
+## SYNOPSIS
+Narrow the **rotation advisory lock** to DB writes only; release across KMS I/O.
 
-    Ticket: [PLAT-412](https://example.atlassian.net/browse/PLAT-412)
+Ticket: [PLAT-412](https://example.atlassian.net/browse/PLAT-412)
 
-    ## PURPOSE
-    The secret rotation worker currently holds a Postgres advisory lock for the full rotation batch, including network I/O to KMS. A batch of 500 keys blocks all other rotations for ~3 min, stalling unrelated tenants sharing the worker pool.
+## PURPOSE
+The secret rotation worker currently holds a Postgres advisory lock for the full rotation batch, including network I/O to KMS. A batch of 500 keys blocks all other rotations for ~3 min, stalling unrelated tenants sharing the worker pool.
 
-    ## DESCRIPTION
-    `rotateBatch` acquires `pg_advisory_lock(rotation_ns)` once, then loops: read key, call KMS encrypt, write ciphertext, advance cursor. The lock spans the whole loop.
+## DESCRIPTION
+`rotateBatch` acquires `pg_advisory_lock(rotation_ns)` once, then loops: read key, call KMS encrypt, write ciphertext, advance cursor. The lock spans the whole loop.
 
-    This PR moves the lock acquisition inside the loop, around only the DB read+write. KMS calls run unlocked. Cursor advancement unchanged.
+This PR moves the lock acquisition inside the loop, around only the DB read+write. KMS calls run unlocked. Cursor advancement unchanged.
 
-    Net effect: concurrent rotations for other tenants no longer block on KMS I/O, removing the stall in PURPOSE. A crash mid-batch resumes from the cursor, which was already the behavior on any non-lock failure.
+Net effect: concurrent rotations for other tenants no longer block on KMS I/O, removing the stall in PURPOSE. A crash mid-batch resumes from the cursor, which was already the behavior on any non-lock failure.
 
-    ## NOTES
-    - **lock is no longer held across KMS** - intentional narrowing, not a regression.
+## NOTES
+- **lock is no longer held across KMS** - intentional narrowing, not a regression.
+```
 
 ### Large change (with WALK-THROUGH)
 
-    ## SYNOPSIS
-    Move **connection acquisition** inside the transaction boundary to prevent **lock leaks across retry loops**.
+```md
+## SYNOPSIS
+Move **connection acquisition** inside the transaction boundary to prevent **lock leaks across retry loops**.
+
+Ticket: [PLAT-501](https://example.atlassian.net/browse/PLAT-501)
+
+## PURPOSE
+The batch processor opens a database connection before entering the retry loop, then begins a transaction inside each retry attempt. If a retry fails and the loop continues, the connection is reused for the next attempt without releasing the transaction savepoint. This holds locks from the failed attempt across the retry, blocking concurrent writers.
 
-    Ticket: [PLAT-501](https://example.atlassian.net/browse/PLAT-501)
+## DESCRIPTION
+The root cause is a mismatch between connection lifecycle and transaction lifecycle. The connection is acquired once and held for the whole batch. The transaction is per-attempt but the savepoint release is skipped on error. The fix is to acquire a fresh connection per attempt, so each retry starts with a clean connection and a clean transaction boundary.
 
-    ## PURPOSE
-    The batch processor opens a database connection before entering the retry loop, then begins a transaction inside each retry attempt. If a retry fails and the loop continues, the connection is reused for the next attempt without releasing the transaction savepoint. This holds locks from the failed attempt across the retry, blocking concurrent writers.
+## WALK-THROUGH
 
-    ## DESCRIPTION
-    The root cause is a mismatch between connection lifecycle and transaction lifecycle. The connection is acquired once and held for the whole batch. The transaction is per-attempt but the savepoint release is skipped on error. The fix is to acquire a fresh connection per attempt, so each retry starts with a clean connection and a clean transaction boundary.
+1. **Connection acquired once at the top** - the handler opens a database connection before entering the retry loop and holds it for the whole batch.
+   - **NOW** - _a fresh connection is acquired per attempt, so each retry starts with a clean connection._
 
-    ## WALK-THROUGH
+2. **Transaction begins inside each retry** - `BEGIN` is issued inside the retry loop, but the connection from the failed attempt is reused without releasing the savepoint.
+   - **NOW** - _`BEGIN` is issued immediately after acquisition, so the connection and transaction lifecycles are aligned._
 
-    1. **Batch processor receives work item** - the handler now calls `acquireConnection` per attempt instead of once at the top.
-    2. **Connection enters transaction** - `BEGIN` is issued immediately after acquisition, so the connection and transaction lifecycles are aligned.
-    3. **Work executes** - the batch runs its queries inside the transaction. _This is where the lock leak originated: the old code held the connection open across retries, dragging the previous transaction's locks into the next attempt._
-    4. **Retry on failure** - on error, the connection is released and a new one is acquired for the next attempt. The savepoint from the failed attempt is gone with the connection.
-    5. **Commit on success** - the transaction commits and the connection is released. Clean exit.
+3. **Work executes inside the transaction** - the batch runs its queries, holding locks from the failed attempt across the retry.
+   - **NOW** - _the batch runs inside a clean transaction. The previous attempt's locks are gone with the released connection._
 
-    ## NOTES
-    - **connection pool pressure** - acquiring per attempt increases pool churn under heavy retry load. Acceptable because retries are rare (observed <0.1% in prod).
-    - **PLAT-501 scope** - this addresses the lock leak. The retry backoff strategy described in the ticket is deferred to a follow-up.
+4. **Retry reuses the connection** - on error, the loop continues with the same connection, dragging the previous transaction's locks into the next attempt.
+   - **NOW** - _on error, the connection is released and a new one is acquired. The savepoint from the failed attempt is gone with the connection._
+
+5. **Commit releases the connection** - on success, the transaction commits but the connection was already held for the whole batch.
+   - **NOW** - _the transaction commits and the connection is released. Clean exit per attempt._
+
+## NOTES
+- **connection pool pressure** - acquiring per attempt increases pool churn under heavy retry load. Acceptable because retries are rare (observed <0.1% in prod).
+- **PLAT-501 scope** - this addresses the lock leak. The retry backoff strategy described in the ticket is deferred to a follow-up.
+```
 
 Scan the bolds only:
 > rotation advisory lock ... KMS I/O ... connection acquisition ... lock leaks across retry loops ... Batch processor receives work item ... Connection enters transaction ... Work executes ... Retry on failure ... Commit on success ... lock is no longer held across KMS ... connection pool pressure ... PLAT-501 scope
@@ -320,17 +390,19 @@ That reading alone conveys the shape and scope of both changes. The prose is for
 
 1. **Gather**: `git log $MERGE_BASE..HEAD`, `git diff $MERGE_BASE..HEAD --stat`, commit messages, current branch name. Apply the ticket resolution order (SYNOPSIS section) - infer first, ask only if nothing matches. Skim the diff; identify decision points (components or branches where behavior differs before vs after). Identify the workflow or lifecycle path if the change has one.
 2. **Read ticket context**: if a ticket is resolved, fetch its description. Use it to seed PURPOSE and identify reviewer-relevant plan changes: revisions, pivots caused by code reality, discoveries after the ticket was written, and deferred or unnecessary ticket items.
-3. **Draft PURPOSE first**, in one breath, without looking at code. If you cannot state the harm in two sentences, you do not understand the PR yet. Go back and read. When a ticket is available, seed PURPOSE from its problem statement, but verify against the code.
-4. **Write DESCRIPTION**: choose the right depth (collapsed for small, three-layer for medium, root-cause + concept for large with WALK-THROUGH). Name everything you will refer to later. Organize by workflow/data-flow, not by touched symbol.
-5. **Write WALK-THROUGH** (if needed): numbered steps in execution order. Bold the step leads. State what changed, not what you did.
-6. **Write SYNOPSIS last** - it is a compression of PURPOSE + the core mechanic.
-7. **Bold and italicize the save points** in the allowed locations. Bold phrases that name the change (components, mechanisms, behaviors). Italicize phrases that orient to significance (conclusions, payoffs), at most one per paragraph. Apply the scan check: read only the bold and italic fragments and verify the shape comes through.
-8. **Add NOTES** for AI-reviewer defensive lines, scope disclaimers, ticket scope mismatches, and remaining work. Use `## NOTES` header. Omit if empty.
-9. **robots.txt only when earned**: do not add it during initial authoring. It is added later, in response to an automated reviewer's false positive (see its section). When you do add it, use the collapsed `<details>` format with `<summary>robots.txt</summary>`, keep the editing HTML comment at the top of the block, and keep the human-warning line first after the comment.
-10. **Verify links**: check ticket/PR links, repo file links, and external docs where tooling allows. Do not claim an unverified link was verified.
-11. **Verify prose style**: check each rule in Prose style. Cut design-narration, authoring-sequence, and buzzwordy abstractions. Verify plain ASCII. Verify first-use definitions for subsystem jargon. Verify plain English nouns (no code-domain nouns in prose). Verify conclusion-first in PURPOSE. Verify NOTES bullets are either short pointers or self-contained. Verify one-paragraph-one-physical-line for GitHub rendering. The robots.txt section is exempt from these prose rules below its human-warning line.
-12. **Verify length**: if the body exceeds the ceiling for its conceptual size, cut until each line earns its place.
-13. **Submit** via `gh pr create --body "$(cat <<'EOF' ... EOF)"` to preserve formatting.
+3. **Read project context for stacked work**: if the PR refers to related PRs, follow-ups, deferred design, upstream dependencies, or unexplained project terms, read the linked source material before drafting. Build a private term map. If a term controls the PR and you cannot resolve it, ask the user.
+4. **Draft PURPOSE first**, in one breath, without looking at code. If you cannot state the harm in two sentences, you do not understand the PR yet. Go back and read. When a ticket is available, seed PURPOSE from its problem statement, but verify against the code.
+5. **Write DESCRIPTION**: choose the right depth (collapsed for small, three-layer for medium, root-cause + concept for large with WALK-THROUGH). Name everything you will refer to later. Organize by workflow/data-flow, not by touched symbol. Add a one- or two-sentence context bridge only when stacked-project context is needed to understand this PR's delta.
+6. **Write WALK-THROUGH** (if needed): numbered steps in execution order. Bold the step leads. State what changed, not what you did.
+7. **Write SYNOPSIS last** - it is a compression of PURPOSE + the core mechanic.
+8. **Bold and italicize the save points** in the allowed locations. Bold phrases that name the change (components, mechanisms, behaviors). Italicize phrases that orient to significance (conclusions, payoffs), at most one per paragraph. Apply the scan check: read only the bold and italic fragments and verify the shape comes through.
+9. **Add NOTES** for AI-reviewer defensive lines, scope disclaimers, ticket scope mismatches, and remaining work. Use `## NOTES` header. Omit if empty.
+10. **robots.txt only when earned**: do not add it during initial authoring. It is added later, in response to an automated reviewer's false positive (see its section). When you do add it, use the collapsed `<details>` format with `<summary>robots.txt</summary>`, keep the editing HTML comment at the top of the block, and keep the human-warning line first after the comment.
+11. **Verify links**: check ticket/PR links, repo file links, and external docs where tooling allows. Do not claim an unverified link was verified.
+12. **Verify prose style and core principle**: check each rule in Prose style. Cut design-narration, authoring-sequence, and buzzwordy abstractions. Verify plain ASCII. Verify first-use definitions for subsystem jargon. Verify project-private labels are translated before use. Verify plain English nouns (no code-domain nouns in prose). Verify conclusion-first in PURPOSE. Verify NOTES bullets are either short pointers or self-contained. Verify one-paragraph-one-physical-line for GitHub rendering. The robots.txt section is exempt from these prose rules below its human-warning line.
+13. **Clarity pass**: read the draft as a cold reviewer skimming the PR. Rewrite before returning it; do not tell the user you performed this pass. Check: does every project-specific term get plain-English meaning before or with the label? Are ambiguous terms qualified or replaced with concrete behavior? Did you replace code/comment shorthand with reader-facing behavior when the shorthand is less clear? Does every process word name object/action/effect? Does every contrast name old and new behavior? Does every causal sentence show the middle step? Did you preserve connective tissue instead of compressing meaning into noun stacks? If the draft got longer, cut a lower-value claim instead of compressing a high-value one.
+14. **Verify length**: if the body exceeds the ceiling for its conceptual size, cut until each line earns its place. For enormous PRs, accept extra length only when it buys context, concrete behavior, or reviewer safety.
+15. **Submit** via `gh pr create --body "$(cat <<'EOF' ... EOF)"` to preserve formatting.
 
 ## Anti-patterns
 
@@ -346,7 +418,12 @@ That reading alone conveys the shape and scope of both changes. The prose is for
 - **Orphaned synopsis.** A bold lead paragraph with no `## SYNOPSIS` header above a body that does use headers. Add the header; it is mandatory.
 - **Bare `Notes:` line.** Use `## NOTES` header or omit the section entirely.
 - **Organizing by touched symbol.** A bullet list of "changed X in file A, changed Y in file B" reads as disconnected touchpoints. Follow the data flow.
-- **Buzzwordy abstractions.** "identity contract", "canonical hash", "check in isolation" - if it sounds like it is trying to sound smart, replace it with plain concrete wording.
+- **Buzzwordy abstractions.** "identity contract", "canonical hash", "check in isolation", "shared seam" - if it sounds like it is trying to sound smart, replace it with plain concrete wording. If "seam" means a conceptual border, say "boundary". If it means common code, say "shared helper", "shared function", or "shared SQL expression".
+- **Project-private labels as explanations.** Roadmap names, subsystem nicknames, architecture slogans, ticket shorthand, internal stack names, and branch-local labels are not explanations. Say what the code does first. The label can follow only if it helps a reviewer connect the prose to the code.
+- **Compressed meaning.** "Coalesced refresh", "synchronous repair", "derived projection", "normalized identity", "resolved state", and similar phrases are not clear unless the sentence says what object changes and what the result is. If a reader has to infer the missing action, expand the sentence or cut the claim.
+- **Copied code shorthand.** A term from a function name, code comment, metric, or existing PR body is not automatically good prose. If the code's word is less concrete than the behavior, translate it.
+- **Invisible contrast.** "X is synchronous now" or "Y is now shared" means little unless the old behavior is nearby. Name both sides of the change.
+- **Missing causal step.** A sentence with "so", "because", "therefore", "prevents", or "allows" must show the mechanism. If the cause and effect do not obviously touch, add the missing step or remove the causal claim.
 - **Loaded language.** Using avoidable loaded terms when neutral terms exist. Prefer allowlist/blocklist, primary/replica, and precise role names.
 - **Smart punctuation.** Em dashes, smart quotes, ellipsis glyphs. Use plain ASCII.
 - **Splitting paragraphs across lines.** GitHub renders each line break as a visible break. One paragraph = one physical line.
@@ -358,3 +435,4 @@ That reading alone conveys the shape and scope of both changes. The prose is for
 - **NOTES bullets that are both wordy and terse.** A bullet that compresses a paragraph of rationale into one dense sentence reads as a private note. Either flag the thing and point to the full explanation, or write a self-contained sentence or two. Not the middle thing.
 - **robots.txt as a suppression lever.** Writing "ignore the finding about X" or "skip checking X" in robots.txt turns it into a rubber stamp and a prompt-injection surface. Explain what X does and the intent behind it so the reviewer clears its own false positive; never instruct it to stop looking.
 - **Preemptive robots.txt.** Adding the section before any automated reviewer has actually produced a false positive. It is a response to a demonstrated misread, not scaffolding.
+- **Over-decomposed WALK-THROUGH.** Nine steps for a refresh flow means you are listing function calls, not workflow phases. Group related stages. A step is a phase the reviewer can hold in their head, not a single operation. If a step's bold lead is a function name, you went too granular.

package/artifacts/skills/thatch-code-review.md

@@ -104,7 +104,15 @@ For the integration review unit (5+ points), dispatch a sub-agent focused on:
 
 ## Step 7: Synthesize
 
-After all sub-agents complete, load the thatch-review-synthesizer skill to verify findings, deduplicate across specialists, classify (CONFIRMED/REJECTED/UNVERIFIABLE), and produce the final severity-grouped report.
+After all sub-agents complete, load the thatch-review-synthesizer skill to verify findings, deduplicate across specialists, classify (CONFIRMED/REJECTED/UNVERIFIABLE), and produce the final report.
+
+Pass the synthesizer:
+- The project context brief from Step 2.
+- The workflow guide from Step 3.
+- The specialist findings.
+- The prior-comments register when present.
+
+The final user-facing report MUST begin with a concise explanation of the workflow(s) this PR changes before listing findings. Use one `### Workflow changes` section, with one subheading per affected workflow when there are multiple. Use the before/now walkthrough shape from the pr-description skill: numbered step = existing behavior; `NOW` sub-bullet = what the PR changes; `N/A` for new stages. This gives the user a map of the change before the findings. Keep it short: 3-6 steps per workflow.
 
 Confirmed LOW findings are mandatory in the final report, including mechanical findings (pedantic, no-slop, breadcrumbs, docs, naming, style, comments). Do not omit them for being non-functional.
 
@@ -117,7 +125,7 @@ Alternatively, perform the synthesis yourself:
 4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE. For behavioral findings, apply citation verification, reachability, and intent verification. For mechanical findings, verify the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy.
 5. Cross-reference against the prior-comments register if one was built in Step 2: tag matching findings `Provenance: previously identified by @author, PR #N, DATE` and produce the `### Previously identified findings` appendix per the synthesizer skill.
 6. Calibrate severity (BLOCKING > HIGH > MEDIUM > LOW) based on your verification.
-7. Produce a final report grouped by severity, with coverage gaps noted. Include every confirmed LOW finding.
+7. Produce a final report with a workflow-change preface, findings grouped by severity, and coverage gaps noted. Include every confirmed LOW finding.
 
 ## Specialist briefing template
 

package/artifacts/skills/thatch-review-synthesizer.md

@@ -90,11 +90,36 @@ You MUST produce the full report structure below. Do not simplify or omit sectio
 
 Confirmed LOW findings are mandatory. Do not summarize them away or omit them for being non-functional. Pedantic, no-slop, breadcrumbs, docs, naming, style, and comment findings are first-class review findings when confirmed. Group them under LOW, but include every one.
 
+The report is user-facing. Start by teaching the changed workflows before listing findings. Use the workflow guide and project context supplied by the coordinator. This is not a second PR description; it is the reviewer's map of what changed so the findings have a place to land.
+
+For each affected workflow, use the same before/now shape as PR descriptions:
+- Numbered step: existing behavior or current workflow stage.
+- `NOW` sub-bullet: what this PR changes at that stage.
+- `N/A` as the numbered item for a new stage.
+
+Keep this section short. Aim for 3-6 steps per workflow. If there are multiple affected workflows, use one subheading per workflow. If the change is small and no workflow changed, write "None — no workflow-level behavior changed".
+
+Apply the same clarity rules as the writing skills: prefer concrete terms over ambiguous ones, translate project-private labels before using them, name object/action/effect for process words, show both sides of contrasts, and show causal middle steps. Do not copy code-comment shorthand when reader-facing behavior is clearer.
+
 ### Scope
+
 - Branch/range reviewed
 - Design context (if provided)
 
+### Workflow changes
+
+For each affected workflow:
+
+#### Workflow name
+
+1. **Existing behavior or stage** — one sentence describing how the code worked before this PR.
+   - **NOW** — _one sentence describing what this PR changes._
+
+2. **N/A**
+   - **NOW** — _one sentence describing a new stage this PR adds._
+
 ### Confirmed findings
+
 For each finding, grouped by severity (BLOCKING > HIGH > MEDIUM > LOW). Each finding MUST include all of these fields:
 1. **Severity** and **category** (from the specialist's taxonomy)
 2. **Source**: which specialist found it
@@ -105,12 +130,15 @@ For each finding, grouped by severity (BLOCKING > HIGH > MEDIUM > LOW). Each fin
 7. **Provenance**: branch-introduced or pre-existing. If the finding matches a prior review comment, append `; previously identified by @author, PR #N, DATE` to this field. For findings matching an `addressed` prior comment, also add a one-line note on why the finding persists so the user can investigate whether the prior resolution is incomplete or the issue has regressed.
 
 ### Rejected findings (appendix, brief)
+
 Findings you rejected and a one-line reason why. Include the specialist and location for each.
 
 ### Pre-existing bugs (appendix, brief)
+
 Findings you verified as real but pre-existing, with a one-line note on the issue and its potential impact.
 
 ### Previously identified findings (appendix — only when a prior-comments register was provided)
+
 List every entry from the prior-comments register here. For each entry, produce a one-block record:
 1. **Author and date** of the original comment
 2. **Original location** (`file:line @ commit-SHA`, or `summary review`) and **current HEAD location** (`file:line`) if locatable
@@ -125,4 +153,5 @@ List every entry from the prior-comments register here. For each entry, produce
 If no prior-comments register was provided (local-branch review or first round on the PR/MR), state `None — no prior review comments to cross-reference` and move on.
 
 ### Coverage gaps
+
 Note which files or areas were NOT covered by any specialist.

package/artifacts/skills/ticket-description.md

@@ -1,10 +1,20 @@
 ---
 name: ticket-description
-description: Draft a ticket description using instructional-design scaffolding (SYNOPSIS / PROBLEM / BACKGROUND / PROPOSED APPROACH / ACCEPTANCE CRITERIA / RELEASE PLAN / VALIDATION / DEPENDENCIES / NOTES) with bold and italic emphasis on the phrases that carry the meaning, so a reader skimming only the emphasized fragments still gets the story. Use when the user asks you to write, draft, or file a ticket, issue, or work item (Linear or Jira). Do NOT use for PR descriptions (use pr-description), commit messages, or design docs.
+description: Draft a ticket description (SYNOPSIS / PROBLEM / BACKGROUND / PROPOSED APPROACH / ACCEPTANCE CRITERIA / RELEASE PLAN / VALIDATION / DEPENDENCIES / NOTES) with bold and italic emphasis on the phrases that carry the meaning, so a reader skimming only the emphasized fragments still gets the story. Use when the user asks you to write, draft, or file a ticket, issue, or work item (Linear or Jira). Do NOT use for PR descriptions (use pr-description), commit messages, or design docs.
 ---
 
 # Writing ticket descriptions
 
+## Core principle
+
+Write for humans. Not for LLMs. Not to impress. Not to pad.
+
+Every sentence earns its place or gets cut. Plain English over jargon. Concrete over abstract. Short over long. A ticket a human reads once and can start work from beats one that looks thorough but says nothing.
+
+If a word does not help a human understand the work, it is dead weight. If a sentence restates the previous one, one is redundant. If a phrase sounds smart but you cannot explain it in simpler words, it is a buzzword. Cut, replace, or simplify.
+
+Target a 7th-grade reading level. Not because the reader is dumb, but because plain prose is faster to read and harder to misread. Short sentences, common words, one idea each. The concepts stay technical; the language stays simple.
+
 ## The reader
 
 You are writing for two people who share one trait: neither has your context, and neither knows this subsystem's jargon.
@@ -15,7 +25,7 @@ The second reader is an **implementer** picking up the ticket cold. They need to
 
 The description is not a design doc. It is a specification that makes work startable. A design doc (when one is warranted) may live in repo docs, Linear, Notion, Archbee, Google Docs, Figma, or another system; link it from the ticket instead of inlining it. The ticket's job is to define the problem, propose a direction, and set the gates that define "done."
 
-This is **instructional design**, not documentation. Each section has a cognitive goal:
+Each section has one job:
 - SYNOPSIS: orient to the class of work and affected area.
 - PROBLEM: make the reader agree there is something worth solving.
 - BACKGROUND: give the implementer the context they would otherwise re-derive.
@@ -26,7 +36,7 @@ This is **instructional design**, not documentation. Each section has a cognitiv
 - DEPENDENCIES: explain ordering constraints, not just list them.
 - NOTES: flag scope limits, intentional non-goals, and things that look in-scope but aren't.
 
-Layer the knowledge so each section builds on the previous one. The reader should never encounter a concept in section N that was not introduced in section N-1.
+Each section builds on the previous one. The reader should never encounter a concept in section N that was not introduced in section N-1.
 
 ## Structure
 
@@ -119,7 +129,7 @@ Only when prod verification is non-trivial. A pure refactor with good tests does
 
 ### DEPENDENCIES (conditional)
 
-Blocking relationships and ordering constraints. "Blocked by PLAT-126" is the tracker field; the *why* belongs here: "PLAT-125 partitions by location_fingerprint, so it can only run after backfill completes (count == 0), not merely after PLAT-124 merges." That kind of nuance is what prevents a well-intentioned lead from reordering the queue.
+Blocking relationships and ordering constraints. "Blocked by PLAT-126" is the tracker field; the _why_ belongs here: "PLAT-125 partitions by location_fingerprint, so it can only run after backfill completes (count == 0), not merely after PLAT-124 merges." That kind of nuance is what prevents a well-intentioned lead from reordering the queue.
 
 Distinguish hard data dependencies (cannot run until X completes) from soft dependencies (should run after X for cleanliness, but technically works independently). Say which kind it is.
 
@@ -141,7 +151,7 @@ If there are no notes, omit the section entirely. Do not emit an empty `## NOTES
 
 ## Emphasis for scanning: bold and italics
 
-Bold and italicize the "save points" - the phrases that carry meaning - not whole sentences. A reader who skims *only* the bold and italic fragments should get the story; full prose is for when they want detail.
+Bold and italicize the "save points" - the phrases that carry meaning - not whole sentences. A reader who skims _only_ the bold and italic fragments should get the story; full prose is for when they want detail.
 
 **What to bold:** phrases that name the **work itself** - the component, the failure mode, the mechanism, the behavior the ticket asks for. These are the nouns and verbs that would appear in a diff of the design, not a diff of the code. "**circular wait** in the **KeyManager**" names the failure mode and the component. "**load key material outside the mutex**" names the mechanism.
 
@@ -177,10 +187,11 @@ These are hard rules, not suggestions.
 5. **No authoring-sequence narration.** Never describe the order you discovered things in, which draft had what, or what a later revision will add. Describe the ticket as it stands.
 6. **Italics for orientation asides.** Use `_italics_` for a one-phrase aside that orients the reader: _This is where the deadlock lived_. Not for emphasis.
 7. **Plain ASCII only.** No smart quotes, smart apostrophes, em dashes, en dashes, ellipsis glyphs, or arrow glyphs. Use plain hyphens (sparingly) for asides; semicolons are often better.
-8. **No buzzwordy abstractions.** If a phrase sounds like it is trying to sound smart, cut or replace it. Name the code and behavior directly. "identity contract" -> "the struct field that identifies the owner". "canonical hash" -> "the SHA-256 we compute on ingestion".
-9. **Prescriptive voice.** The ticket proposes work that hasn't happened yet. Use "the fix should...", "the implementation must...", "the worker should..." not "this PR moves..." or "the code now...". The PR description uses descriptive voice; the ticket uses prescriptive.
-10. **Default to a numbered outline for steps.** A flat list, with an occasional inline branch ("if the path is not in the registry, return a 404; otherwise continue to step 6"), covers almost every workflow. The bar for a diagram or Mermaid chart is high: reach for one only when the flow genuinely needs two dimensions to read - a graph network with many nodes and edges, or a workflow that recurses, forks, and rejoins in ways a linear outline cannot follow without constant back-references. If the flow is one or two levels deep and does not recurse or redirect, an outline is clearer and cheaper to maintain than a diagram.
-11. **Avoid loaded language.** Use neutral, current terminology unless the repo's established name is different. Prefer allowlist/blocklist over whitelist/blacklist, primary/replica over master/slave, and precise role names over moralized labels like "bad" or "evil".
+8. **No buzzwordy abstractions.** If a phrase sounds like it is trying to sound smart, cut or replace it. Name the code and behavior directly. "identity contract" -> "the struct field that identifies the owner". "canonical hash" -> "the SHA-256 we compute on ingestion". "leverage" -> "use". "utilize" -> "use". "facilitate" -> "help". If you cannot say what a phrase means in plain English, it does not belong. Buzzwords are the number-one signal that an AI wrote the ticket; do not send that signal.
+9. **Prefer specific terms over ambiguous ones.** If a word can mean more than one thing in this ticket, qualify it or replace it with the specific behavior. Do not rely on the reader guessing the local meaning. Ordinary words can be ambiguous when the code gives them a special role: claim, owner, active, current, generation, repair, coalesce, terminal, source, scope, sync, publish, resolve. "Publish the value" is vague. "Persist the value in the database so the UI can display it" is specific.
+10. **Prescriptive voice.** The ticket proposes work that hasn't happened yet. Use "the fix should...", "the implementation must...", "the worker should..." not "this PR moves..." or "the code now...". The PR description uses descriptive voice; the ticket uses prescriptive.
+11. **Default to a numbered outline for steps.** A flat list, with an occasional inline branch ("if the path is not in the registry, return a 404; otherwise continue to step 6"), covers almost every workflow. The bar for a diagram or Mermaid chart is high: reach for one only when the flow genuinely needs two dimensions to read - a graph network with many nodes and edges, or a workflow that recurses, forks, and rejoins in ways a linear outline cannot follow without constant back-references. If the flow is one or two levels deep and does not recurse or redirect, an outline is clearer and cheaper to maintain than a diagram.
+12. **Avoid loaded language.** Use neutral, current terminology unless the repo's established name is different. Prefer allowlist/blocklist over whitelist/blacklist, primary/replica over master/slave, and precise role names over moralized labels like "bad" or "evil".
 
 ## Length and style
 
@@ -207,6 +218,23 @@ Comparison process:
 
 When the codebase contradicts the ticket, flag the discrepancy to the user before drafting. Do not silently paper over the gap.
 
+## Project context for planned work
+
+Some tickets are slices of a larger project. The code alone may not explain the project terms, ordering constraints, or prior decisions the implementer needs. Before drafting, read enough context to make the ticket startable for an engineer new to this area.
+
+Read project context when the request, existing ticket, code comments, branch name, prior PRs, docs, or discussion mentions:
+- a parent ticket, related PR, follow-up, or multi-ticket project;
+- a deferred part of the design;
+- an upstream dependency;
+- a project-specific term whose local meaning is not obvious from the code touched by this ticket;
+- a roadmap label, subsystem nickname, architecture slogan, or branch-local name.
+
+Use available source material: linked tickets, linked PRs, nearby docs, code comments, commit messages, and project memory. Build a private term map: term -> plain behavior -> source. Do not dump the map into the ticket. Use it to write the shortest useful BACKGROUND.
+
+If a term or dependency controls the work and you cannot resolve it from available context, stop and ask the user. Do not guess. Do not write around the missing definition with vaguer words.
+
+Put project context in BACKGROUND only when it helps the implementer start work or helps a lead schedule it correctly. Omit generic backstory.
+
 ## Search before create
 
 Before filing a new ticket, search for likely duplicates in the tracker. Use the proposed title, problem keywords, affected subsystem, and any incident/customer/project references. If a plausible duplicate exists, surface it to the user before drafting or filing.
@@ -361,20 +389,22 @@ That reading alone conveys the shape, scope, and gates of all three tickets.
 1. **Gather**: read the code the ticket references. Check `git log` for recent changes to the same files. Identify the problem, the prior work, and the proposed direction.
 2. **Search before create**: search Linear/Jira for likely duplicate tickets. If one exists, surface it before drafting or filing.
 3. **Codebase comparison**: verify the problem still exists in the current code. If it was already fixed, tell the user. If it was partially mitigated, note the mitigation.
-4. **Draft PROBLEM first**, in one breath, without looking at code. If you cannot state the harm in three sentences, you do not understand the problem yet. Go back and read.
-5. **Write BACKGROUND** (if needed): what prior work led here, what was done, what was left behind.
-6. **Write PROPOSED APPROACH**: the compass heading, not the map. Prescriptive voice.
-7. **Write ACCEPTANCE CRITERIA**: observable, testable bullets. Name the test shape where relevant.
-8. **Write RELEASE PLAN** (if needed): flags, ordering, rollback.
-9. **Write VALIDATION** (if needed): monitoring, signals, smoke tests.
-10. **Write DEPENDENCIES** (if needed): what blocks this, what this blocks, and why.
-11. **Write SYNOPSIS last** - it is a compression of PROBLEM + the core approach.
-12. **Bold and italicize the save points** in the allowed locations. Bold phrases that name the work (components, mechanisms, behaviors). Italicize phrases that orient to significance (conclusions, payoffs), at most one per paragraph. Apply the scan check.
-13. **Add NOTES** for non-goals, declined alternatives, and scope limits. Use `## NOTES` header. Omit if empty.
-14. **Suggest Linear labels** when the ticket is being filed in Linear. Use obvious stable labels only; do not guess initiative labels.
-15. **Verify links**: check repo file links, external docs, tickets, PRs, and design artifacts where tooling allows. Do not claim an unverified link was verified.
-16. **Verify prose style**: check each rule in Prose style. Cut design-narration, authoring-sequence, and buzzwordy abstractions. Verify plain ASCII. Verify prescriptive voice (not descriptive). Verify first-use definitions for subsystem jargon in BACKGROUND or PROBLEM. Verify plain English nouns (no code-domain nouns in prose). Verify conclusion-first in PROBLEM. Verify NOTES bullets are either short pointers or self-contained.
-17. **Verify length**: if the body exceeds what the work's conceptual size warrants, cut until each line earns its place. If PROPOSED APPROACH dominates, consider splitting into a design doc plus ticket.
+4. **Read project context for planned work**: if the ticket is part of a larger project, depends on prior work, uses unexplained project terms, or has scheduling dependencies, read the linked tickets, PRs, docs, comments, and memory before drafting. Build a private term map. If a term or dependency controls the work and you cannot resolve it, ask the user.
+5. **Draft PROBLEM first**, in one breath, without looking at code. If you cannot state the harm in three sentences, you do not understand the problem yet. Go back and read.
+6. **Write BACKGROUND** (if needed): what prior work led here, what was done, what was left behind, and what project context an engineer new to this area needs to start.
+7. **Write PROPOSED APPROACH**: the compass heading, not the map. Prescriptive voice.
+8. **Write ACCEPTANCE CRITERIA**: observable, testable bullets. Name the test shape where relevant.
+9. **Write RELEASE PLAN** (if needed): flags, ordering, rollback.
+10. **Write VALIDATION** (if needed): monitoring, signals, smoke tests.
+11. **Write DEPENDENCIES** (if needed): what blocks this, what this blocks, and why.
+12. **Write SYNOPSIS last** - it is a compression of PROBLEM + the core approach.
+13. **Bold and italicize the save points** in the allowed locations. Bold phrases that name the work (components, mechanisms, behaviors). Italicize phrases that orient to significance (conclusions, payoffs), at most one per paragraph. Apply the scan check.
+14. **Add NOTES** for non-goals, declined alternatives, and scope limits. Use `## NOTES` header. Omit if empty.
+15. **Suggest Linear labels** when the ticket is being filed in Linear. Use obvious stable labels only; do not guess initiative labels.
+16. **Verify links**: check repo file links, external docs, tickets, PRs, and design artifacts where tooling allows. Do not claim an unverified link was verified.
+17. **Verify prose style and core principle**: check each rule in Prose style. Cut design-narration, authoring-sequence, and buzzwordy abstractions. Verify plain ASCII. Verify prescriptive voice (not descriptive). Verify first-use definitions for subsystem jargon in BACKGROUND or PROBLEM. Verify plain English nouns (no code-domain nouns in prose). Verify conclusion-first in PROBLEM. Verify NOTES bullets are either short pointers or self-contained.
+18. **Clarity pass**: read the draft as a cold lead skimming a backlog, then as an implementer picking up the work cold. Rewrite before returning it; do not tell the user you performed this pass. Check: does every project-specific term get plain-English meaning before or with the label? Are ambiguous terms qualified or replaced with specific behavior? Does every process word name object/action/effect? Does every contrast name current and proposed behavior? Does every causal sentence show the middle step? Did you preserve connective tissue instead of compressing meaning into noun stacks? If the draft got longer, cut a lower-value claim instead of compressing a high-value one.
+19. **Verify length**: if the body exceeds what the work's conceptual size warrants, cut until each line earns its place. If PROPOSED APPROACH dominates, consider splitting into a design doc plus ticket.
 
 ## Anti-patterns
 

package/docs/dev/skills.md

@@ -36,21 +36,21 @@ description: Extract durable project facts ... Use when ...
 | `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth-wall breaks, em dashes, filler. |
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of behavior? |
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
-| `thatch-review-synthesizer` | Verify specialist findings against code, dedupe, classify, calibrate severity. Cross-references findings against prior review comments when a follow-up round register is provided; produces a Previously identified appendix. |
+| `thatch-review-synthesizer` | Verify specialist findings against code, dedupe, classify, calibrate severity. Starts the final report with a workflow-change preface, then cross-references findings against prior review comments when a follow-up round register is provided. |
 | `thatch-review-context` | Gather project/feature context (PR descriptions, git archaeology, ticket references, memory) before fan-out. Prevents false positives about intentionally deferred work. Also fetches prior review comments on a connected PR/MR for follow-up-round detection and builds a register with preliminary addressed-check status per comment. |
 | `thatch-workflow-research` | Research code workflows/features affected by a change or planned change. Reads code flows, comments, git history, memories, docs. Produces a guide to the code for reviewers or planners. |
 | `thatch-change-walkthrough` | Explain a change to the user as a teaching walkthrough: resolve the delta, research each affected workflow at the merge-base, teach current behavior, then overlay the modifications with file:line citations and analogies. |
 | `thatch-code-walkthrough` | Explain a feature, module, or workflow to the user as a teaching walkthrough: identify the code area (optionally from a branch or PR), research how it works, teach it with file:line citations and analogies, list the key files. |
 | `thatch-session-reflection` | End-of-session memory recording (project, user, tools, self). |
-| `pr-description` | Draft PR descriptions with instructional-design scaffolding (SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES) and bold+italic emphasis for scanning. |
-| `ticket-description` | Draft ticket/issue descriptions with instructional-design scaffolding (SYNOPSIS / PROBLEM / BACKGROUND / PROPOSED APPROACH / ACCEPTANCE CRITERIA / RELEASE PLAN / VALIDATION / DEPENDENCIES / NOTES). |
+| `pr-description` | Draft PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, project-context research, clarity checks, and bold+italic emphasis for scanning. |
+| `ticket-description` | Draft ticket/issue descriptions with clear sections, project-context research, clarity checks, and bold+italic emphasis for scanning. |
 | `split-overlarge-pr` | Split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |
 
 **opencode-only (1)** — the coordinator needs sub-agent support:
 
 | Skill | Role |
 |-------|------|
-| `thatch-code-review` | Resolve review target (incl. VCS detection and connected PR/MR lookup for follow-up round detection), gather project context, research affected workflows, estimate complexity, partition, dispatch the 6 specialists in parallel, synthesize (incl. cross-referencing findings against prior review comments). |
+| `thatch-code-review` | Resolve review target (incl. VCS detection and connected PR/MR lookup for follow-up round detection), gather project context, research affected workflows, estimate complexity, partition, dispatch the 6 specialists in parallel, synthesize with a workflow-change preface and prior-comment cross-reference. |
 
 ## REVIEW_COMMON
 
@@ -115,7 +115,7 @@ and `--cursor` pass only the shared set.
 ## Memory review skills in practice
 
 - **Quick single lens**: load any specialist directly and point it at a branch.
-- **Full review on opencode**: load `thatch-code-review` — it gathers project context, researches affected workflows, dispatches all 6 specialists in parallel (with both the context brief and workflow guide injected into each briefing), then synthesizes.
+- **Full review on opencode**: load `thatch-code-review` — it gathers project context, researches affected workflows, dispatches all 6 specialists in parallel (with both the context brief and workflow guide injected into each briefing), then synthesizes a report that starts with the workflow changes before findings.
 - **Full review on Claude Code/Cursor**: run each specialist in sequence, then
   run `thatch-review-synthesizer` to verify and aggregate.
 

package/docs/user/README.md

@@ -174,7 +174,7 @@ Six specialist review lenses, each a self-contained static-analysis pass:
 | `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth wall breaks, em dashes, hedging, filler. |
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of the code's behavior? |
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
-| `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a single deduplicated, severity-grouped report. |
+| `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a report that starts with workflow changes, then deduplicated severity-grouped findings. |
 | `thatch-review-context` | Gathers project context (PR descriptions, git archaeology, ticket references, memory) before a review. Prevents false positives about intentionally deferred work. |
 | `thatch-workflow-research` | Researches code workflows and features affected by a change or planned change. Reads code flows, comments, git history, and produces a guide for reviewers or planners. |
 | `thatch-change-walkthrough` | Explains a change to the user as a teaching walkthrough: researches each affected workflow at the merge-base, teaches current behavior, then overlays the modifications with file:line citations. |
@@ -184,15 +184,15 @@ Six specialist review lenses, each a self-contained static-analysis pass:
 
 | Skill | Purpose |
 |-------|---------|
-| `pr-description` | Drafts PR descriptions using instructional-design scaffolding (SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES) with bold and italic emphasis for scanning. |
-| `ticket-description` | Drafts ticket or issue descriptions (Linear or Jira) using instructional-design scaffolding with bold and italic emphasis for scanning. |
+| `pr-description` | Drafts PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, project-context research, clarity checks, and bold/italic emphasis for scanning. |
+| `ticket-description` | Drafts ticket or issue descriptions (Linear or Jira) with clear sections, project-context research, clarity checks, and bold/italic emphasis for scanning. |
 | `split-overlarge-pr` | Splits already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |
 
 ### opencode-only skills
 
 | Skill | Purpose |
 |-------|---------|
-| `thatch-code-review` | Multi-agent review coordinator. Dispatches parallel sub-agents for triage, decomposition, specialist fan-out, and synthesis. Not available in Claude Code (requires sub-agent support). |
+| `thatch-code-review` | Multi-agent review coordinator. Dispatches parallel sub-agents for triage, decomposition, specialist fan-out, and synthesis with a workflow-change preface. Not available in Claude Code (requires sub-agent support). |
 
 ### Host availability
 
@@ -222,7 +222,8 @@ Load thatch-code-review and review branch feature-x.
 ```
 
 The coordinator will triage the change, dispatch parallel sub-agents (one per
-specialist lens), and synthesize a final report.
+specialist lens), and synthesize a final report. The report starts with the
+workflow-level changes so the findings have context.
 
 For a **full review on Claude Code** (or without the coordinator), run each
 specialist in sequence, then synthesize:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",

package/src/prompts.ts

@@ -46,8 +46,8 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-session-reflection\` — record what you learned at end of session.
 - \`thatch-fact-extractor\` — extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
 - \`thatch-dedup-classifier\` — resolve duplicate memory pairs from \`thatch_find_duplicates\`.
-- \`pr-description\` — draft a PR description using instructional-design scaffolding with bold and italic emphasis on the phrases that carry the meaning, so a reviewer skimming only the emphasized fragments still gets the story.
-- \`ticket-description\` — draft a ticket, issue, or work item (Linear or Jira) using instructional-design scaffolding with bold and italic emphasis for scanning.
+- \`pr-description\` — draft a PR description with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, using bold and italic emphasis on the phrases that carry the meaning.
+- \`ticket-description\` — draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
 - \`split-overlarge-pr\` — split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
 
 ## When to Write
@@ -85,6 +85,14 @@ about their preferences:
 2. Use thatch_prediction_update to create, reinforce, or weaken a prediction
 3. Use thatch_prediction_delete to remove a prediction created in error
 
+Code review discussions are high-signal prediction material. When working
+through potential review comments with the user, watch for preferences about
+review threshold, severity, tone, evidence, scope, false positives, or what is
+worth posting. This applies whether the user invoked a review skill, is
+reviewing your changes, or asked you to review their changes or another LLM's
+changes. Before creating a new prediction, query for an existing one and
+reinforce or adjust it when possible.
+
 ## What to Store
 
 - **Global store**: user observations, agent personality, system environment
@@ -212,8 +220,8 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-session-reflection\` — record what you learned at end of session.
 - \`thatch-fact-extractor\` — extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
 - \`thatch-dedup-classifier\` — resolve duplicate memory pairs from \`find_duplicates\`.
-- \`pr-description\` — draft a PR description using instructional-design scaffolding with bold and italic emphasis on the phrases that carry the meaning, so a reviewer skimming only the emphasized fragments still gets the story.
-- \`ticket-description\` — draft a ticket, issue, or work item (Linear or Jira) using instructional-design scaffolding with bold and italic emphasis for scanning.
+- \`pr-description\` — draft a PR description with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, using bold and italic emphasis on the phrases that carry the meaning.
+- \`ticket-description\` — draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
 - \`split-overlarge-pr\` — split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
 
 ## When to Write
@@ -251,6 +259,14 @@ about their preferences:
 2. Use prediction_update to create, reinforce, or weaken a prediction
 3. Use prediction_delete to remove a prediction created in error
 
+Code review discussions are high-signal prediction material. When working
+through potential review comments with the user, watch for preferences about
+review threshold, severity, tone, evidence, scope, false positives, or what is
+worth posting. This applies whether the user invoked a review skill, is
+reviewing your changes, or asked you to review their changes or another LLM's
+changes. Before creating a new prediction, query for an existing one and
+reinforce or adjust it when possible.
+
 ## What to Store
 
 - **Global store**: user observations, agent personality, system environment
@@ -440,8 +456,8 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-session-reflection\` — record what you learned at end of session.
 - \`thatch-fact-extractor\` — extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
 - \`thatch-dedup-classifier\` — resolve duplicate memory pairs from \`find_duplicates\`.
-- \`pr-description\` — draft a PR description using instructional-design scaffolding with bold and italic emphasis on the phrases that carry the meaning, so a reviewer skimming only the emphasized fragments still gets the story.
-- \`ticket-description\` — draft a ticket, issue, or work item (Linear or Jira) using instructional-design scaffolding with bold and italic emphasis for scanning.
+- \`pr-description\` — draft a PR description with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, using bold and italic emphasis on the phrases that carry the meaning.
+- \`ticket-description\` — draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
 - \`split-overlarge-pr\` — split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
 
 ## When to Write
@@ -479,6 +495,14 @@ about their preferences:
 2. Use prediction_update to create, reinforce, or weaken a prediction
 3. Use prediction_delete to remove a prediction created in error
 
+Code review discussions are high-signal prediction material. When working
+through potential review comments with the user, watch for preferences about
+review threshold, severity, tone, evidence, scope, false positives, or what is
+worth posting. This applies whether the user invoked a review skill, is
+reviewing your changes, or asked you to review their changes or another LLM's
+changes. Before creating a new prediction, query for an existing one and
+reinforce or adjust it when possible.
+
 ## What to Store
 
 - **Global store**: user observations, agent personality, system environment