chore: condense changesets and drop docs-only entries

Removes the five docs-page-only changesets (quickstart drop, grill-me pass, four-section spine, rewrite-to-standard, writing-for-agents pass) — the changelog reports on the shipped skills, not on the site pages. Merges the clusters that describe one change each: ask-matt routing, the grilling round-by-round rework, prototype, wayfinder, wizard and writing-for-agents. 27 changesets become 15. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-12 10:28:06 +07:00 · 2026-08-05 13:07:04 +01:00
parent c553e932f0
commit 77d207ef03
22 changed files with 55 additions and 143 deletions
@@ -1,13 +0,0 @@
 ---
 "mattpocock-skills": patch
 ---
 Give `/ask-matt` the **phase boundary** decision tree, replacing the two-bullet `Crossing sessions` section.
 A **phase** is a chunk of work inside a session — the grilling, the implementation, the QA — and the boundary between two of them is where you decide what to do with the context you've built. The router now carries all five options in order (**continue**, `/clear`, `/handoff`, **subagent**, `/compact`), with the ordered tree and its reasoning disclosed in a new `PHASE-BOUNDARIES.md`. Three fixes come with it:
 - **`/handoff` was oversold.** It read as the general bridge between context windows. It's narrow: you need it only when something has to *travel* — a new harness, a new directory, a colleague, or a side task forked mid-phase. What it buys is portability.
 - **`/compact` is the default, not the first reach.** It sits at the bottom of the tree, after the four cheaper or more precise questions above it. Starting there produces a session that's confidently wrong about whatever the summary flattened.
 - **Two branches were missing entirely.** **Continue** is the one to rule out first — it's the only move that keeps the conversation as a primary source rather than a summary of one — and a **subagent** handles anything scoped tightly enough to run AFK.
 Context hygiene's escape hatch now says `/compact` rather than `/handoff` (same harness, same directory, at a boundary — the handoff clause doesn't apply), and the smart zone figure is updated from ~120k to ~150k tokens.
@@ -0,0 +1,20 @@
 ---
 "mattpocock-skills": patch
 ---
 Sharpen `/ask-matt` — the router now covers phase boundaries, the two wayfinder mistakes, and two skills it never mentioned.
 **Phase boundaries.** A **phase** is a chunk of work inside a session — the grilling, the implementation, the QA — and the boundary between two of them is where you decide what to do with the context you've built. The two-bullet `Crossing sessions` section is replaced by a decision tree carrying all five options in order (**continue**, `/clear`, `/handoff`, **subagent**, `/compact`), with the reasoning disclosed in a new `PHASE-BOUNDARIES.md`. Three fixes come with it:
 - **`/handoff` was oversold.** It read as the general bridge between context windows. It's narrow: you need it only when something has to *travel* — a new harness, a new directory, a colleague, or a side task forked mid-phase. What it buys is portability.
 - **`/compact` is the default, not the first reach.** It sits at the bottom of the tree, after the four cheaper or more precise questions above it. Starting there produces a session that's confidently wrong about whatever the summary flattened.
 - **Two branches were missing entirely.** **Continue** is the one to rule out first — it's the only move that keeps the conversation as a primary source rather than a summary of one — and a **subagent** handles anything scoped tightly enough to run AFK.
 Context hygiene's escape hatch now says `/compact` rather than `/handoff` (same harness, same directory, at a boundary — the handoff clause doesn't apply), and the smart zone figure is updated from ~120k to ~150k tokens.
 **Wayfinder routing.** The two mistakes people most often make with the heaviest, most cognitively demanding flow:
 - **Over-reaching for it.** It's slower and denser than a single grill, so it's flagged as the heaviest flow and reserved for the idea that genuinely won't fit one session — a well-scoped feature belongs on `/grill-with-docs`, not here.
 - **Losing the way at the handoff.** When the map clears, wayfinder hands off, it doesn't build: merge onto the main flow at `/to-spec` (which collapses the map's linked decisions into a buildable plan) rather than looping the map straight into `/implement`. Straight-to-`/implement` is only for efforts that turned out genuinely small.
 **Missing routes.** `/grilling` and `/resolving-merge-conflicts` were absent from the router altogether and are now in it, and `grill-me` splits from `grill-with-docs` on whether you are in a working directory.
