Rewrite as a raw idea dump, not a working skill

Previous version built one lens out to a real process, which wasn't
the ask — this replaces it with an uncut capture of every idea from
the design conversation (determinism hunting, CLAUDE.md->standards
migration, writing-for-agents branches applied to review, tool
economy off session JSONL, navigation pointers, codebase design,
the sub-agents-vs-single-skill question, multi-session mode,
propose-never-apply), explicitly marked not-functional and parked
for a /writing-for-agents pass later.

.changeset/retro-stub.md

@@ -0,0 +1,5 @@
+---
+"mattpocock-skills": patch
+---
+
+Add `retro` to `in-progress` as a non-functional stub: a raw capture of every idea from the design conversation (determinism hunting, CLAUDE.md→CODING_STANDARDS.md migration, writing-for-agents branch vocabulary applied to review, tool economy off session JSONL, navigation-pointer gaps, codebase-design lens, sub-agents-vs-single-skill architecture, multi-session mode, propose-never-apply). Not reduced to steps or pruned yet — parked for a future `/writing-for-agents` pass.

.changeset/wait-what-context-map.md

@@ -1,5 +0,0 @@
----
-"mattpocock-skills": patch
----
-
-wait-what: follow `CONTEXT-MAP.md` to the right `CONTEXT.md` when a repo indexes multiple contexts that way instead of keeping a single root `CONTEXT.md`.

docs/engineering/grill-with-docs.md

@@ -40,6 +40,12 @@ That third row is the one that catches people out. `CONTEXT.md` is a glossary an
 
 The glossary is the point. Domain language is the thing this skill is actually building — the project's own words, agreed once, so you, the agent and your colleagues stop paying to re-derive them. It is worth saying that not everyone agrees this buys you agent performance: the sharpest public pushback is that a term and its plain-English expansion get the same result from the [model](https://www.aihero.dev/ai-coding-dictionary/model), and that the vocabulary really compresses communication between the humans who share it. That reading still leaves the glossary valuable; it just moves the value.
 
+## It assumes one writer
+
+The stateful outputs assume a single person curating them. A two-developer team running four months in one repo reported state drift on roughly 20% of sampled merged PRs, with ADR citations and README claims the highest-drift surfaces — deliberate, human-curated docs drifted worse than agent memory did. Pruning the stale docs did not hold; the same sweep was stale again within days. What worked was deleting shadow state outright and adding a deterministic citation and link linter to CI.
+
+Related: running the skill repeatedly across unrelated changes in one repo tends to accumulate mixed-topic docs, because nothing separates one session's output from another's. Neither of these is fixed in the skill today.
+
 ## Common questions
 
 **Should I use this or `/wayfinder`?**

docs/productivity/wait-what.md

@@ -22,7 +22,7 @@ The skill says re-pitch **that**, not "that last message". What lost you is usua
 
 The body reuses the leading words already in your global `CLAUDE.md` and your project's `CONTEXT.md`. ASD-STE100 Simplified Technical English sets the register. The ubiquitous language supplies the nouns. The skill, `CLAUDE.md` and `CONTEXT.md` reach for the same [tokens](https://www.aihero.dev/ai-coding-dictionary/token), so invoking it is not a new instruction. It is a reminder of one the agent already agreed to.
 
-If you have no `CONTEXT.md` — and no `CONTEXT-MAP.md` pointing to one for the context at hand — the skill still works. You lose only the domain-vocabulary half.
+If you have no `CONTEXT.md`, the skill still works. You lose only the domain-vocabulary half.
 
 ## It's working if
 

skills/in-progress/README.md

@@ -14,3 +14,4 @@ npx skills@latest add mattpocock/skills --skill=<name>
 - **[writing-shape](./writing-shape/SKILL.md)** — Take a markdown file of raw material and shape it into an article paragraph by paragraph, arguing format choices at each step.
 - **[claude-handoff](./claude-handoff/SKILL.md)** — Hand the current conversation off to a fresh background agent that picks up the work immediately, seeded with a handoff summary via `claude --bg`. User-invoked.
 - **[setup-ts-deep-modules](./setup-ts-deep-modules/SKILL.md)** — Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files, tests exercising it through those. User-invoked.
+- **[retro](./retro/SKILL.md)** — Not functional. Raw design ideas for a retrospective skill — determinism hunting, steering-file hygiene, tool economy, navigation pointers, codebase design — parked for a future `/writing-for-agents` pass.