@@ -1,10 +0,0 @@
 ---
 "mattpocock-skills": patch
 ---
 Make `/ask-matt` clued-up about `/wayfinder` — the heaviest, most cognitively demanding flow.
 The router now sharpens the two routing mistakes people most often make with wayfinder:
 - **Over-reaching for it.** It's slower and denser than a single grill, so it's flagged as the heaviest flow and reserved for the idea that genuinely won't fit one session — a well-scoped feature belongs on `/grill-with-docs`, not here.
 - **Losing the way at the handoff.** When the map clears, wayfinder hands off, it doesn't build: merge onto the main flow at `/to-spec` (which collapses the map's linked decisions into a buildable plan) rather than looping the map straight into `/implement`. Straight-to-`/implement` is only for efforts that turned out genuinely small.
@@ -1,11 +0,0 @@
 ---
 "mattpocock-skills": patch
 ---
 Drop the hand-written Quickstart block from all 25 docs pages.
 aihero.dev already renders an install widget above every skill page — a copy button, the single-skill command, the whole-set command, and the update line. Each page then wrote the same two commands out again immediately below it. The reader saw the install command twice.
 The two copies had also drifted apart. The widget renders the current `npx skills@latest …` wording; the hand-written blocks still carried the older bare `npx skills …`, so most pages showed the correct command and a stale one, one after the other.
 Deleting the block removes those stale copies and leaves the site's own. `.agents/writing-docs.md` now states the rule directly — install wording is a property of the site, not of the page — and its template no longer carries a Quickstart to copy.
@@ -1,17 +0,0 @@
 ---
 "mattpocock-skills": patch
 ---
 Rewrite the `grill-me` docs page around what people actually get wrong.
 The old page explained the mechanism — rounds, the frontier, the decision tree — and stopped there. Every recurring question from the last few months went unanswered on it: which of the three grilling skills to reach for, how many questions is normal, what to do when a question can't be answered by talking, and whether to start a fresh session before writing the spec.
 The rewrite keeps the mechanism short and spends the page on the judgement calls instead:
 - **Sibling routing** is now a three-way list keyed on what you have in front of you — no codebase, a codebase, or too big for one session — rather than a paragraph.
 - **"It's a conversation, not an interview"** names passivity as the main failure mode. A session where you answer "agreed" forty times produces a plan you didn't write and can't defend.
 - **"Grillable and ungrillable"** gives readers the move for a question that talking cannot settle: stop, prototype, come back. This is where long sessions come from.
 - **A "Common questions" section** answers the six highest-volume ones directly, including how to restore one-question-at-a-time and why you should not clear context before `to-spec`.
 - **"It's working if"** added, led by the sharpest signal: if you never disagreed, you didn't need the session.
 Also drops the "plan mode" ambiguity by saying plainly to leave it off.
@@ -1,15 +0,0 @@
 ---
 "mattpocock-skills": patch
 ---
 Make `Common questions` and `It's working if` part of the docs-page standard, and say where the questions come from.
 An audit of all 25 docs pages found the two sections that carry the most weight are the two the standard treated as optional. Only `grill-me` has a `Common questions` section; `writing-for-agents` gains one in #758. Twelve pages have no `It's working if` at all, and several that do use it for compliance checks on the skill's internals rather than for signals the reader can see.
 `.agents/writing-docs.md` now:
 - **Names the four-section spine** — `What it does`, `When to reach for it`, `Common questions`, `It's working if`. A page missing the last two is unfinished, not finished-and-short. The template's order is now the page's order.
 - **Gates `Common questions` on evidence.** Every question has to be one someone asked, and three observed questions beat eight plausible ones. The hunt runs over three sources: the personal wiki at `~/repos/matt/personal-wiki` where it exists on the machine (its `wiki/audience/` area is organised around what the audience is confused by, with `sources:` linkbacks to the original threads), this repo's issues, and `CHANGELOG.md` for anything renamed or moved.
 - **Raises the bar on `It's working if`** — each bullet must be checkable without opening `SKILL.md`.
 `CLAUDE.md` names the four sections in the pointer, so the spine is visible without reading `writing-docs.md` first.
@@ -1,7 +0,0 @@
 ---
 "mattpocock-skills": patch
 ---
 Rewrite every human-facing docs page to the four-section standard. Each page now states the skill's defining constraint, says when to reach for it and when to reach for something else, answers the questions people actually ask, and names what you see when it is working. The questions were found rather than invented — in the issue tracker, in the community threads, and in the changesets — so a well-discussed skill like `wayfinder` carries ten and a quiet one like `resolving-merge-conflicts` carries three.
 Writing them surfaced claims elsewhere that were no longer true. `tdd` now points at `/codebase-design` for interface vocabulary, which the v1.0 changelog said had already happened but which was never wired up. `ask-matt` gains `/grilling` and `/resolving-merge-conflicts`, both previously missing from the router altogether, and splits `grill-me` from `grill-with-docs` on whether you are in a working directory. The READMEs stop calling wayfinder's map one of investigation tickets, stop dropping the first phase from the `diagnosing-bugs` loop, and stop promising that `improve-codebase-architecture` will rescue a ball of mud when what it does is survey one.
@@ -1,15 +0,0 @@
 ---
 "mattpocock-skills": patch
 ---
 Rewrite the `writing-for-agents` docs page around what people actually get wrong.
 The old page was a table of contents for the skill: the two loads, then a bullet per lever. It answered none of the questions the rename and the AMA threads have been generating for months — where `writing-great-skills` went, whether the agent or the human is doing the writing, why you shouldn't just ask Claude to write the skill for you, and how you know when a document is done.
 The rewrite keeps the levers to one compact list and spends the page on the judgement calls instead:
 - **The defining constraint is now stated up front** — the default move is deletion, not explanation, because the reader has already read everything. This is also the answer to "why not let the model write it", so it leads.
 - **The scope is stated as a test**, not a list: does an agent read this document and act? Skills, `AGENTS.md`, specs, tickets and runtime prompts all pass it.
 - **A "Common questions" section** answers the nine highest-volume ones directly, including the rename, the "streamline" failure where an agent trims for length and cuts behaviour, whether to rewrite documents per model, the skill that only works on the one task it was built from, and the leading-word question from non-native English speakers.
 - **"It's working if"** added, led by the sharpest signal: the document gets shorter as it gets better, and duplication is the most reliable sign it was never tested.
 - **`Where it fits`** says plainly that it has no chain neighbour: it sits underneath the set rather than beside one skill, and the documents the other skills leave behind are the text it governs.
@@ -2,10 +2,12 @@
 "mattpocock-skills": minor
 ---
-Graduate **`wizard`** out of `in-progress/` into the **Engineering** bucket, so it ships in the plugin. It generates an interactive bash script that walks a human through a manual procedure — third-party setup, a one-off migration, an A→B state transition — opening each URL, saying what to click, capturing the values, and writing them into `.env` files and GitHub Actions secrets.
+Graduate **`wizard`** out of `in-progress/` into the **Engineering** bucket, so it ships in the plugin — and make it model-invoked. It generates an interactive bash script that walks a human through a manual procedure — third-party setup, a one-off migration, an A→B state transition — opening each URL, saying what to click, capturing the values, and writing them into `.env` files and GitHub Actions secrets.
 The delightful UX is pre-solved by the bundled `template.sh` (progress with time-remaining, confirmation gates, cross-platform URL opening including WSL, hidden secret entry, idempotent `.env` upserts, `gh secret`/`gh variable` writes with graceful degradation, closing skip summary). Everything above the `STAGES` marker is a fixed library that's never hand-edited — the skill's job is only to scope the procedure and author its **stages**.
 Engineering rather than Productivity: it reads `.env*`, `docker-compose*`, framework config and every `secrets.*`/`vars.*` reference in `.github/workflows/` to scope itself, writes CI secrets, and verifies its output with `bash -n` and `shellcheck`.