skills/in-progress/retro/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: retro
+description: STUB — not functional. Raw design ideas for a retrospective skill, awaiting a /writing-for-agents pass.
+disable-model-invocation: true
+---
+
+# Retro (stub)
+
+Not a working skill. This file is raw material for a future `/writing-for-agents` pass — every idea from the design conversation, uncut, none of it yet reduced to steps, reference, branches, or pruned for no-ops. Treat every section below as a candidate, not an instruction. Do not follow this file as a process.
+
+## Premise
+
+- Runs at the end of a conversation: a retrospective on how the conversation went.
+- The compound-engineering promise — the process improves over time — without compound engineering's failure mode: models are bad at improving their own behavior unsupervised. Whatever this becomes, it proposes; it never applies.
+- The opportunity: tie together four things this codebase already has, in one pass — steering files (`CLAUDE.md`/`AGENTS.md`), `CODING_STANDARDS.md`, the skills themselves, and the `writing-for-agents` discipline that governs how all three should be written.
+
+## Ideas to fold in — one per raw idea, uncut
+
+1. **Determinism hunt.** Somewhere in the session, the agent (or the user) made a judgment call that had to be made every time — a piece of reasoning repeated rather than automated. Flag these as their own category, distinct from `CODING_STANDARDS.md` prose: a determinism candidate isn't a rule to remember, it's a rule to stop needing — a lint rule, a script, a hook, a type, a tool.
+2. **CLAUDE.md → CODING_STANDARDS.md migration.** Steering instructions that have accreted in `CLAUDE.md` belong in `CODING_STANDARDS.md` instead. Retro should actively look for steering prose sitting in the wrong file and propose *moving* it, not just propose new rules.
+3. **Branches, from `writing-for-agents`.** Apply the branch vocabulary (a branch = a distinct case a document handles) to the documents retro touches. E.g. a "review branch": when reviewing a piece of code, name the distinct cases its behavior handles, and check the standards file covers each as its own branch rather than one blurred rule.
+4. **Tool economy.** Opinions on tool calls and tool setups: find tools that were expensive this session — many calls, high latency, high token cost, retries — by reading the actual session JSONL, not impressions, and propose cheaper tool setups.
+5. **Navigation pointers.** Look for hard-to-reach parts of the codebase this session struggled to find — places that needed a highway pointer in `CLAUDE.md`/`AGENTS.md` and didn't have one — and propose adding them.
+6. **Codebase design.** Apply the `codebase-design` deep-module/deletion-test vocabulary to flag shallow modules or deletion-test failures the session bumped into — same lens as `/improve-codebase-architecture`, but sourced from this session's actual friction rather than a cold scan.
+7. **Prune, not just add.** Any pass over `CODING_STANDARDS.md` should also run the deletion test against *existing* rules and propose removals — a retro that only adds becomes exactly the mess this idea exists to prevent.
+8. **Architecture — undecided, two competing shapes:**
+   - **One skill, several sub-agents** — each lens above (determinism, tool economy, navigation, codebase design, steering-file hygiene) runs as a parallel sub-agent, each pointed at its own reference doc living inside this skill's folder.
+   - **One skill, no sub-agents** — the conversation is already fully in context and there's no exploration needed for the single-session case, so just hand the one in-context agent a checklist of lenses and let it work through them directly. Sub-agents may only earn their keep for the multi-session case below, where transcripts genuinely aren't in context yet.
+9. **Multi-session mode.** Fan out sub-agents across several past transcripts in the same project before drawing conclusions, so one session's idiosyncrasy doesn't get promoted to a standing rule.
+10. **Never writes directly.** Whatever shape this takes, the output is a proposed diff on a branch, landed as a PR — never a direct commit to `CODING_STANDARDS.md`, `CLAUDE.md`, or anywhere else.
+
+## Reference material for the eventual write-up
+
+- `writing-for-agents` — branches, context pointers, information hierarchy, pruning/no-ops vocabulary. The tool this stub is meant to be fed through.
+- `codebase-design` — deletion test, deep module vocabulary, for idea 6.
+- `code-review` — precedent for the parallel-sub-agent, non-reranked aggregation shape, relevant to idea 8's first option.
+
+## Next step
+
+Run `/writing-for-agents` against this file: pick an information-hierarchy tier for each idea above (in-file step vs in-file reference vs disclosed reference), settle idea 8, and cut whatever turns out to be a no-op once the real process is written.

skills/in-progress/retro/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Retro (stub)"
+  short_description: "Not functional yet — design ideas only"
+policy:
+  allow_implicit_invocation: false

skills/productivity/wait-what/SKILL.md

@@ -4,4 +4,4 @@ description: Stop. That last message did not land — re-pitch it.
 disable-model-invocation: true
 ---
 
-Wait — I don't understand where you've got to here. Re-pitch that: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from `CONTEXT.md` (follow `CONTEXT-MAP.md` to the right one if the repo has more than one).
+Wait — I don't understand where you've got to here. Re-pitch that: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from `CONTEXT.md`.