-Now wired as a promoted skill — plugin entry, top-level + Engineering READMEs under **Model-invoked**, a docs page at `docs/engineering/wizard.md`, and a Standalone route in `ask-matt` for the steps only a human can take.
+Because it is model-invoked, the agent can reach for it the moment it hits a step only a human can perform, instead of dumping numbered instructions into the chat and hoping you follow them. Typing `/wizard` works exactly as before — model-invocation only ever *adds* the agent's reach. The description is written as the pointer that decides when it fires: what it produces, four trigger branches (provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, a one-off migration or cutover), and an explicit non-trigger — don't invoke it for steps the agent can perform itself. Work an agent can do, an agent should do; the wizard is for the clicks, approvals and dashboard trips you would not hand to one. The stage-list confirmation before a line is written now doubles as the proposal when the agent fires it mid-build.
 Now wired as a promoted skill — plugin entry, top-level + Engineering READMEs under **Model-invoked**, a docs page at `docs/engineering/wizard.md`, and a Standalone route in `ask-matt` for the steps only a human can take. Model-invocation also puts it out of the reach of [#693](https://github.com/mattpocock/skills/issues/693), which drops user-invoked skills from the listing on Claude's desktop and web surfaces.
@@ -1,5 +0,0 @@
 ---
 "mattpocock-skills": patch
 ---
 Pin the question format in **`grilling`**. Every question in a round is now emitted in one fixed shape — `❓ **Q1** - **<title>**`, then the body (prose or multiple choices), then the recommendation on its own `➡️` line. A round reads as a scannable numbered list with each recommendation visually separated from the question, so you can answer by number instead of quoting questions back.
@@ -3,3 +3,7 @@
 ---
 Rework **`grilling`** from one-question-at-a-time to round-by-round. It now maps the decision tree and asks the whole **frontier** — every question whose prerequisites are already settled — in a single numbered round, then recomputes the frontier from the user's answers and asks the next round. Same 13 questions land in ~3 rounds instead of 13. Facts the environment can answer are dispatched to background sub-agents so research never blocks the round: only questions downstream of a running exploration wait for it. The session ends when the frontier is empty.
 Every question in a round is emitted in one fixed shape — `❓ **Q1** - **<title>**`, then the body (prose or multiple choices), then the recommendation on its own `➡️` line. A round reads as a scannable numbered list with each recommendation visually separated from the question, so you can answer by number instead of quoting questions back.
 `grill-me`, `grill-with-docs` and `triage` run the frontier a round at a time as well — `triage`'s grill step and `grilling`'s Codex `short_description` now say so instead of describing the old rhythm. The opt-out for one-question-at-a-time (a line in your global `CLAUDE.md`) is unchanged.
@@ -1,5 +0,0 @@
 ---
 "mattpocock-skills": patch
 ---
 Sync the skills and docs that still described grilling as a **one-question-at-a-time** interview. Since the round-by-round rework, `grill-me`, `grill-with-docs` and `triage` all run the frontier a round at a time — their pages, `triage`'s grill step and `grilling`'s Codex `short_description` now say so. The opt-out for the old rhythm (a line in your global `CLAUDE.md`) is unchanged.
@@ -1,5 +0,0 @@
 ---
 "mattpocock-skills": minor
 ---
 Reshape the **`prototype`** skill's logic branch to produce a **single shareable HTML file** instead of a terminal app. The demo is one self-contained file (plain HTML/CSS/JS, no build, no server) a non-developer can open by double-click and drive in their own domain language: a labelled state panel, always-available free-play buttons, and a set of tabbed **guided walkthroughs** — each a scenario with the ordered buttons to press underneath it. The portable pure-logic module still lifts into the real code; the HTML shell is the throwaway primary source.
@@ -1,5 +0,0 @@
 ---
 "mattpocock-skills": minor
 ---
 Reword how the **`prototype`** skill handles its artifacts around a single idea: **the prototype is a primary source**. Rather than being deleted once it's answered its question, the prototype is captured as runnable evidence on a throwaway branch (`prototype/<name>`) out of main, with a context pointer to it left on the implementation issue — so the main branch keeps only the validated decision while the exploration stays findable. The answer (verdict + question) is still captured durably in an issue/ADR/commit.
@@ -0,0 +1,9 @@
 ---
 "mattpocock-skills": minor
 ---
 Reshape the **`prototype`** skill around two ideas: the demo is **a single shareable HTML file**, and the prototype is **a primary source**.
 The logic branch now produces one self-contained file (plain HTML/CSS/JS, no build, no server) instead of a terminal app — a non-developer can open it by double-click and drive it in their own domain language: a labelled state panel, always-available free-play buttons, and a set of tabbed **guided walkthroughs**, each a scenario with the ordered buttons to press underneath it. The portable pure-logic module still lifts into the real code; the HTML shell is the throwaway.
 Throwaway no longer means deleted. Rather than being removed once it has answered its question, the prototype is captured as runnable evidence on a throwaway branch (`prototype/<name>`) out of main, with a context pointer to it left on the implementation issue — so the main branch keeps only the validated decision while the exploration stays findable. The answer (verdict + question) is still captured durably in an issue/ADR/commit.
@@ -0,0 +1,9 @@
 ---
 "mattpocock-skills": minor
 ---
 Name the `/wayfinder` unit a **decision ticket**, and burn research tickets down with subagents.
 People kept reading a wayfinder ticket as an ordinary *implementation* ticket — a slice of a build to execute — when wayfinder uses them as **decision tickets**: questions whose resolution is a decision. The skill description and its opening line now introduce the term (and say what makes it one), with the `ask-matt` / engineering README blurbs and the docs page matching — while "ticket" stays the everyday word once the term is established. `CONTEXT.md` records **Decision ticket** as a domain term, so the "avoid: ticket" guidance no longer contradicts wayfinder's deliberate use of the word.
 Research tickets are no longer parked for a separately-launched session. Research stays a real ticket type — it's a genuine shared blocker that downstream decisions hang on, and that dependency is exactly what the frontier's blocking edges exist to render. What changes is how it's resolved: because research is AFK, charting doesn't stop and read it. After creating the tickets, the charting session fires a `/research` subagent for each research ticket to burn it down in parallel, capturing the findings on a throwaway `research/<name>` branch with a context pointer. Research tickets are the one exception to *one ticket per session*.
@@ -1,7 +0,0 @@
 ---
 "mattpocock-skills": patch
 ---
 Name the `/wayfinder` unit a **decision ticket**.
 People kept reading a wayfinder ticket as an ordinary *implementation* ticket — a slice of a build to execute — when wayfinder uses them as **decision tickets**: questions whose resolution is a decision. The skill description and its opening line now introduce "decision ticket" (and say what makes it one), and the `ask-matt` / engineering README wayfinder blurbs and the docs page match — while "ticket" stays the everyday word once the term is established. `CONTEXT.md` records **Decision ticket** as a domain term so the "avoid: ticket" guidance no longer contradicts wayfinder's deliberate use of the word.
@@ -1,7 +0,0 @@
 ---
 "mattpocock-skills": minor
 ---
 Wayfinder now burns research tickets down with subagents instead of leaving them parked for a separately-launched session.
 Research stays a real ticket type — it's a genuine shared blocker that downstream decisions hang on, and that dependency is exactly what the frontier's blocking edges exist to render. What changes is how it's resolved: because research is AFK, charting doesn't stop and read it. After creating the tickets, the charting session fires a `/research` subagent for each research ticket to burn it down in parallel, capturing the findings on a throwaway `research/<name>` branch with a context pointer. Research tickets are the one exception to *one ticket per session*.
@@ -1,9 +0,0 @@
 ---
 "mattpocock-skills": minor
 ---
 Make **`wizard`** model-invoked. The agent can now reach for it the moment it hits a step only a human can perform, instead of dumping numbered instructions into the chat and hoping you follow them. Typing `/wizard` works exactly as before — model-invocation only ever *adds* the agent's reach.
 The description is rewritten as the pointer that decides when it fires: a short statement of what it produces, four trigger branches (provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, a one-off migration or cutover), and an explicit non-trigger — don't invoke it for steps the agent can perform itself. Work an agent can do, an agent should do; the wizard is for the clicks, approvals and dashboard trips you would not hand to one.
 Nothing else changed. Same name, same `template.sh`, same four process steps, same stage-list confirmation before a line is written — which now doubles as the proposal when the agent fires it mid-build. Also moved to **Model-invoked** in both READMEs, and out of the reach of [#693](https://github.com/mattpocock/skills/issues/693), which drops user-invoked skills from the listing on Claude's desktop and web surfaces.
@@ -1,5 +0,0 @@
 ---
 "mattpocock-skills": minor
 ---
 Extend **`writing-for-agents`**' pruning section with a new leading word: **cache**. Single source of truth now reaches past the document into the environment — `package.json` scripts, config files, directory layout, `--help` output are themselves authoritative, so a doc that restates them is a cache of a lookup, earning its load only when the lookup is expensive. The positive target: cache what the agent cannot find by looking (unwritten conventions, the reason behind a choice, gotchas no config confesses), and leave one-file, one-command lookups to the environment, where they cannot go stale.
@@ -1,5 +0,0 @@
 ---
 "mattpocock-skills": minor
 ---
 **Breaking:** rename **`writing-great-skills`** → **`writing-for-agents`** and restructure it. The reference now covers any document an agent consumes — skills, `AGENTS.md` / `CLAUDE.md`, docs reached by a pointer — not just skills. `GLOSSARY.md` is merged into `SKILL.md` (one authoritative treatment per term; the `_Avoid_` synonym lists and the standalone Predictability definition are gone); the skill-only mechanics (frontmatter, model- vs user-invoked, router skills, the invocation cut of splitting) are disclosed to a new `SKILL-MECHANICS.md`. The skill is now **model-invoked**: it fires when creating or editing skills or modifying `AGENTS.md`/`CLAUDE.md`. `ask-matt`'s pointer updated. Reinstall under the new name; the old name is gone (no alias).
@@ -0,0 +1,9 @@
 ---
 "mattpocock-skills": minor
 ---
 **Breaking:** rename **`writing-great-skills`** → **`writing-for-agents`**, restructure it, and add a new leading word.
 The reference now covers any document an agent consumes — skills, `AGENTS.md` / `CLAUDE.md`, docs reached by a pointer — not just skills. `GLOSSARY.md` is merged into `SKILL.md` (one authoritative treatment per term; the `_Avoid_` synonym lists and the standalone Predictability definition are gone); the skill-only mechanics (frontmatter, model- vs user-invoked, router skills, the invocation cut of splitting) are disclosed to a new `SKILL-MECHANICS.md`. The skill is now **model-invoked**: it fires when creating or editing skills or modifying `AGENTS.md`/`CLAUDE.md`. `ask-matt`'s pointer updated. Reinstall under the new name; the old name is gone (no alias).
 The pruning section gains **cache**. Single source of truth now reaches past the document into the environment — `package.json` scripts, config files, directory layout, `--help` output are themselves authoritative, so a doc that restates them is a cache of a lookup, earning its load only when the lookup is expensive. The positive target: cache what the agent cannot find by looking (unwritten conventions, the reason behind a choice, gotchas no config confesses), and leave one-file, one-command lookups to the environment, where they cannot go stale.