From 93f73198e3588c1844733b67feaffa5b58812ff3 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 1 Jul 2026 16:30:16 +0100 Subject: [PATCH 1/8] feat(to-plan): add sequential plan skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a user-invoked `to-plan` skill — the sequential, HITL sibling of `to-issues`. Both slice work into tracer-bullet vertical slices, but `to-plan` produces one ordered sequence you drive by hand, one phase per fresh context, rather than parallel independently-grabbable issues. It publishes to the tracker `/setup-matt-pocock-skills` configured, shaped to it: a single sequential `plan.md` for a local tracker, or a parent issue with ordered sub-issues (native sub-issues where supported) for a real one. Registers the skill everywhere CLAUDE.md requires (plugin.json, top-level and bucket READMEs, docs page), updates the `ask-matt` router's main-flow fork to offer both to-issues and to-plan, and adds a changeset. Co-Authored-By: Claude Opus 4.8 (1M context) --- .changeset/to-plan-skill.md | 5 ++ .claude-plugin/plugin.json | 1 + README.md | 1 + docs/engineering/to-plan.md | 53 +++++++++++++ skills/engineering/README.md | 1 + skills/engineering/ask-matt/SKILL.md | 4 +- skills/engineering/to-plan/SKILL.md | 112 +++++++++++++++++++++++++++ 7 files changed, 176 insertions(+), 1 deletion(-) create mode 100644 .changeset/to-plan-skill.md create mode 100644 docs/engineering/to-plan.md create mode 100644 skills/engineering/to-plan/SKILL.md diff --git a/.changeset/to-plan-skill.md b/.changeset/to-plan-skill.md new file mode 100644 index 0000000..5fc5609 --- /dev/null +++ b/.changeset/to-plan-skill.md @@ -0,0 +1,5 @@ +--- +"mattpocock-skills": minor +--- + +Add a new user-invoked **`to-plan`** skill to the `engineering/` bucket — the sequential, HITL sibling of **`to-issues`**. Both slice work into tracer-bullet vertical slices, but where `to-issues` produces independently-grabbable issues for parallel agents, `to-plan` produces one ordered sequence you drive by hand, one phase per fresh context. It publishes to the tracker `/setup-matt-pocock-skills` configured, shaped to it: a single sequential `plan.md` for a local tracker, or a parent issue with ordered sub-issues (native sub-issues where the platform supports them) for a real one. The `to-*` fork in `ask-matt`'s main flow now offers both, and there's a human-facing docs page at `docs/engineering/to-plan.md`. diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 1255e60..8ec7f2c 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -9,6 +9,7 @@ "./skills/engineering/setup-matt-pocock-skills", "./skills/engineering/tdd", "./skills/engineering/to-issues", + "./skills/engineering/to-plan", "./skills/engineering/to-prd", "./skills/engineering/implement", "./skills/engineering/prototype", diff --git a/README.md b/README.md index fe6a0ec..0caeecb 100644 --- a/README.md +++ b/README.md @@ -155,6 +155,7 @@ Skills I use daily for code work. - **[improve-codebase-architecture](./skills/engineering/improve-codebase-architecture/SKILL.md)** — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. - **[setup-matt-pocock-skills](./skills/engineering/setup-matt-pocock-skills/SKILL.md)** — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo before using the other engineering skills. - **[to-issues](./skills/engineering/to-issues/SKILL.md)** — Break any plan, spec, or PRD into independently-grabbable issues using vertical slices. +- **[to-plan](./skills/engineering/to-plan/SKILL.md)** — Turn any plan, spec, or PRD into a sequential set of tracer-bullet phases worked one at a time — a single ordered file for a local tracker, or parent-and-sub-issues for a real one. - **[to-prd](./skills/engineering/to-prd/SKILL.md)** — Turn the current conversation into a PRD and publish it to the issue tracker. No interview — just synthesizes what you've already discussed. **Model-invoked** diff --git a/docs/engineering/to-plan.md b/docs/engineering/to-plan.md new file mode 100644 index 0000000..b797426 --- /dev/null +++ b/docs/engineering/to-plan.md @@ -0,0 +1,53 @@ +Quickstart: + +```bash +npx skills add mattpocock/skills --skill=to-plan +``` + +```bash +npx skills update to-plan +``` + +[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/to-plan) + +## What it does + +`to-plan` turns a PRD, spec, or the current conversation into a **sequential** plan — an ordered list of phases you work through one at a time, in a fresh context per phase. + +Every phase is a **tracer bullet** — a thin *vertical* slice that cuts through all integration layers end-to-end (schema, API, UI, tests), never a horizontal slice of one layer. A completed slice is demoable or verifiable on its own, and is sized to fit a single fresh context window. + +## When to reach for it + +You invoke this by typing `/to-plan` — the agent won't reach for it on its own. + +Reach for it once you have an agreed plan or a written spec and you want it turned into a sequence of phases you'll build **by hand, one at a time**. Point it at the conversation, or pass a PRD or issue reference and it reads that first. If the change hasn't been written up as a spec yet, produce one first — for that, use [to-prd](https://aihero.dev/skills-to-prd). + +## Sequential, not parallel + +`to-plan` is the sequential, HITL sibling of [to-issues](https://aihero.dev/skills-to-issues). Both slice work into tracer bullets, but they're for different workflows: + +- **`to-issues`** produces *independently-grabbable* issues, so parallel agents can pick them up at once (it applies the ready-for-agent label). +- **`to-plan`** produces one *ordered sequence* you drive yourself, phase by phase, staying in the loop — no ready-for-agent label. + +## Publishes to your configured tracker + +Like the other skills, `to-plan` publishes through the tracker [setup-matt-pocock-skills](https://aihero.dev/skills-setup-matt-pocock-skills) configured, and it adapts the shape to that tracker: + +- **Local files** → a single sequential `plan.md` in the repo root, all phases in order. +- **A real issue tracker (GitHub, Linear)** → a parent issue for the whole plan, with one sub-issue per phase, in order — using the platform's native sub-issue relationship where it has one, otherwise sequential issues each blocked by the previous. + +## Vertical slices, not horizontal ones + +The whole skill turns on one distinction. A **horizontal** slice ships one layer of the change — all the schema, or all the API — and nothing works until every layer lands. A **vertical** slice, the tracer bullet, ships one narrow path through *every* layer at once, so it can be demoed the moment it's done. + +Before slicing, `to-plan` looks for prefactoring — "make the change easy, then make the easy change" — and orders that work first. It then quizzes you on the breakdown (granularity, ordering, what to merge or split) before publishing anything. + +## Where it fits + +`to-plan` is the sequential branch of the main build chain: + +```txt +grill-with-docs → to-prd → to-plan → implement → code-review +``` + +It sits between [to-prd](https://aihero.dev/skills-to-prd), which hands it a settled spec to slice against, and [implement](https://aihero.dev/skills-implement), which builds each phase, driving [tdd](https://aihero.dev/skills-tdd) internally to write the tests test-first, before its [code-review](https://aihero.dev/skills-code-review) pass. Work one phase per fresh context, clearing between them. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/skills/engineering/README.md b/skills/engineering/README.md index 2c123f4..706478b 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -12,6 +12,7 @@ Reachable only when you type them (`disable-model-invocation: true`). - **[improve-codebase-architecture](./improve-codebase-architecture/SKILL.md)** — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. - **[setup-matt-pocock-skills](./setup-matt-pocock-skills/SKILL.md)** — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo. - **[to-issues](./to-issues/SKILL.md)** — Break any plan, spec, or PRD into independently-grabbable issues using vertical slices. +- **[to-plan](./to-plan/SKILL.md)** — Turn any plan, spec, or PRD into a sequential set of tracer-bullet phases worked one at a time — a single ordered file for a local tracker, or parent-and-sub-issues for a real one. - **[to-prd](./to-prd/SKILL.md)** — Turn the current conversation into a PRD and publish it to the issue tracker. ## Model-invoked diff --git a/skills/engineering/ask-matt/SKILL.md b/skills/engineering/ask-matt/SKILL.md index f19a17c..bb3a514 100644 --- a/skills/engineering/ask-matt/SKILL.md +++ b/skills/engineering/ask-matt/SKILL.md @@ -20,7 +20,9 @@ The route most work travels. You have an idea and want it built. - **`/prototype`** to answer the question with throwaway code, - **`/handoff`** back what you learned, and reference it from the original idea thread. 3. **Branch — is this a multi-session build?** - - **Yes** → **`/to-prd`** (turn the thread into a PRD) → **`/to-issues`** (split the PRD into independently-grabbable issues). Because the issues are independent, **clear context between each one**: start a fresh session per issue and kick off **`/implement`** by passing it the PRD and the single issue to work on. + - **Yes** → **`/to-prd`** (turn the thread into a PRD), then split it into tracer-bullet slices one of two ways: + - **`/to-issues`** — independently-grabbable issues on your tracker, for **parallel/AFK** agents. Because the issues are independent, **clear context between each one** and kick off **`/implement`** per issue. + - **`/to-plan`** — a **sequential** plan you drive **by hand**, staying in the loop. Publishes to the same tracker, shaped to it: a single ordered `plan.md` for a local tracker, or a parent issue with ordered sub-issues for a real one. Work one phase per fresh context, clearing between them, with **`/implement`**. - **No** → **`/implement`** right here, in the same context window. Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point. diff --git a/skills/engineering/to-plan/SKILL.md b/skills/engineering/to-plan/SKILL.md new file mode 100644 index 0000000..d1baf0a --- /dev/null +++ b/skills/engineering/to-plan/SKILL.md @@ -0,0 +1,112 @@ +--- +name: to-plan +description: Turn a PRD, spec, or the current conversation into a sequential plan of tracer-bullet vertical slices, published to the configured tracker — one ordered file for local, or parent-and-sub-issues for a real tracker. +disable-model-invocation: true +--- + +# To Plan + +Turn a plan, spec, or PRD into a **sequential** plan of vertical slices (tracer bullets) — an ordered list of phases you work through one at a time, in a fresh context per phase. + +This is the sequential, HITL sibling of `/to-issues`. Where `to-issues` produces independently-grabbable issues for parallel agents, `to-plan` produces one ordered sequence you drive by hand, top to bottom. + +The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not. + +## Process + +### 1. Gather context + +Work from whatever is already in the conversation context. If the user passes a reference (a PRD path, an issue number or URL) as an argument, fetch it and read its full body. + +### 2. Explore the codebase (optional) + +If you have not already explored the codebase, do so to understand the current state of the code. Phase titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching. + +Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change." + +### 3. Draft vertical slices + +Break the work into **tracer bullet** phases. Each phase is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer. + + + +- Each slice delivers a narrow but COMPLETE path through every layer (schema, API, UI, tests) +- A completed slice is demoable or verifiable on its own +- Each slice is sized to fit in a single fresh context window +- Any prefactoring should be done first + + + +Order the phases **sequentially**, in dependency order — each phase builds on the ones before it. There is no parallelism: a plain top-to-bottom sequence. + +### 4. Quiz the user + +Present the proposed breakdown as a numbered list. For each phase, show: + +- **Title**: short descriptive name +- **What it delivers**: the end-to-end behaviour this phase makes work + +Ask the user: + +- Does the granularity feel right? (too coarse / too fine) +- Is the ordering correct — does each phase build on the ones before it? +- Should any phases be merged or split further? + +Iterate until the user approves the breakdown. + +### 5. Publish the plan to the configured tracker + +Publish the approved phases in order. **How** depends on the tracker `/setup-matt-pocock-skills` configured: + +- **Local files** → write one sequential `plan.md` in the repo root, all phases in order, using the file template below. +- **A real issue tracker (GitHub, Linear, …)** → create **one parent issue** for the whole plan, then **one sub-issue per phase, in order**. Use the platform's native sub-issue / child-issue relationship if it supports one; otherwise create sequential issues and set each phase's "Blocked by" to the previous phase. Use the issue template below for the parent and each phase. + +These are worked **sequentially by hand**, not handed to parallel agents, so do NOT apply the ready-for-agent triage label. + + + +# Plan: + +A one-line summary of what this plan builds. Reference the source PRD or spec if there is one. + +## Phases + +Each phase is one tracer bullet — a vertical slice worked in a fresh context, top to bottom. + +### 1. + +**Delivers:** the end-to-end behaviour this phase makes work, from the user's perspective — not a layer-by-layer implementation list. + +- [ ] Acceptance criterion 1 +- [ ] Acceptance criterion 2 + +### 2. + +... + + + + + +**Parent issue** — title: the plan's short name. Body: the one-line summary, a reference to the source PRD/spec, and the ordered list of phase titles. + +**Each phase sub-issue:** + +## What to build + +The end-to-end behaviour this phase makes work, from the user's perspective — not layer-by-layer implementation. + +## Acceptance criteria + +- [ ] Criterion 1 +- [ ] Criterion 2 + +## Blocked by + +The previous phase (omit for the first phase). + + + +In either form, avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits. + +Work the plan one phase at a time with `/implement`, clearing context between phases. From c5a4a8c2e966e28628f56d1bfef07f401d399df0 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 1 Jul 2026 16:47:28 +0100 Subject: [PATCH 2/8] refactor(to-plan,to-issues): prune no-ops in vertical-slice framing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fold the redundant 'thin vertical slice cuts through all layers, NOT horizontal' intro sentence into vertical-slice-rules bullet 1 (it was duplicating the bullet), and cut to-plan's 'no parallelism / top-to-bottom' restatement — 'sequential' is already anchored as the leading word. Keeps the shared core identical across the two sibling skills. Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/engineering/to-plan/SKILL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/engineering/to-plan/SKILL.md b/skills/engineering/to-plan/SKILL.md index d1baf0a..7e0c1cb 100644 --- a/skills/engineering/to-plan/SKILL.md +++ b/skills/engineering/to-plan/SKILL.md @@ -26,18 +26,18 @@ Look for opportunities to prefactor the code to make the implementation easier. ### 3. Draft vertical slices -Break the work into **tracer bullet** phases. Each phase is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer. +Break the work into **tracer bullet** phases. -- Each slice delivers a narrow but COMPLETE path through every layer (schema, API, UI, tests) +- Each slice cuts a narrow but COMPLETE path through every layer (schema, API, UI, tests) — vertical, NOT a horizontal slice of one layer - A completed slice is demoable or verifiable on its own - Each slice is sized to fit in a single fresh context window - Any prefactoring should be done first -Order the phases **sequentially**, in dependency order — each phase builds on the ones before it. There is no parallelism: a plain top-to-bottom sequence. +Order the phases in dependency order — each builds on the ones before it. ### 4. Quiz the user From 386d4ff719a7c420ad1454232d0436b01f1b8c17 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Thu, 2 Jul 2026 10:53:40 +0100 Subject: [PATCH 3/8] refactor: unify planning skills into /to-spec + /to-tickets MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Executes the `unify-to-tickets` decision (personal-wiki #23), reworking this PR from "add /to-plan" into the full planning-skills unification. - Rename /to-prd → /to-spec. "spec" is now the single through-line term (the skill still opens with "you may know this document as a PRD" for discoverability). - Merge /to-plan + /to-issues into one /to-tickets skill; delete /to-issues. /to-tickets emits a set of tickets, each declaring its blocking edges — one medium-agnostic artifact that reads as a sequential plan (local `tickets.md`, edges as text) or a parallelizable DAG (real tracker, native blocking links). The edges live in the ticket either way; the medium only decides whether anything acts on them in parallel. - ask-matt now routes idea → /to-spec → /to-tickets → /implement. - Sweep every cross-reference (docs pages, chain diagrams, CONTEXT.md, ADRs, .agents, setup templates) to the new names and vocabulary. - Rewrite the changeset to describe the unification. Co-Authored-By: Claude Opus 4.8 (1M context) --- ...etup-pointer-only-for-hard-dependencies.md | 2 +- .agents/writing-docs.md | 8 +- .changeset/to-plan-skill.md | 5 - .changeset/unify-to-tickets.md | 10 ++ .claude-plugin/plugin.json | 5 +- .../mainstream-issue-trackers-only.md | 2 +- CONTEXT.md | 4 +- README.md | 7 +- docs/engineering/ask-matt.md | 4 +- docs/engineering/code-review.md | 10 +- docs/engineering/codebase-design.md | 2 +- docs/engineering/domain-modeling.md | 2 +- docs/engineering/grill-with-docs.md | 4 +- docs/engineering/implement.md | 10 +- docs/engineering/prototype.md | 2 +- docs/engineering/setup-matt-pocock-skills.md | 8 +- docs/engineering/tdd.md | 4 +- docs/engineering/to-issues.md | 47 ------- docs/engineering/to-plan.md | 53 -------- docs/engineering/to-prd.md | 59 --------- docs/engineering/to-spec.md | 60 +++++++++ docs/engineering/to-tickets.md | 57 +++++++++ docs/engineering/triage.md | 4 +- docs/productivity/grill-me.md | 2 +- docs/productivity/grilling.md | 2 +- docs/productivity/handoff.md | 6 +- skills/engineering/README.md | 5 +- skills/engineering/ask-matt/SKILL.md | 10 +- skills/engineering/implement/SKILL.md | 4 +- .../setup-matt-pocock-skills/SKILL.md | 2 +- skills/engineering/to-issues/SKILL.md | 91 -------------- skills/engineering/to-plan/SKILL.md | 112 ----------------- .../engineering/{to-prd => to-spec}/SKILL.md | 16 +-- skills/engineering/to-tickets/SKILL.md | 116 ++++++++++++++++++ skills/productivity/handoff/SKILL.md | 2 +- 35 files changed, 304 insertions(+), 433 deletions(-) delete mode 100644 .changeset/to-plan-skill.md create mode 100644 .changeset/unify-to-tickets.md delete mode 100644 docs/engineering/to-issues.md delete mode 100644 docs/engineering/to-plan.md delete mode 100644 docs/engineering/to-prd.md create mode 100644 docs/engineering/to-spec.md create mode 100644 docs/engineering/to-tickets.md delete mode 100644 skills/engineering/to-issues/SKILL.md delete mode 100644 skills/engineering/to-plan/SKILL.md rename skills/engineering/{to-prd => to-spec}/SKILL.md (78%) create mode 100644 skills/engineering/to-tickets/SKILL.md diff --git a/.agents/adr/0001-explicit-setup-pointer-only-for-hard-dependencies.md b/.agents/adr/0001-explicit-setup-pointer-only-for-hard-dependencies.md index 37918f9..dd2ad0f 100644 --- a/.agents/adr/0001-explicit-setup-pointer-only-for-hard-dependencies.md +++ b/.agents/adr/0001-explicit-setup-pointer-only-for-hard-dependencies.md @@ -4,7 +4,7 @@ Engineering skills depend on per-repo config (issue tracker, triage label vocabu We split these into **hard-dependency** and **soft-dependency** skills: -- **Hard dependency** (`to-issues`, `to-prd`, `triage`) — include an explicit one-liner: _"… should have been provided to you — run `/setup-matt-pocock-skills` if not."_ Without the mapping, output is wrong, not just fuzzy. +- **Hard dependency** (`to-tickets`, `to-spec`, `triage`) — include an explicit one-liner: _"… should have been provided to you — run `/setup-matt-pocock-skills` if not."_ Without the mapping, output is wrong, not just fuzzy. - **Soft dependency** (`diagnose`, `tdd`, `improve-codebase-architecture`) — reference "the project's domain glossary" and "ADRs in the area you're touching" in vague prose only. If the docs aren't there, the skill still works; output is just less sharp. The split keeps soft-dependency skills token-light and avoids cargo-culting the setup pointer into places where it isn't load-bearing. diff --git a/.agents/writing-docs.md b/.agents/writing-docs.md index 592412f..c3bfc83 100644 --- a/.agents/writing-docs.md +++ b/.agents/writing-docs.md @@ -30,7 +30,7 @@ npx skills update ## What it does -One or two plain-language paragraphs. Lead with the skill's one-sentence job, then state the **defining constraint** — the single fact that makes this skill behave differently from the obvious default (for `to-prd`: it does not interview the user again, it synthesises what is already known). Write it as a plain declarative sentence — never a labelled aside like "The defining constraint:" or "The key thing:"; the formula reads as filler. This line is the most valuable on the page; never omit it. +One or two plain-language paragraphs. Lead with the skill's one-sentence job, then state the **defining constraint** — the single fact that makes this skill behave differently from the obvious default (for `to-spec`: it does not interview the user again, it synthesises what is already known). Write it as a plain declarative sentence — never a labelled aside like "The defining constraint:" or "The key thing:"; the formula reads as filler. This line is the most valuable on the page; never omit it. ## When to reach for it @@ -41,7 +41,7 @@ How and when you reach for the skill — two beats, both effectively always pres ## Prerequisites -Optional — include only when the skill needs something in place to be functional; omit the heading entirely otherwise. Covers: a **workspace it writes into** (a stateful skill like `grill-with-docs` writes `CONTEXT.md` and ADRs; `teach` builds a whole directory — say what it writes and where), **prior setup** (`triage`/`to-prd`/`to-issues` need `setup-matt-pocock-skills` to have configured an issue tracker), or **repo-specific tooling**. A stateless skill that runs anywhere has no prerequisites — drop the section. +Optional — include only when the skill needs something in place to be functional; omit the heading entirely otherwise. Covers: a **workspace it writes into** (a stateful skill like `grill-with-docs` writes `CONTEXT.md` and ADRs; `teach` builds a whole directory — say what it writes and where), **prior setup** (`triage`/`to-spec`/`to-tickets` need `setup-matt-pocock-skills` to have configured an issue tracker), or **repo-specific tooling**. A stateless skill that runs anywhere has no prerequisites — drop the section. ## @@ -51,13 +51,13 @@ The single non-negotiable: **surface the skill's leading word / defining idea** ## It's working if -Optional. A short, checkable list of the observable signals that tell the reader the skill is actually doing its job — what they should see when it fires, and by absence when it hasn't. Include it when a skill has crisp tells (e.g. `to-prd` writes without re-interviewing you; a leading word reappearing in the trace); omit the heading when the signals are vague. A few bullets, no more. +Optional. A short, checkable list of the observable signals that tell the reader the skill is actually doing its job — what they should see when it fires, and by absence when it hasn't. Include it when a skill has crisp tells (e.g. `to-spec` writes without re-interviewing you; a leading word reappearing in the trace); omit the heading when the signals are vague. A few bullets, no more. ## Where it fits Always present. Situate the skill in the system in a sentence or two: -- **Role.** Name it: a **chain step** (`grill-with-docs → to-prd → to-issues → implement → code-review`), a **run-once setup** (`setup-matt-pocock-skills`), **periodic maintenance** (`improve-codebase-architecture`, "every few days"), or a **reach-for-it-anytime standalone** (`diagnosing-bugs`, `prototype`, `handoff`). A standalone's map is one honest sentence — far better than omitting the section. +- **Role.** Name it: a **chain step** (`grill-with-docs → to-spec → to-tickets → implement → code-review`), a **run-once setup** (`setup-matt-pocock-skills`), **periodic maintenance** (`improve-codebase-architecture`, "every few days"), or a **reach-for-it-anytime standalone** (`diagnosing-bugs`, `prototype`, `handoff`). A standalone's map is one honest sentence — far better than omitting the section. - **Neighbours.** The one or two siblings that matter, each with a because-clause, linked absolutely. - **The map.** Point to [ask-matt](https://aihero.dev/skills-ask-matt), the router over the whole set, so this page stays a node and never has to redraw the graph. diff --git a/.changeset/to-plan-skill.md b/.changeset/to-plan-skill.md deleted file mode 100644 index 5fc5609..0000000 --- a/.changeset/to-plan-skill.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -Add a new user-invoked **`to-plan`** skill to the `engineering/` bucket — the sequential, HITL sibling of **`to-issues`**. Both slice work into tracer-bullet vertical slices, but where `to-issues` produces independently-grabbable issues for parallel agents, `to-plan` produces one ordered sequence you drive by hand, one phase per fresh context. It publishes to the tracker `/setup-matt-pocock-skills` configured, shaped to it: a single sequential `plan.md` for a local tracker, or a parent issue with ordered sub-issues (native sub-issues where the platform supports them) for a real one. The `to-*` fork in `ask-matt`'s main flow now offers both, and there's a human-facing docs page at `docs/engineering/to-plan.md`. diff --git a/.changeset/unify-to-tickets.md b/.changeset/unify-to-tickets.md new file mode 100644 index 0000000..b3ad9f1 --- /dev/null +++ b/.changeset/unify-to-tickets.md @@ -0,0 +1,10 @@ +--- +"mattpocock-skills": minor +--- + +Unify the planning skills. **`to-prd` is renamed to `to-spec`** — "spec" is now the single through-line term (it still opens with "you may know this document as a PRD" for discoverability). **`to-plan` and `to-issues` are merged into one `to-tickets` skill, and `to-issues` is deleted.** + +`to-tickets` breaks a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring its **blocking edges**. That one artifact reads two ways depending on the tracker `/setup-matt-pocock-skills` configured: a **local file** (`tickets.md`) writes the edges as text and you work it top-to-bottom by hand; a **real tracker** writes them as native blocking links, so any ticket whose blockers are done is on the frontier and several agents can run at once. The edges live in the ticket either way — the medium only decides whether anything acts on them in parallel. + +`ask-matt`'s main flow now routes `idea → /to-spec → /to-tickets → /implement`, and there are human-facing docs pages at `docs/engineering/to-spec.md` and `docs/engineering/to-tickets.md`. + diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 8ec7f2c..e32cc25 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -8,9 +8,8 @@ "./skills/engineering/improve-codebase-architecture", "./skills/engineering/setup-matt-pocock-skills", "./skills/engineering/tdd", - "./skills/engineering/to-issues", - "./skills/engineering/to-plan", - "./skills/engineering/to-prd", + "./skills/engineering/to-spec", + "./skills/engineering/to-tickets", "./skills/engineering/implement", "./skills/engineering/prototype", "./skills/engineering/research", diff --git a/.out-of-scope/mainstream-issue-trackers-only.md b/.out-of-scope/mainstream-issue-trackers-only.md index 135c16f..7cd3dd6 100644 --- a/.out-of-scope/mainstream-issue-trackers-only.md +++ b/.out-of-scope/mainstream-issue-trackers-only.md @@ -4,7 +4,7 @@ ## Why this is out of scope -Every issue-tracker backend hard-codes a CLI shape into the skills (commands, flags, output parsing). Each new backend is permanent maintenance surface — it has to keep working as the tool's CLI evolves, and it has to keep being tested against `/to-prd`, `/to-issues`, `/triage`, and friends. That cost is only worth paying for trackers a meaningful fraction of users actually have. +Every issue-tracker backend hard-codes a CLI shape into the skills (commands, flags, output parsing). Each new backend is permanent maintenance surface — it has to keep working as the tool's CLI evolves, and it has to keep being tested against `/to-spec`, `/to-tickets`, `/triage`, and friends. That cost is only worth paying for trackers a meaningful fraction of users actually have. "Mainstream" is a judgment call, not a numeric bar: diff --git a/CONTEXT.md b/CONTEXT.md index eb85462..e3e4be8 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -5,11 +5,11 @@ A collection of agent skills (slash commands and behaviors) loaded by Claude Cod ## Language **Issue tracker**: -The tool that hosts a repo's issues — GitHub Issues, Linear, a local `.scratch/` markdown convention, or similar. Skills like `to-issues`, `to-prd`, `triage`, and `qa` read from and write to it. +The tool that hosts a repo's issues — GitHub Issues, Linear, a local `.scratch/` markdown convention, or similar. Skills like `to-tickets`, `to-spec`, `triage`, and `qa` read from and write to it. _Avoid_: backlog manager, backlog backend, issue host **Issue**: -A single tracked unit of work inside an **Issue tracker** — a bug, task, PRD, or slice produced by `to-issues`. +A single tracked unit of work inside an **Issue tracker** — a bug, task, spec, or slice produced by `to-tickets`. _Avoid_: ticket (use only when quoting external systems that call them tickets) **Triage role**: diff --git a/README.md b/README.md index 0caeecb..8095656 100644 --- a/README.md +++ b/README.md @@ -131,7 +131,7 @@ For debugging, I've also built a **[`/diagnosing-bugs`](./skills/engineering/dia This is built in to every layer of these skills: -- [`/to-prd`](./skills/engineering/to-prd/SKILL.md) quizzes you about which modules you're touching before creating a PRD +- [`/to-spec`](./skills/engineering/to-spec/SKILL.md) quizzes you about which modules you're touching before creating a spec And crucially, [`/improve-codebase-architecture`](./skills/engineering/improve-codebase-architecture/SKILL.md) helps you rescue a codebase that has become a ball of mud. I recommend running it on your codebase once every few days. @@ -154,9 +154,8 @@ Skills I use daily for code work. - **[triage](./skills/engineering/triage/SKILL.md)** — Move issues through a state machine of triage roles. - **[improve-codebase-architecture](./skills/engineering/improve-codebase-architecture/SKILL.md)** — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. - **[setup-matt-pocock-skills](./skills/engineering/setup-matt-pocock-skills/SKILL.md)** — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo before using the other engineering skills. -- **[to-issues](./skills/engineering/to-issues/SKILL.md)** — Break any plan, spec, or PRD into independently-grabbable issues using vertical slices. -- **[to-plan](./skills/engineering/to-plan/SKILL.md)** — Turn any plan, spec, or PRD into a sequential set of tracer-bullet phases worked one at a time — a single ordered file for a local tracker, or parent-and-sub-issues for a real one. -- **[to-prd](./skills/engineering/to-prd/SKILL.md)** — Turn the current conversation into a PRD and publish it to the issue tracker. No interview — just synthesizes what you've already discussed. +- **[to-spec](./skills/engineering/to-spec/SKILL.md)** — Turn the current conversation into a spec and publish it to the issue tracker. No interview — just synthesizes what you've already discussed. +- **[to-tickets](./skills/engineering/to-tickets/SKILL.md)** — Break any plan, spec, or conversation into a set of tracer-bullet tickets, each declaring its blocking edges — written as text in a local file, or as native blocking links on a real tracker. **Model-invoked** diff --git a/docs/engineering/ask-matt.md b/docs/engineering/ask-matt.md index bfb50c1..5873bf1 100644 --- a/docs/engineering/ask-matt.md +++ b/docs/engineering/ask-matt.md @@ -14,7 +14,7 @@ npx skills update ask-matt `ask-matt` is the router over the skills in this repo. You describe the situation you're in; it tells you which skill or flow fits and in what order to run them. -It **does no work itself**. It doesn't grill, write a PRD, or fix anything — it only orients. It exists for the **user-invoked** skills above all: nothing fires those for you, so *you* have to remember they exist, and `ask-matt` is the memory you offload that to. It also points at the model-invoked skills you'd reach for by name — `/tdd`, `/diagnosing-bugs`, `/prototype`, `/code-review`, and the two vocabulary references, `/domain-modeling` and `/codebase-design`. It answers "which one, and when", then hands you off to the skill that actually does the job. +It **does no work itself**. It doesn't grill, write a spec, or fix anything — it only orients. It exists for the **user-invoked** skills above all: nothing fires those for you, so *you* have to remember they exist, and `ask-matt` is the memory you offload that to. It also points at the model-invoked skills you'd reach for by name — `/tdd`, `/diagnosing-bugs`, `/prototype`, `/code-review`, and the two vocabulary references, `/domain-modeling` and `/codebase-design`. It answers "which one, and when", then hands you off to the skill that actually does the job. ## When to reach for it @@ -24,7 +24,7 @@ Reach for it whenever you're unsure which skill or flow a situation calls for: y ## Flows, not just skills -The idea `ask-matt` gives you to think with is the **flow** — a path *through* the skills rather than a single one. Most work runs along one **main flow** (idea → ship: grill → PRD → issues → implement → review), two **on-ramps** merge onto it (a triage lane for incoming bugs and requests; a codebase-health lane that generates ideas), and everything else is a **standalone** you reach for on its own. Ask a question and you get placed on the right flow, at the right step — not just handed a tool. +The idea `ask-matt` gives you to think with is the **flow** — a path *through* the skills rather than a single one. Most work runs along one **main flow** (idea → ship: grill → spec → tickets → implement → review), two **on-ramps** merge onto it (a triage lane for incoming bugs and requests; a codebase-health lane that generates ideas), and everything else is a **standalone** you reach for on its own. Ask a question and you get placed on the right flow, at the right step — not just handed a tool. ## Where it fits diff --git a/docs/engineering/code-review.md b/docs/engineering/code-review.md index b6ebbf3..ac48f2b 100644 --- a/docs/engineering/code-review.md +++ b/docs/engineering/code-review.md @@ -12,7 +12,7 @@ npx skills update code-review ## What it does -`code-review` reviews the diff between `HEAD` and a fixed point you supply — a commit, branch, tag, or merge-base — along two separate axes: **Standards** (does the code follow this repo's documented conventions?) and **Spec** (does it implement what the originating issue or PRD asked for?). It runs each axis as its own parallel sub-agent and reports them side by side. It never merges or re-ranks the two sets of findings — keeping them separate is the whole point, because a change can pass one axis and fail the other, and a single blended verdict lets one mask the other. +`code-review` reviews the diff between `HEAD` and a fixed point you supply — a commit, branch, tag, or merge-base — along two separate axes: **Standards** (does the code follow this repo's documented conventions?) and **Spec** (does it implement what the originating issue or spec asked for?). It runs each axis as its own parallel sub-agent and reports them side by side. It never merges or re-ranks the two sets of findings — keeping them separate is the whole point, because a change can pass one axis and fail the other, and a single blended verdict lets one mask the other. ## When to reach for it @@ -22,11 +22,11 @@ Reach for this when there is a diff to judge against a known-good point and you ## Prerequisites -The **Spec** axis needs somewhere to find the originating spec — an issue reference in the commit messages, a path you pass in, or a PRD under `docs/`/`specs/`. That issue-tracker wiring comes from [setup-matt-pocock-skills](https://aihero.dev/skills-setup-matt-pocock-skills); without a spec the Spec axis simply skips and says so. The **Standards** axis needs nothing set up — it always carries a built-in Fowler smell baseline even in a repo that documents no conventions. +The **Spec** axis needs somewhere to find the originating spec — an issue reference in the commit messages, a path you pass in, or a spec under `docs/`/`specs/`. That issue-tracker wiring comes from [setup-matt-pocock-skills](https://aihero.dev/skills-setup-matt-pocock-skills); without a spec the Spec axis simply skips and says so. The **Standards** axis needs nothing set up — it always carries a built-in Fowler smell baseline even in a repo that documents no conventions. ## Two axes, never merged -The defining idea is the **two axes**. **Standards** asks whether the diff conforms to how this repo writes code — its `CODING_STANDARDS.md` or `CONTRIBUTING.md`, plus a fixed baseline of ~12 Fowler code smells (Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, …). Two rules keep the baseline safe: a documented repo standard always overrides it, and every smell is a judgement call, never a hard violation. **Spec** asks the orthogonal question — does the code do what the issue or PRD actually asked, without missing requirements or smuggling in scope creep? +The defining idea is the **two axes**. **Standards** asks whether the diff conforms to how this repo writes code — its `CODING_STANDARDS.md` or `CONTRIBUTING.md`, plus a fixed baseline of ~12 Fowler code smells (Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, …). Two rules keep the baseline safe: a documented repo standard always overrides it, and every smell is a judgement call, never a hard violation. **Spec** asks the orthogonal question — does the code do what the issue or spec actually asked, without missing requirements or smuggling in scope creep? They run as parallel sub-agents so neither pollutes the other's context, and the final report presents them under separate `## Standards` and `## Spec` headings with a per-axis summary. There is deliberately no single winner across axes. @@ -41,7 +41,7 @@ They run as parallel sub-agents so neither pollutes the other's context, and the `code-review` is the review step at the tail of the main build chain: ```txt -grill-with-docs → to-prd → to-issues → implement → code-review +grill-with-docs → to-spec → to-tickets → implement → code-review ``` -Its closest neighbour is [implement](https://aihero.dev/skills-implement), which drives the build and calls this as its own review pass before committing; upstream, the spec it checks against is produced by [to-prd](https://aihero.dev/skills-to-prd) and [to-issues](https://aihero.dev/skills-to-issues). When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. +Its closest neighbour is [implement](https://aihero.dev/skills-implement), which drives the build and calls this as its own review pass before committing; upstream, the spec it checks against is produced by [to-spec](https://aihero.dev/skills-to-spec) and [to-tickets](https://aihero.dev/skills-to-tickets). When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/engineering/codebase-design.md b/docs/engineering/codebase-design.md index d2c8d80..2240e74 100644 --- a/docs/engineering/codebase-design.md +++ b/docs/engineering/codebase-design.md @@ -34,7 +34,7 @@ Callers and tests cross the same seam, so a well-placed interface gives tests so ## Pulled out on purpose -`codebase-design` is the **single source of truth** for the deep-module vocabulary, split out as its own model-invoked skill so anything can reach it. Other skills point at it rather than restating the words: [tdd](https://aihero.dev/skills-tdd) borrows it to place a seam before writing the test, [improve-codebase-architecture](https://aihero.dev/skills-improve-codebase-architecture) leans on it while restructuring existing code, and [to-prd](https://aihero.dev/skills-to-prd) speaks it when it sketches seams and deepening opportunities before writing a spec. +`codebase-design` is the **single source of truth** for the deep-module vocabulary, split out as its own model-invoked skill so anything can reach it. Other skills point at it rather than restating the words: [tdd](https://aihero.dev/skills-tdd) borrows it to place a seam before writing the test, [improve-codebase-architecture](https://aihero.dev/skills-improve-codebase-architecture) leans on it while restructuring existing code, and [to-spec](https://aihero.dev/skills-to-spec) speaks it when it sketches seams and deepening opportunities before writing a spec. The point of keeping it standalone is that you can also reach for it on its own — as a **reference** for how to think about module design — without triggering the larger process any of those skills mandate. Fix the words once, in one place, and every design conversation inherits them. diff --git a/docs/engineering/domain-modeling.md b/docs/engineering/domain-modeling.md index d9927d3..273cfde 100644 --- a/docs/engineering/domain-modeling.md +++ b/docs/engineering/domain-modeling.md @@ -43,4 +43,4 @@ Keeping it standalone means you can also reach for it directly — as a **refere ## Where it fits -`domain-modeling` is a **reach-for-it-anytime standalone** that runs *underneath* other skills as often as at a fixed step. Its closest neighbour is [codebase-design](https://aihero.dev/skills-codebase-design), because a shared language is what lets you name a deep module and its seam precisely; downstream, a settled glossary is exactly what [to-prd](https://aihero.dev/skills-to-prd) synthesises into a spec written in the project's own words. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. +`domain-modeling` is a **reach-for-it-anytime standalone** that runs *underneath* other skills as often as at a fixed step. Its closest neighbour is [codebase-design](https://aihero.dev/skills-codebase-design), because a shared language is what lets you name a deep module and its seam precisely; downstream, a settled glossary is exactly what [to-spec](https://aihero.dev/skills-to-spec) synthesises into a spec written in the project's own words. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/engineering/grill-with-docs.md b/docs/engineering/grill-with-docs.md index e9cd220..e8c4abc 100644 --- a/docs/engineering/grill-with-docs.md +++ b/docs/engineering/grill-with-docs.md @@ -44,7 +44,7 @@ What makes this variant its own skill is where the answers go. As the grill runs `grill-with-docs` is the opening step of the main build chain: ```txt -grill-with-docs → to-prd → to-issues → implement → code-review +grill-with-docs → to-spec → to-tickets → implement → code-review ``` -It comes first, before anything is written down as a spec: it produces the shared understanding and settled vocabulary that [to-prd](https://aihero.dev/skills-to-prd) then synthesises into a PRD without re-interviewing you. Its close neighbours are [grilling](https://aihero.dev/skills-grilling), the same interview without the docs, and [domain-modeling](https://aihero.dev/skills-domain-modeling), the glossary-and-ADR discipline it drives. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. +It comes first, before anything is written down as a spec: it produces the shared understanding and settled vocabulary that [to-spec](https://aihero.dev/skills-to-spec) then synthesises into a spec without re-interviewing you. Its close neighbours are [grilling](https://aihero.dev/skills-grilling), the same interview without the docs, and [domain-modeling](https://aihero.dev/skills-domain-modeling), the glossary-and-ADR discipline it drives. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/engineering/implement.md b/docs/engineering/implement.md index 7e44167..e079af8 100644 --- a/docs/engineering/implement.md +++ b/docs/engineering/implement.md @@ -12,7 +12,7 @@ npx skills update implement ## What it does -`implement` builds the work described in a PRD or a set of issues — driving it through test-driven development, typechecking, and the full test suite, then handing off to review and committing to the current branch. +`implement` builds the work described in a spec or a set of tickets — driving it through test-driven development, typechecking, and the full test suite, then handing off to review and committing to the current branch. It does **not** decide what to build. The spec is already settled and the seams are already agreed; `implement` executes that plan rather than reopening it. It is the hands, not the head — the thinking happened upstream. @@ -20,11 +20,11 @@ It does **not** decide what to build. The spec is already settled and the seams You invoke this by typing `/implement` — the agent won't reach for it on its own. -Reach for it once the work is written down as a PRD or split into issues and you're ready to turn that into code. If the spec doesn't exist yet, write it first — for that, use [to-prd](https://aihero.dev/skills-to-prd), or [to-issues](https://aihero.dev/skills-to-issues) to break a PRD into tickets. If you just want to build something test-first without a full spec, drop to [tdd](https://aihero.dev/skills-tdd) directly. +Reach for it once the work is written down as a spec or split into tickets and you're ready to turn that into code. If the spec doesn't exist yet, write it first — for that, use [to-spec](https://aihero.dev/skills-to-spec), or [to-tickets](https://aihero.dev/skills-to-tickets) to break a spec into tickets. If you just want to build something test-first without a full spec, drop to [tdd](https://aihero.dev/skills-tdd) directly. ## Pre-agreed seams -The idea `implement` runs on is the **seam** — the stable interface a feature is tested at, chosen before any code is written. It doesn't invent seams mid-build; it uses the ones already picked (during [to-prd](https://aihero.dev/skills-to-prd)) and writes tests against them via [tdd](https://aihero.dev/skills-tdd). Working at pre-agreed seams is what keeps the implementation honest: the tests target something durable, so the code underneath can move without the tests moving. +The idea `implement` runs on is the **seam** — the stable interface a feature is tested at, chosen before any code is written. It doesn't invent seams mid-build; it uses the ones already picked (during [to-spec](https://aihero.dev/skills-to-spec)) and writes tests against them via [tdd](https://aihero.dev/skills-tdd). Working at pre-agreed seams is what keeps the implementation honest: the tests target something durable, so the code underneath can move without the tests moving. Around that core it keeps the loop tight — typecheck often, run single test files as it goes, run the whole suite once at the end — then closes out with a review pass and a commit to the current branch. @@ -33,7 +33,7 @@ Around that core it keeps the loop tight — typecheck often, run single test fi `implement` is the build step near the end of the main chain, just before the review: ```txt -grill-with-docs → to-prd → to-issues → implement → code-review +grill-with-docs → to-spec → to-tickets → implement → code-review ``` -Reach for it after the work has been specced and sequenced, not before. Its key neighbours are [to-issues](https://aihero.dev/skills-to-issues), which produces the independently-grabbable tickets it works through, and [tdd](https://aihero.dev/skills-tdd), which it drives internally to write the tests at each seam before running its own [code-review](https://aihero.dev/skills-code-review) pass and committing. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. +Reach for it after the work has been specced and sequenced, not before. Its key neighbours are [to-tickets](https://aihero.dev/skills-to-tickets), which produces the tickets — each declaring its blocking edges — that it works through, and [tdd](https://aihero.dev/skills-tdd), which it drives internally to write the tests at each seam before running its own [code-review](https://aihero.dev/skills-code-review) pass and committing. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/engineering/prototype.md b/docs/engineering/prototype.md index db8eb8e..af8ca42 100644 --- a/docs/engineering/prototype.md +++ b/docs/engineering/prototype.md @@ -37,4 +37,4 @@ The code is disposable; the **answer** is the only thing worth keeping. When the ## Where it fits -`prototype` is a reach-for-it-anytime standalone: you drop into it to resolve a design question, then drop back out. Its answer often feeds the next step — a validated state model or UI direction becomes settled input for [to-prd](https://aihero.dev/skills-to-prd) to write up, or an architectural decision worth recording via [domain-modeling](https://aihero.dev/skills-domain-modeling). When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. +`prototype` is a reach-for-it-anytime standalone: you drop into it to resolve a design question, then drop back out. Its answer often feeds the next step — a validated state model or UI direction becomes settled input for [to-spec](https://aihero.dev/skills-to-spec) to write up, or an architectural decision worth recording via [domain-modeling](https://aihero.dev/skills-domain-modeling). When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/engineering/setup-matt-pocock-skills.md b/docs/engineering/setup-matt-pocock-skills.md index b9b1d6f..47d793e 100644 --- a/docs/engineering/setup-matt-pocock-skills.md +++ b/docs/engineering/setup-matt-pocock-skills.md @@ -20,13 +20,13 @@ It writes config, it does not hard-code behaviour. The engineering chain assumes You invoke this by typing `/setup-matt-pocock-skills` — the agent won't reach for it on its own. -Reach for it **once per repo, before the first use of any other engineering skill**. If [triage](https://aihero.dev/skills-triage), [to-prd](https://aihero.dev/skills-to-prd), or [to-issues](https://aihero.dev/skills-to-issues) start guessing where your issues live or applying labels that don't exist, they haven't been set up here yet. Re-run it only to switch issue trackers or start over — day-to-day tweaks are just edits to `docs/agents/*.md`. +Reach for it **once per repo, before the first use of any other engineering skill**. If [triage](https://aihero.dev/skills-triage), [to-spec](https://aihero.dev/skills-to-spec), or [to-tickets](https://aihero.dev/skills-to-tickets) start guessing where your issues live or applying labels that don't exist, they haven't been set up here yet. Re-run it only to switch issue trackers or start over — day-to-day tweaks are just edits to `docs/agents/*.md`. ## The three decisions It walks you through three choices, one at a time, each with a plain-language explainer (it assumes you don't already know the terms): -- **Issue tracker** — where work is tracked, so `triage`/`to-prd`/`to-issues` know whether to call `gh`, `glab`, write markdown under `.scratch/`, or follow a workflow you describe. GitHub, GitLab, local markdown, or other. +- **Issue tracker** — where work is tracked, so `triage`/`to-spec`/`to-tickets` know whether to call `gh`, `glab`, write markdown under `.scratch/`, or follow a workflow you describe. GitHub, GitLab, local markdown, or other. - **Triage labels** — the strings behind the five canonical roles (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`), mapped to labels you've actually configured so `triage` applies real ones instead of creating duplicates. - **Domain docs** — whether the repo has one `CONTEXT.md` or a multi-context map, so skills that read domain language look in the right place. @@ -36,8 +36,8 @@ The output is three files — `docs/agents/issue-tracker.md`, `docs/agents/triag - Three files land under `docs/agents/`, and an `## Agent skills` section appears in your `CLAUDE.md` or `AGENTS.md`. - The tracker it proposes matches your real `git remote`, and the labels match strings that already exist in your repo. -- Afterwards, `triage` and `to-issues` act on the right place with the right labels instead of asking or guessing. +- Afterwards, `triage` and `to-tickets` act on the right place with the right labels instead of asking or guessing. ## Where it fits -`setup-matt-pocock-skills` is a **run-once setup** — the foundation the whole engineering set stands on, not a step you repeat. Its neighbours are the skills that read what it writes: [triage](https://aihero.dev/skills-triage), because it applies the label vocabulary configured here, and [to-prd](https://aihero.dev/skills-to-prd) / [to-issues](https://aihero.dev/skills-to-issues), because they publish into the issue tracker configured here. Run it first; everything downstream assumes it has. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. +`setup-matt-pocock-skills` is a **run-once setup** — the foundation the whole engineering set stands on, not a step you repeat. Its neighbours are the skills that read what it writes: [triage](https://aihero.dev/skills-triage), because it applies the label vocabulary configured here, and [to-spec](https://aihero.dev/skills-to-spec) / [to-tickets](https://aihero.dev/skills-to-tickets), because they publish into the issue tracker configured here. Run it first; everything downstream assumes it has. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/engineering/tdd.md b/docs/engineering/tdd.md index a0fe809..46b636e 100644 --- a/docs/engineering/tdd.md +++ b/docs/engineering/tdd.md @@ -20,7 +20,7 @@ It will **not** write all the tests up front. Batching the tests first ("horizon Type `/tdd`, or the agent reaches for it automatically when a task fits — building a feature or fixing a bug test-first, or when you say "red-green-refactor". -Reach for it when there's a concrete behaviour to build and you want tests that survive a refactor. If the behaviour isn't pinned down yet, settle the spec first — for that, use [to-prd](https://aihero.dev/skills-to-prd). When the work is really about the shape of the interface rather than the tests, use [codebase-design](https://aihero.dev/skills-codebase-design); `tdd` calls into it for the deep-module vocabulary during planning. +Reach for it when there's a concrete behaviour to build and you want tests that survive a refactor. If the behaviour isn't pinned down yet, settle the spec first — for that, use [to-spec](https://aihero.dev/skills-to-spec). When the work is really about the shape of the interface rather than the tests, use [codebase-design](https://aihero.dev/skills-codebase-design); `tdd` calls into it for the deep-module vocabulary during planning. ## Red-green, one slice at a time @@ -41,7 +41,7 @@ Refactoring only happens once the suite is green; never while red. `tdd` is the red-green loop the main build chain runs to write code: ```txt -grill-with-docs → to-prd → to-issues → implement → code-review +grill-with-docs → to-spec → to-tickets → implement → code-review ``` [implement](https://aihero.dev/skills-implement) is the chain's build step, and it drives `tdd` internally to build each ticket test-first before handing off to [code-review](https://aihero.dev/skills-code-review) — so `tdd` is the engine inside that step rather than a step of its own. You can also reach for it directly, whenever there's a concrete behaviour to build without a full spec. Its other neighbour is [codebase-design](https://aihero.dev/skills-codebase-design), which it leans on to find deep-module seams worth testing at. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/engineering/to-issues.md b/docs/engineering/to-issues.md deleted file mode 100644 index 99624b5..0000000 --- a/docs/engineering/to-issues.md +++ /dev/null @@ -1,47 +0,0 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=to-issues -``` - -```bash -npx skills update to-issues -``` - -[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/to-issues) - -## What it does - -`to-issues` breaks a plan, spec, or PRD into a set of independently-grabbable issues and publishes them to your project's issue tracker, in dependency order. - -Every issue is a **tracer bullet** — a thin *vertical* slice that cuts through all integration layers end-to-end (schema, API, UI, tests), never a horizontal slice of one layer. A completed slice is demoable or verifiable on its own, which is what makes the resulting tickets safe to hand to independent agents. - -## When to reach for it - -You invoke this by typing `/to-issues` — the agent won't reach for it on its own. - -Reach for it once you have an agreed plan or a written spec and you want it split into tickets an agent can pick up. Point it at the conversation, or pass an existing issue reference and it fetches the body and comments first. If the change hasn't been written up as a spec yet, produce one first — for that, use [to-prd](https://aihero.dev/skills-to-prd). - -## Prerequisites - -`to-issues` publishes into your issue tracker, so [setup-matt-pocock-skills](https://aihero.dev/skills-setup-matt-pocock-skills) must have configured the tracker and its triage label vocabulary for this repo first. It applies the ready-for-agent triage label itself as it publishes. - -## Vertical slices, not horizontal ones - -The whole skill turns on one distinction. A **horizontal** slice ships one layer of the change — all the schema, or all the API — and nothing works until every layer lands. A **vertical** slice, the tracer bullet, ships one narrow path through *every* layer at once, so it can be demoed the moment it's done. - -Before slicing, `to-issues` looks for prefactoring — "make the change easy, then make the easy change" — and orders that work first. It then quizzes you on the breakdown (granularity, dependencies, what to merge or split) before writing anything, and publishes blockers first so each issue's "Blocked by" field can reference a real ticket. - -## The wide-refactor exception - -One shape breaks the tracer-bullet rule: a **wide refactor** — a single mechanical change (rename a column, retype a shared symbol) whose **blast radius** fans across the whole codebase, so one edit breaks thousands of call sites at once and no vertical slice can land green. `to-issues` slices it as **expand–contract** instead: expand (add the new form beside the old so nothing breaks), migrate (move call sites over in batches sized by blast radius, one issue per batch, CI green throughout because the old form still exists), then contract (delete the old form once no caller remains). When even the batches can't stay green alone, they share an integration branch that all block a final integrate-and-verify issue, and green is promised only there. - -## Where it fits - -`to-issues` is a step in the main build chain: - -```txt -grill-with-docs → to-prd → to-issues → implement → code-review -``` - -It sits between [to-prd](https://aihero.dev/skills-to-prd), which hands it a settled spec with user stories to slice against, and [implement](https://aihero.dev/skills-implement), which builds each independently-grabbable issue, driving [tdd](https://aihero.dev/skills-tdd) internally to write the tests test-first, before its [code-review](https://aihero.dev/skills-code-review) pass. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/engineering/to-plan.md b/docs/engineering/to-plan.md deleted file mode 100644 index b797426..0000000 --- a/docs/engineering/to-plan.md +++ /dev/null @@ -1,53 +0,0 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=to-plan -``` - -```bash -npx skills update to-plan -``` - -[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/to-plan) - -## What it does - -`to-plan` turns a PRD, spec, or the current conversation into a **sequential** plan — an ordered list of phases you work through one at a time, in a fresh context per phase. - -Every phase is a **tracer bullet** — a thin *vertical* slice that cuts through all integration layers end-to-end (schema, API, UI, tests), never a horizontal slice of one layer. A completed slice is demoable or verifiable on its own, and is sized to fit a single fresh context window. - -## When to reach for it - -You invoke this by typing `/to-plan` — the agent won't reach for it on its own. - -Reach for it once you have an agreed plan or a written spec and you want it turned into a sequence of phases you'll build **by hand, one at a time**. Point it at the conversation, or pass a PRD or issue reference and it reads that first. If the change hasn't been written up as a spec yet, produce one first — for that, use [to-prd](https://aihero.dev/skills-to-prd). - -## Sequential, not parallel - -`to-plan` is the sequential, HITL sibling of [to-issues](https://aihero.dev/skills-to-issues). Both slice work into tracer bullets, but they're for different workflows: - -- **`to-issues`** produces *independently-grabbable* issues, so parallel agents can pick them up at once (it applies the ready-for-agent label). -- **`to-plan`** produces one *ordered sequence* you drive yourself, phase by phase, staying in the loop — no ready-for-agent label. - -## Publishes to your configured tracker - -Like the other skills, `to-plan` publishes through the tracker [setup-matt-pocock-skills](https://aihero.dev/skills-setup-matt-pocock-skills) configured, and it adapts the shape to that tracker: - -- **Local files** → a single sequential `plan.md` in the repo root, all phases in order. -- **A real issue tracker (GitHub, Linear)** → a parent issue for the whole plan, with one sub-issue per phase, in order — using the platform's native sub-issue relationship where it has one, otherwise sequential issues each blocked by the previous. - -## Vertical slices, not horizontal ones - -The whole skill turns on one distinction. A **horizontal** slice ships one layer of the change — all the schema, or all the API — and nothing works until every layer lands. A **vertical** slice, the tracer bullet, ships one narrow path through *every* layer at once, so it can be demoed the moment it's done. - -Before slicing, `to-plan` looks for prefactoring — "make the change easy, then make the easy change" — and orders that work first. It then quizzes you on the breakdown (granularity, ordering, what to merge or split) before publishing anything. - -## Where it fits - -`to-plan` is the sequential branch of the main build chain: - -```txt -grill-with-docs → to-prd → to-plan → implement → code-review -``` - -It sits between [to-prd](https://aihero.dev/skills-to-prd), which hands it a settled spec to slice against, and [implement](https://aihero.dev/skills-implement), which builds each phase, driving [tdd](https://aihero.dev/skills-tdd) internally to write the tests test-first, before its [code-review](https://aihero.dev/skills-code-review) pass. Work one phase per fresh context, clearing between them. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/engineering/to-prd.md b/docs/engineering/to-prd.md deleted file mode 100644 index 1a8dbde..0000000 --- a/docs/engineering/to-prd.md +++ /dev/null @@ -1,59 +0,0 @@ -Quickstart: - -```bash -npx skills add mattpocock/skills --skill=to-prd -``` - -```bash -npx skills update to-prd -``` - -[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/to-prd) - -## What it does - -`to-prd` turns the current conversation and your codebase understanding into a product requirements document, then publishes it to your issue tracker. - -It does **not** interview you again. By the time you reach for it, the alignment work is done — `to-prd` synthesises what is already known rather than asking a fresh round of questions. - -## When to reach for it - -You invoke this by typing `/to-prd` — the agent won't reach for it on its own. - -Reach for it once a change has been talked through and the domain language is settled, and you want that shared understanding written down as a spec before any code is written. If you *haven't* aligned yet, grill first — for that, use [grill-with-docs](https://aihero.dev/skills-grill-with-docs). To split the finished PRD into tickets, use [to-issues](https://aihero.dev/skills-to-issues). - -## Prerequisites - -`to-prd` publishes into your issue tracker, so [setup-matt-pocock-skills](https://aihero.dev/skills-setup-matt-pocock-skills) must have configured the tracker and triage labels for this repo first. It applies the `ready-for-agent` label itself — no separate triage pass needed. - -## What the PRD includes - -- **Problem statement** — what is broken or missing, and why it's worth solving, in the project's own vocabulary. -- **Solution** — the shape of the fix at a high level, before any implementation detail. -- **User stories** — an extensive, numbered list of the concrete behaviours the change must support, each one independently checkable. -- **Implementation decisions** — the choices already settled during the conversation, so they aren't relitigated later. -- **Testing decisions** — the seams the feature will be tested at, and what "done" looks like. -- **Out-of-scope items** — what this change deliberately does *not* cover, to keep the ticket bounded. -- **Further notes** — anything else worth carrying forward that doesn't fit the sections above. - -## Deep modules - -Before writing the PRD, `to-prd` sketches the **seams** at which the feature will be tested and looks for **deep module** opportunities — a lot of functionality hidden behind a small, stable interface. It prefers existing seams to new ones and the highest seam possible, ideally just one across the whole change. - -That matters for agentic development: a good interface gives tests something durable to target, so the code underneath can change without the tests moving. - -## It's working if - -- It starts writing the PRD instead of asking you a fresh round of questions. -- It checks the seams with you before writing, and proposes as few as possible. -- The PRD comes back in your project's domain vocabulary, not generic boilerplate. - -## Where it fits - -`to-prd` is a step in the main build chain: - -```txt -grill-with-docs → to-prd → to-issues → implement → code-review -``` - -Reach for it after the plan and domain language are resolved, and before you break the work into implementation tickets. Its key neighbours are [grill-with-docs](https://aihero.dev/skills-grill-with-docs), which sharpens the context so the PRD is precise, and [to-issues](https://aihero.dev/skills-to-issues), which turns the PRD into independently-grabbable issues for [implement](https://aihero.dev/skills-implement) to build. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/engineering/to-spec.md b/docs/engineering/to-spec.md new file mode 100644 index 0000000..8494b7a --- /dev/null +++ b/docs/engineering/to-spec.md @@ -0,0 +1,60 @@ +Quickstart: + +```bash +npx skills add mattpocock/skills --skill=to-spec +``` + +```bash +npx skills update to-spec +``` + +[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/to-spec) + +## What it does + +`to-spec` turns the current conversation and your codebase understanding into a spec (you may know this document as a PRD), then publishes it to your issue tracker. + +It does **not** interview you again. By the time you reach for it, the alignment work is done — `to-spec` synthesises what is already known rather than asking a fresh round of questions. + +## When to reach for it + +You invoke this by typing `/to-spec` — the agent won't reach for it on its own. + +Reach for it once a change has been talked through and the domain language is settled, and you want that shared understanding written down before any code is written. If you *haven't* aligned yet, grill first — for that, use [grill-with-docs](https://aihero.dev/skills-grill-with-docs). To split the finished spec into tickets, use [to-tickets](https://aihero.dev/skills-to-tickets). + +## Prerequisites + +`to-spec` publishes into your issue tracker, so [setup-matt-pocock-skills](https://aihero.dev/skills-setup-matt-pocock-skills) must have configured the tracker and triage labels for this repo first. It applies the `ready-for-agent` label itself — no separate triage pass needed. + +## What the spec includes + +- **Problem statement** — what is broken or missing, and why it's worth solving, in the project's own vocabulary. +- **Solution** — the shape of the fix at a high level, before any implementation detail. +- **User stories** — an extensive, numbered list of the concrete behaviours the change must support, each one independently checkable. +- **Implementation decisions** — the choices already settled during the conversation, so they aren't relitigated later. +- **Testing decisions** — the seams the feature will be tested at, and what "done" looks like. +- **Out-of-scope items** — what this change deliberately does *not* cover, to keep the ticket bounded. +- **Further notes** — anything else worth carrying forward that doesn't fit the sections above. + +## Deep modules + +Before writing the spec, `to-spec` sketches the **seams** at which the feature will be tested and looks for **deep module** opportunities — a lot of functionality hidden behind a small, stable interface. It prefers existing seams to new ones and the highest seam possible, ideally just one across the whole change. + +That matters for agentic development: a good interface gives tests something durable to target, so the code underneath can change without the tests moving. + +## It's working if + +- It starts writing the spec instead of asking you a fresh round of questions. +- It checks the seams with you before writing, and proposes as few as possible. +- The spec comes back in your project's domain vocabulary, not generic boilerplate. + +## Where it fits + +`to-spec` is a step in the main build chain: + +```txt +grill-with-docs → to-spec → to-tickets → implement → code-review +``` + +Reach for it after the plan and domain language are resolved, and before you break the work into implementation tickets. Its key neighbours are [grill-with-docs](https://aihero.dev/skills-grill-with-docs), which sharpens the context so the spec is precise, and [to-tickets](https://aihero.dev/skills-to-tickets), which turns the spec into a set of tickets for [implement](https://aihero.dev/skills-implement) to build. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. + diff --git a/docs/engineering/to-tickets.md b/docs/engineering/to-tickets.md new file mode 100644 index 0000000..113f891 --- /dev/null +++ b/docs/engineering/to-tickets.md @@ -0,0 +1,57 @@ +Quickstart: + +```bash +npx skills add mattpocock/skills --skill=to-tickets +``` + +```bash +npx skills update to-tickets +``` + +[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/to-tickets) + +## What it does + +`to-tickets` breaks a plan, spec, or the current conversation into a set of **tickets** — each a tracer-bullet vertical slice — and publishes them to your configured tracker, with every ticket declaring the tickets that block it. + +Every ticket is a **tracer bullet** — a thin *vertical* slice that cuts through all integration layers end-to-end (schema, API, UI, tests), never a horizontal slice of one layer. A completed slice is demoable or verifiable on its own, which is what makes each ticket safe to hand to an agent. + +## When to reach for it + +You invoke this by typing `/to-tickets` — the agent won't reach for it on its own. + +Reach for it once you have an agreed plan or a written spec and you want it split into tickets. Point it at the conversation, or pass a spec or issue reference and it fetches the body and comments first. If the change hasn't been written up as a spec yet, produce one first — for that, use [to-spec](https://aihero.dev/skills-to-spec). + +## Prerequisites + +`to-tickets` publishes into your issue tracker, so [setup-matt-pocock-skills](https://aihero.dev/skills-setup-matt-pocock-skills) must have configured the tracker and its triage label vocabulary for this repo first. On a real tracker it applies the ready-for-agent label as it publishes. + +## One artifact, two readings + +The blocking edges are the whole point. They make one set of tickets read two ways, depending on the tracker: + +- **Local files** → a single `tickets.md` in the repo root, the edges written as text. You work it top-to-bottom, by hand, staying in the loop. +- **A real tracker (GitHub, Linear)** → one issue per ticket, the edges as native blocking links (or sub-issues). Any ticket whose blockers are all done is on the **frontier** and can be grabbed — so several agents can run at once. + +The edges live in the ticket regardless of medium; the medium only decides whether anything acts on them in parallel. `to-tickets` produces the artifact — how you run it (sequential by hand, or a parallel fleet) is up to you. + +## Vertical slices, not horizontal ones + +The whole skill turns on one distinction. A **horizontal** slice ships one layer of the change — all the schema, or all the API — and nothing works until every layer lands. A **vertical** slice, the tracer bullet, ships one narrow path through *every* layer at once, so it can be demoed the moment it's done. + +Before slicing, `to-tickets` looks for prefactoring — "make the change easy, then make the easy change" — and orders that work first. It then quizzes you on the breakdown (granularity, blocking edges, what to merge or split) before publishing anything, and publishes blockers first so each ticket's "Blocked by" can reference a real ticket. + +## The wide-refactor exception + +One shape breaks the tracer-bullet rule: a **wide refactor** — a single mechanical change (rename a column, retype a shared symbol) whose **blast radius** fans across the whole codebase, so one edit breaks thousands of call sites at once and no vertical slice can land green. `to-tickets` slices it as **expand–contract** instead: expand (add the new form beside the old so nothing breaks), migrate (move call sites over in batches sized by blast radius, one ticket per batch, CI green throughout because the old form still exists), then contract (delete the old form once no caller remains). When even the batches can't stay green alone, they share an integration branch that all block a final integrate-and-verify ticket, and green is promised only there. + +## Where it fits + +`to-tickets` is a step in the main build chain: + +```txt +grill-with-docs → to-spec → to-tickets → implement → code-review +``` + +It sits between [to-spec](https://aihero.dev/skills-to-spec), which hands it a settled spec with user stories to slice against, and [implement](https://aihero.dev/skills-implement), which builds each ticket, driving [tdd](https://aihero.dev/skills-tdd) internally to write the tests test-first, before its [code-review](https://aihero.dev/skills-code-review) pass. Work the frontier one ticket per fresh context, clearing between them. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. + diff --git a/docs/engineering/triage.md b/docs/engineering/triage.md index a43b71d..00673b5 100644 --- a/docs/engineering/triage.md +++ b/docs/engineering/triage.md @@ -20,7 +20,7 @@ It never labels blind. Every triaged item carries exactly one **category** role You invoke this by typing `/triage` and describing what you want in natural language — the agent won't reach for it on its own. "Show me anything that needs my attention", "let's look at #42", "move #42 to ready-for-agent". -Reach for it when your issue tracker has raw, unevaluated reports and you want them sorted, verified, and turned into work an agent or human can pick up. To turn a settled conversation into a fresh spec instead, use [to-prd](https://aihero.dev/skills-to-prd); to split an existing PRD into tickets, use [to-issues](https://aihero.dev/skills-to-issues). `triage` is the reverse direction — it processes what's *already* landed in the tracker. +Reach for it when your issue tracker has raw, unevaluated reports and you want them sorted, verified, and turned into work an agent or human can pick up. To turn a settled conversation into a fresh spec instead, use [to-spec](https://aihero.dev/skills-to-spec); to split an existing spec into tickets, use [to-tickets](https://aihero.dev/skills-to-tickets). `triage` is the reverse direction — it processes what's *already* landed in the tracker. ## Prerequisites @@ -43,4 +43,4 @@ The step that separates `triage` from ad-hoc labelling is verification. It repro ## Where it fits -`triage` is the **periodic maintenance** pass over your issue tracker — run it whenever reports pile up, to keep the queue sorted and the `ready-for-agent` column trustworthy. It sits at the front of the tracker, upstream of the build chain: the briefs it writes are what [tdd](https://aihero.dev/skills-tdd) later picks up to implement. When a request needs sharpening it leans on [grilling](https://aihero.dev/skills-grilling) and [domain-modeling](https://aihero.dev/skills-domain-modeling) to grill it into shape one question at a time. Its close neighbour is [to-prd](https://aihero.dev/skills-to-prd), which populates the tracker from a fresh conversation where `triage` processes what's already there. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. +`triage` is the **periodic maintenance** pass over your issue tracker — run it whenever reports pile up, to keep the queue sorted and the `ready-for-agent` column trustworthy. It sits at the front of the tracker, upstream of the build chain: the briefs it writes are what [tdd](https://aihero.dev/skills-tdd) later picks up to implement. When a request needs sharpening it leans on [grilling](https://aihero.dev/skills-grilling) and [domain-modeling](https://aihero.dev/skills-domain-modeling) to grill it into shape one question at a time. Its close neighbour is [to-spec](https://aihero.dev/skills-to-spec), which populates the tracker from a fresh conversation where `triage` processes what's already there. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/productivity/grill-me.md b/docs/productivity/grill-me.md index 38e4e33..7a8e3fb 100644 --- a/docs/productivity/grill-me.md +++ b/docs/productivity/grill-me.md @@ -30,4 +30,4 @@ The session walks the plan as a tree of decisions, resolving dependencies betwee ## Where it fits -`grill-me` is a reach-for-it-anytime standalone — the pre-build stress test you run whenever a plan needs hardening. It is the stateless, user-invoked front door to the [grilling](https://aihero.dev/skills-grilling) primitive; its closest neighbour is [grill-with-docs](https://aihero.dev/skills-grill-with-docs), the stateful sibling that runs the same interview but additionally records the decisions as ADRs and a glossary. If the outcome is a spec you want written down, hand off to [to-prd](https://aihero.dev/skills-to-prd), which synthesises the settled understanding into a PRD without re-interviewing you. When you're unsure which flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. +`grill-me` is a reach-for-it-anytime standalone — the pre-build stress test you run whenever a plan needs hardening. It is the stateless, user-invoked front door to the [grilling](https://aihero.dev/skills-grilling) primitive; its closest neighbour is [grill-with-docs](https://aihero.dev/skills-grill-with-docs), the stateful sibling that runs the same interview but additionally records the decisions as ADRs and a glossary. If the outcome is a spec you want written down, hand off to [to-spec](https://aihero.dev/skills-to-spec), which synthesises the settled understanding into a spec without re-interviewing you. When you're unsure which flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/productivity/grilling.md b/docs/productivity/grilling.md index 8fa5067..8d62b2c 100644 --- a/docs/productivity/grilling.md +++ b/docs/productivity/grilling.md @@ -34,4 +34,4 @@ Keeping the technique in one place means you can also reach for it directly when ## Where it fits -`grilling` is the interview **primitive** under the main build chain: [grill-with-docs](https://aihero.dev/skills-grill-with-docs) runs it to sharpen context before [to-prd](https://aihero.dev/skills-to-prd) writes the spec. When you're unsure which entry point fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. +`grilling` is the interview **primitive** under the main build chain: [grill-with-docs](https://aihero.dev/skills-grill-with-docs) runs it to sharpen context before [to-spec](https://aihero.dev/skills-to-spec) writes the spec. When you're unsure which entry point fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/productivity/handoff.md b/docs/productivity/handoff.md index dce65da..25901a0 100644 --- a/docs/productivity/handoff.md +++ b/docs/productivity/handoff.md @@ -14,7 +14,7 @@ npx skills update handoff `handoff` compacts the current conversation into a **handoff document** — a single write-up a fresh agent can read to pick up the work where you left off. -It does **not** re-state what already lives elsewhere. Anything captured in a PRD, plan, ADR, issue, commit, or diff is referenced by path or URL, never copied. The document carries only the live thread — what you were doing, why, and what's next — and it's saved to your OS's temporary directory, not into the workspace, so it never becomes another artifact to maintain. +It does **not** re-state what already lives elsewhere. Anything captured in a spec, plan, ADR, issue, commit, or diff is referenced by path or URL, never copied. The document carries only the live thread — what you were doing, why, and what's next — and it's saved to your OS's temporary directory, not into the workspace, so it never becomes another artifact to maintain. ## When to reach for it @@ -26,11 +26,11 @@ Reach for this when a conversation has gone long enough that its context is at r - **The live thread** — what's in flight and why, in the conversation's own terms, minus anything already written down elsewhere. - **Suggested skills** — a pointer to the skills the next agent should reach for to continue. -- **References, not copies** — links and paths to the PRDs, plans, ADRs, issues, and diffs that hold the settled detail. +- **References, not copies** — links and paths to the specs, plans, ADRs, issues, and diffs that hold the settled detail. - **Redacted secrets** — API keys, passwords, and PII stripped before the document is written. The idea to hold onto is **compaction**: a handoff is the conversation squeezed down to just its resumable core, so a fresh agent inherits the momentum, not the noise. ## Where it fits -`handoff` is a reach-for-it-anytime standalone — it sits at the seam between two sessions rather than inside a build chain. It pairs naturally with the artifact-producing skills whose output it points at: [to-prd](https://aihero.dev/skills-to-prd), because a finished PRD is exactly the kind of settled detail a handoff references instead of repeating. When you're unsure which skill fits the moment, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. +`handoff` is a reach-for-it-anytime standalone — it sits at the seam between two sessions rather than inside a build chain. It pairs naturally with the artifact-producing skills whose output it points at: [to-spec](https://aihero.dev/skills-to-spec), because a finished spec is exactly the kind of settled detail a handoff references instead of repeating. When you're unsure which skill fits the moment, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/skills/engineering/README.md b/skills/engineering/README.md index 706478b..e23433a 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -11,9 +11,8 @@ Reachable only when you type them (`disable-model-invocation: true`). - **[triage](./triage/SKILL.md)** — Move issues through a state machine of triage roles. - **[improve-codebase-architecture](./improve-codebase-architecture/SKILL.md)** — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. - **[setup-matt-pocock-skills](./setup-matt-pocock-skills/SKILL.md)** — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo. -- **[to-issues](./to-issues/SKILL.md)** — Break any plan, spec, or PRD into independently-grabbable issues using vertical slices. -- **[to-plan](./to-plan/SKILL.md)** — Turn any plan, spec, or PRD into a sequential set of tracer-bullet phases worked one at a time — a single ordered file for a local tracker, or parent-and-sub-issues for a real one. -- **[to-prd](./to-prd/SKILL.md)** — Turn the current conversation into a PRD and publish it to the issue tracker. +- **[to-spec](./to-spec/SKILL.md)** — Turn the current conversation into a spec and publish it to the issue tracker. +- **[to-tickets](./to-tickets/SKILL.md)** — Break any plan, spec, or conversation into a set of tracer-bullet tickets, each declaring its blocking edges — text in a local file, or native blocking links on a real tracker. ## Model-invoked diff --git a/skills/engineering/ask-matt/SKILL.md b/skills/engineering/ask-matt/SKILL.md index bb3a514..d7044e8 100644 --- a/skills/engineering/ask-matt/SKILL.md +++ b/skills/engineering/ask-matt/SKILL.md @@ -20,18 +20,16 @@ The route most work travels. You have an idea and want it built. - **`/prototype`** to answer the question with throwaway code, - **`/handoff`** back what you learned, and reference it from the original idea thread. 3. **Branch — is this a multi-session build?** - - **Yes** → **`/to-prd`** (turn the thread into a PRD), then split it into tracer-bullet slices one of two ways: - - **`/to-issues`** — independently-grabbable issues on your tracker, for **parallel/AFK** agents. Because the issues are independent, **clear context between each one** and kick off **`/implement`** per issue. - - **`/to-plan`** — a **sequential** plan you drive **by hand**, staying in the loop. Publishes to the same tracker, shaped to it: a single ordered `plan.md` for a local tracker, or a parent issue with ordered sub-issues for a real one. Work one phase per fresh context, clearing between them, with **`/implement`**. + - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's an ordered `tickets.md` you work by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **clearing context between each one**. - **No** → **`/implement`** right here, in the same context window. Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point. ### Context hygiene -Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-issues` — so the grilling, PRD, and issues all build on the same thinking. Each `/implement` then starts fresh, working from the issue. +Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-tickets` — so the grilling, spec, and tickets all build on the same thinking. Each `/implement` then starts fresh, working from the ticket. -The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~120k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-issues`, don't push on degraded — `/handoff` and continue in a fresh thread. +The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~120k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-tickets`, don't push on degraded — `/handoff` and continue in a fresh thread. ## On-ramps @@ -39,7 +37,7 @@ A starting situation that generates work, then merges onto the main flow. - **Bugs and requests piling up** → **`/triage`**. It moves issues through triage roles and produces agent-ready issues, which **`/implement`** later picks up. - Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Issues that `/to-issues` produced are already agent-ready, so **don't triage them**. + Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Tickets that `/to-tickets` produced are already agent-ready, so **don't triage them**. - **Something's broken** → **`/diagnosing-bugs`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. It refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the real finding is that there's no good seam to lock the bug down. diff --git a/skills/engineering/implement/SKILL.md b/skills/engineering/implement/SKILL.md index 02b27b2..7a0b11f 100644 --- a/skills/engineering/implement/SKILL.md +++ b/skills/engineering/implement/SKILL.md @@ -1,10 +1,10 @@ --- name: implement -description: "Implement a piece of work based on a PRD or set of issues." +description: "Implement a piece of work based on a spec or set of tickets." disable-model-invocation: true --- -Implement the work described by the user in the PRD or issues. +Implement the work described by the user in the spec or tickets. Use /tdd where possible, at pre-agreed seams. diff --git a/skills/engineering/setup-matt-pocock-skills/SKILL.md b/skills/engineering/setup-matt-pocock-skills/SKILL.md index c42b3f2..612dfe5 100644 --- a/skills/engineering/setup-matt-pocock-skills/SKILL.md +++ b/skills/engineering/setup-matt-pocock-skills/SKILL.md @@ -35,7 +35,7 @@ Assume the user does not know what these terms mean. Each section starts with a **Section A — Issue tracker.** -> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-issues`, `triage`, `to-prd`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo. +> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, `to-spec`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo. Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose that. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer: diff --git a/skills/engineering/to-issues/SKILL.md b/skills/engineering/to-issues/SKILL.md deleted file mode 100644 index 657e311..0000000 --- a/skills/engineering/to-issues/SKILL.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -name: to-issues -description: Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices. -disable-model-invocation: true ---- - -# To Issues - -Break a plan into independently-grabbable issues using vertical slices (tracer bullets). - -The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not. - -## Process - -### 1. Gather context - -Work from whatever is already in the conversation context. If the user passes an issue reference (issue number, URL, or path) as an argument, fetch it from the issue tracker and read its full body and comments. - -### 2. Explore the codebase (optional) - -If you have not already explored the codebase, do so to understand the current state of the code. Issue titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching. - -Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change." - -### 3. Draft the issues - -Break the plan into **tracer bullet** issues, following the **Vertical slice rules**. A **wide refactor** is the exception to that rule — slice it by **expand–contract** instead (see **Wide refactors**). - -### 4. Quiz the user - -Present the proposed breakdown as a numbered list. For each slice, show: - -- **Title**: short descriptive name -- **Blocked by**: which other slices (if any) must complete first -- **User stories covered**: which user stories this addresses (if the source material has them) - -Ask the user: - -- Does the granularity feel right? (too coarse / too fine) -- Are the dependency relationships correct? -- Should any slices be merged or split further? - -Iterate until the user approves the breakdown. - -### 5. Publish the issues to the issue tracker - -For each approved slice, publish a new issue to the issue tracker using the **Issue body template**. These issues are considered ready for AFK agents, so publish them with the correct triage label unless instructed otherwise. - -Publish issues in dependency order (blockers first) so you can reference real issue identifiers. Where the tracker supports it, link each slice to its parent as a native **sub-issue** and wire each blocker as a native **blocking edge** (mechanics in the issue-tracker doc); the `## Parent` and `## Blocked by` body sections are the fallback otherwise. - -Do NOT close or modify any parent issue. - -## Reference - -### Vertical slice rules - -Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer. - -- Each slice delivers a narrow but COMPLETE path through every layer (schema, API, UI, tests) -- A completed slice is demoable or verifiable on its own -- Any prefactoring should be done first - -### Wide refactors - -A **wide refactor** is one mechanical change — rename a column, retype a shared symbol — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own issue blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in an issue blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify issue — green is promised only there. - -### Issue body template - - -## Parent - -A reference to the parent issue on the issue tracker (if the source was an existing issue, otherwise omit this section). - -## What to build - -A concise description of this vertical slice. Describe the end-to-end behavior, not layer-by-layer implementation. - -Avoid specific file paths or code snippets — they go stale fast. Exception: if the `/prototype` skill produced code that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), add a context pointer to where that prototype code lives rather than inlining it. - -## Acceptance criteria - -- [ ] Criterion 1 -- [ ] Criterion 2 -- [ ] Criterion 3 - -## Blocked by - -- A reference to the blocking ticket (if any) - -Or "None - can start immediately" if no blockers. - diff --git a/skills/engineering/to-plan/SKILL.md b/skills/engineering/to-plan/SKILL.md deleted file mode 100644 index 7e0c1cb..0000000 --- a/skills/engineering/to-plan/SKILL.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -name: to-plan -description: Turn a PRD, spec, or the current conversation into a sequential plan of tracer-bullet vertical slices, published to the configured tracker — one ordered file for local, or parent-and-sub-issues for a real tracker. -disable-model-invocation: true ---- - -# To Plan - -Turn a plan, spec, or PRD into a **sequential** plan of vertical slices (tracer bullets) — an ordered list of phases you work through one at a time, in a fresh context per phase. - -This is the sequential, HITL sibling of `/to-issues`. Where `to-issues` produces independently-grabbable issues for parallel agents, `to-plan` produces one ordered sequence you drive by hand, top to bottom. - -The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not. - -## Process - -### 1. Gather context - -Work from whatever is already in the conversation context. If the user passes a reference (a PRD path, an issue number or URL) as an argument, fetch it and read its full body. - -### 2. Explore the codebase (optional) - -If you have not already explored the codebase, do so to understand the current state of the code. Phase titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching. - -Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change." - -### 3. Draft vertical slices - -Break the work into **tracer bullet** phases. - - - -- Each slice cuts a narrow but COMPLETE path through every layer (schema, API, UI, tests) — vertical, NOT a horizontal slice of one layer -- A completed slice is demoable or verifiable on its own -- Each slice is sized to fit in a single fresh context window -- Any prefactoring should be done first - - - -Order the phases in dependency order — each builds on the ones before it. - -### 4. Quiz the user - -Present the proposed breakdown as a numbered list. For each phase, show: - -- **Title**: short descriptive name -- **What it delivers**: the end-to-end behaviour this phase makes work - -Ask the user: - -- Does the granularity feel right? (too coarse / too fine) -- Is the ordering correct — does each phase build on the ones before it? -- Should any phases be merged or split further? - -Iterate until the user approves the breakdown. - -### 5. Publish the plan to the configured tracker - -Publish the approved phases in order. **How** depends on the tracker `/setup-matt-pocock-skills` configured: - -- **Local files** → write one sequential `plan.md` in the repo root, all phases in order, using the file template below. -- **A real issue tracker (GitHub, Linear, …)** → create **one parent issue** for the whole plan, then **one sub-issue per phase, in order**. Use the platform's native sub-issue / child-issue relationship if it supports one; otherwise create sequential issues and set each phase's "Blocked by" to the previous phase. Use the issue template below for the parent and each phase. - -These are worked **sequentially by hand**, not handed to parallel agents, so do NOT apply the ready-for-agent triage label. - - - -# Plan: - -A one-line summary of what this plan builds. Reference the source PRD or spec if there is one. - -## Phases - -Each phase is one tracer bullet — a vertical slice worked in a fresh context, top to bottom. - -### 1. - -**Delivers:** the end-to-end behaviour this phase makes work, from the user's perspective — not a layer-by-layer implementation list. - -- [ ] Acceptance criterion 1 -- [ ] Acceptance criterion 2 - -### 2. - -... - - - - - -**Parent issue** — title: the plan's short name. Body: the one-line summary, a reference to the source PRD/spec, and the ordered list of phase titles. - -**Each phase sub-issue:** - -## What to build - -The end-to-end behaviour this phase makes work, from the user's perspective — not layer-by-layer implementation. - -## Acceptance criteria - -- [ ] Criterion 1 -- [ ] Criterion 2 - -## Blocked by - -The previous phase (omit for the first phase). - - - -In either form, avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits. - -Work the plan one phase at a time with `/implement`, clearing context between phases. diff --git a/skills/engineering/to-prd/SKILL.md b/skills/engineering/to-spec/SKILL.md similarity index 78% rename from skills/engineering/to-prd/SKILL.md rename to skills/engineering/to-spec/SKILL.md index e5f1141..f3cca8d 100644 --- a/skills/engineering/to-prd/SKILL.md +++ b/skills/engineering/to-spec/SKILL.md @@ -1,24 +1,24 @@ --- -name: to-prd -description: Turn the current conversation into a PRD and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed. +name: to-spec +description: Turn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed. disable-model-invocation: true --- -This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know. +This skill takes the current conversation context and codebase understanding and produces a spec (you may know this document as a PRD). Do NOT interview the user — just synthesize what you already know. The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not. ## Process -1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching. +1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching. 2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one. Check with the user that these seams match their expectations. -3. Write the PRD using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage. +3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage. - + ## Problem Statement @@ -66,10 +66,10 @@ A list of testing decisions that were made. Include: ## Out of Scope -A description of the things that are out of scope for this PRD. +A description of the things that are out of scope for this spec. ## Further Notes Any further notes about the feature. - + diff --git a/skills/engineering/to-tickets/SKILL.md b/skills/engineering/to-tickets/SKILL.md new file mode 100644 index 0000000..a26adbe --- /dev/null +++ b/skills/engineering/to-tickets/SKILL.md @@ -0,0 +1,116 @@ +--- +name: to-tickets +description: Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker — edges as text in a local file, or native blocking links on a real tracker. +disable-model-invocation: true +--- + +# To Tickets + +Break a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring the tickets that **block** it. + +The blocking edges are the whole point. They make one artifact read two ways: on a **local file** they're written as text and you work it top-to-bottom by hand; on a **real tracker** they're native blocking links, so any agent can grab a ticket whose blockers are all done — the **frontier** — and several can run at once. The edges live in the ticket either way; the medium only decides whether anything acts on them in parallel. You are producing the artifact, not deciding how it's run. + +The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not. + +## Process + +### 1. Gather context + +Work from whatever is already in the conversation context. If the user passes a reference (a spec path, an issue number or URL) as an argument, fetch it and read its full body and comments. + +### 2. Explore the codebase (optional) + +If you have not already explored the codebase, do so to understand the current state of the code. Ticket titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching. + +Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change." + +### 3. Draft vertical slices + +Break the work into **tracer bullet** tickets. + + + +- Each slice cuts a narrow but COMPLETE path through every layer (schema, API, UI, tests) — vertical, NOT a horizontal slice of one layer +- A completed slice is demoable or verifiable on its own +- Each slice is sized to fit in a single fresh context window +- Any prefactoring should be done first + + + +Give each ticket its **blocking edges** — the other tickets that must complete before it can start. A ticket with no blockers can start immediately. + +**Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change — rename a column, retype a shared symbol — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket — green is promised only there. + +### 4. Quiz the user + +Present the proposed breakdown as a numbered list. For each ticket, show: + +- **Title**: short descriptive name +- **Blocked by**: which other tickets (if any) must complete first +- **What it delivers**: the end-to-end behaviour this ticket makes work + +Ask the user: + +- Does the granularity feel right? (too coarse / too fine) +- Are the blocking edges correct — does each ticket only depend on tickets that genuinely gate it? +- Should any tickets be merged or split further? + +Iterate until the user approves the breakdown. + +### 5. Publish the tickets to the configured tracker + +Publish the approved tickets. **How** depends on the tracker `/setup-matt-pocock-skills` configured — the tickets are the same either way, only the shape of the blocking edges changes: + +- **Local files** → write one `tickets.md` in the repo root, all tickets in dependency order (blockers first), each with its "Blocked by" listing the titles it depends on. Use the file template below. +- **A real issue tracker (GitHub, Linear, …)** → publish one issue per ticket in dependency order (blockers first) so each ticket's blocking edges can reference real identifiers. Use the platform's native blocking / sub-issue relationship where it has one; otherwise set each ticket's "Blocked by" to the blocking issues. Apply the `ready-for-agent` triage label unless instructed otherwise — the tickets are agent-grabbable by construction. + +Do NOT close or modify any parent issue. + + + +# Tickets: + +A one-line summary of what these tickets build. Reference the source spec if there is one. + +Work the **frontier**: any ticket whose blockers are all done. For a purely linear chain that means top to bottom. + +## + +**What to build:** the end-to-end behaviour this ticket makes work, from the user's perspective — not a layer-by-layer implementation list. + +**Blocked by:** the titles of the tickets that gate this one, or "None — can start immediately". + +- [ ] Acceptance criterion 1 +- [ ] Acceptance criterion 2 + +## + +... + + + + + +## Parent + +A reference to the parent issue on the tracker (if the source was an existing issue, otherwise omit this section). + +## What to build + +The end-to-end behaviour this ticket makes work, from the user's perspective — not layer-by-layer implementation. + +## Acceptance criteria + +- [ ] Criterion 1 +- [ ] Criterion 2 + +## Blocked by + +- A reference to each blocking ticket, or "None — can start immediately". + + + +In either form, avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits. + +Work the frontier one ticket at a time with `/implement`, clearing context between tickets. + diff --git a/skills/productivity/handoff/SKILL.md b/skills/productivity/handoff/SKILL.md index ec762d9..043d9e1 100644 --- a/skills/productivity/handoff/SKILL.md +++ b/skills/productivity/handoff/SKILL.md @@ -9,7 +9,7 @@ Write a handoff document summarising the current conversation so a fresh agent c Include a "suggested skills" section in the document, which suggests skills that the agent should invoke. -Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead. +Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead. Redact any sensitive information, such as API keys, passwords, or personally identifiable information. From 09a72ba465bc1d347a0358af049a7f27cd04ff31 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Thu, 2 Jul 2026 11:07:27 +0100 Subject: [PATCH 4/8] refactor(to-tickets): prune no-ops from the two-readings intro Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/engineering/to-tickets/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/engineering/to-tickets/SKILL.md b/skills/engineering/to-tickets/SKILL.md index a26adbe..7246e7b 100644 --- a/skills/engineering/to-tickets/SKILL.md +++ b/skills/engineering/to-tickets/SKILL.md @@ -8,7 +8,7 @@ disable-model-invocation: true Break a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring the tickets that **block** it. -The blocking edges are the whole point. They make one artifact read two ways: on a **local file** they're written as text and you work it top-to-bottom by hand; on a **real tracker** they're native blocking links, so any agent can grab a ticket whose blockers are all done — the **frontier** — and several can run at once. The edges live in the ticket either way; the medium only decides whether anything acts on them in parallel. You are producing the artifact, not deciding how it's run. +The blocking edges make one set of tickets read two ways. On a **local file** they're written as text — work them top-to-bottom by hand. On a **real tracker** they're native blocking links, so any ticket whose blockers are done is on the **frontier**, and several agents can work it at once. The medium only decides whether the edges are acted on in parallel; you produce the artifact, not the run. The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not. From d29732e49f60a71e2036471c8eaa31631bf5151c Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Thu, 2 Jul 2026 11:09:24 +0100 Subject: [PATCH 5/8] refactor(to-tickets): cut the two-readings explainer from SKILL.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It documented what the skill does rather than steering the agent — the publish mechanics it described are already Step 5's instructions, and the conceptual framing already lives in ask-matt and the docs page. Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/engineering/to-tickets/SKILL.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/skills/engineering/to-tickets/SKILL.md b/skills/engineering/to-tickets/SKILL.md index 7246e7b..dceaa73 100644 --- a/skills/engineering/to-tickets/SKILL.md +++ b/skills/engineering/to-tickets/SKILL.md @@ -8,8 +8,6 @@ disable-model-invocation: true Break a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring the tickets that **block** it. -The blocking edges make one set of tickets read two ways. On a **local file** they're written as text — work them top-to-bottom by hand. On a **real tracker** they're native blocking links, so any ticket whose blockers are done is on the **frontier**, and several agents can work it at once. The medium only decides whether the edges are acted on in parallel; you produce the artifact, not the run. - The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not. ## Process From 639df6e7386dfddc739b2aecdeff37a876f2483b Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Mon, 6 Jul 2026 16:17:16 +0100 Subject: [PATCH 6/8] Graduate wayfinder to engineering; unify changesets for v1.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Graduate `wayfinder` out of in-progress into the engineering bucket (plugin.json, top-level + Engineering READMEs under User-invoked, docs page, ask-matt on-ramp, disable-model-invocation). Consolidate the 22 pending changesets into 10 coherent v1.1 entries: one `wayfinder` (rename from decision-mapping + full reframe + graduation), one `grilling`, one `code-review`, one `tdd`; fold the superseded to-issues changeset into unify-to-tickets and drop its stray `` tag. Highest bump is minor → 1.0.1 becomes 1.1.0. Co-Authored-By: Claude Opus 4.8 (1M context) --- .changeset/code-review-promote.md | 5 --- .changeset/code-review.md | 7 +++ .changeset/decision-mapping-task-type.md | 5 --- .changeset/grilling-gate-and-leading-word.md | 5 --- .changeset/grilling.md | 9 ++++ .changeset/review-smell-baseline.md | 5 --- .changeset/tdd-reference-only-seams.md | 7 --- .changeset/tdd-tautological-tests.md | 5 --- .changeset/tdd.md | 9 ++++ .../to-issues-sub-issues-and-prototype.md | 5 --- .changeset/unify-to-tickets.md | 3 +- .changeset/wayfinder-assign-to-claim.md | 7 --- .changeset/wayfinder-collaborative-tracker.md | 9 ---- .changeset/wayfinder-deferred-section.md | 11 ----- .changeset/wayfinder-destination-purpose.md | 7 --- .changeset/wayfinder-grilling-not-self.md | 12 ----- .changeset/wayfinder-map-index.md | 7 --- .../wayfinder-native-blocking-rationale.md | 7 --- .changeset/wayfinder-no-fog-early-exit.md | 9 ---- .changeset/wayfinder-plan-big-work.md | 7 --- .changeset/wayfinder.md | 17 +++++++ .changeset/wayfinding-rename.md | 9 ---- .claude-plugin/plugin.json | 1 + README.md | 1 + docs/engineering/wayfinder.md | 44 +++++++++++++++++++ skills/engineering/README.md | 1 + skills/engineering/ask-matt/SKILL.md | 2 + .../wayfinder/SKILL.md | 1 + skills/in-progress/README.md | 1 - 29 files changed, 94 insertions(+), 124 deletions(-) delete mode 100644 .changeset/code-review-promote.md create mode 100644 .changeset/code-review.md delete mode 100644 .changeset/decision-mapping-task-type.md delete mode 100644 .changeset/grilling-gate-and-leading-word.md create mode 100644 .changeset/grilling.md delete mode 100644 .changeset/review-smell-baseline.md delete mode 100644 .changeset/tdd-reference-only-seams.md delete mode 100644 .changeset/tdd-tautological-tests.md create mode 100644 .changeset/tdd.md delete mode 100644 .changeset/to-issues-sub-issues-and-prototype.md delete mode 100644 .changeset/wayfinder-assign-to-claim.md delete mode 100644 .changeset/wayfinder-collaborative-tracker.md delete mode 100644 .changeset/wayfinder-deferred-section.md delete mode 100644 .changeset/wayfinder-destination-purpose.md delete mode 100644 .changeset/wayfinder-grilling-not-self.md delete mode 100644 .changeset/wayfinder-map-index.md delete mode 100644 .changeset/wayfinder-native-blocking-rationale.md delete mode 100644 .changeset/wayfinder-no-fog-early-exit.md delete mode 100644 .changeset/wayfinder-plan-big-work.md create mode 100644 .changeset/wayfinder.md delete mode 100644 .changeset/wayfinding-rename.md create mode 100644 docs/engineering/wayfinder.md rename skills/{in-progress => engineering}/wayfinder/SKILL.md (99%) diff --git a/.changeset/code-review-promote.md b/.changeset/code-review-promote.md deleted file mode 100644 index fea959d..0000000 --- a/.changeset/code-review-promote.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -Rename the in-progress **`review`** skill to **`code-review`** and promote it from `in-progress/` to the `engineering/` bucket. It now ships in the plugin, is listed in the top-level and Engineering READMEs (Model-invoked), and has a human-facing docs page at `docs/engineering/code-review.md`. The `/implement` skill and docs now point at `/code-review`. diff --git a/.changeset/code-review.md b/.changeset/code-review.md new file mode 100644 index 0000000..1ab2da8 --- /dev/null +++ b/.changeset/code-review.md @@ -0,0 +1,7 @@ +--- +"mattpocock-skills": minor +--- + +Promote and harden **`code-review`**. The in-progress **`review`** skill is renamed to **`code-review`** and moved from `in-progress/` into `engineering/`: it now ships in the plugin, is listed in the top-level and Engineering READMEs (Model-invoked), and has a docs page at `docs/engineering/code-review.md`. The `/implement` skill and docs point at `/code-review`. + +It also gains an always-on **Fowler smell baseline** on its Standards axis — a curated ~12 high-signal "Bad Smells in Code" (Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Repeated Switches, Shotgun Surgery, Divergent Change, Speculative Generality, Message Chains, Middle Man, Refused Bequest) inlined into `SKILL.md` as a fixed baseline alongside whatever the repo documents, not a new third axis. Two binding rules keep it safe: a documented repo standard overrides the baseline, and every smell is reported as a judgement call, never a hard violation. diff --git a/.changeset/decision-mapping-task-type.md b/.changeset/decision-mapping-task-type.md deleted file mode 100644 index db333f1..0000000 --- a/.changeset/decision-mapping-task-type.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -Add a fourth **Task** ticket type to the **`decision-mapping`** skill. Some blockers are neither a decision, a prototype, nor research — just literal manual work that has to happen before the discussion can move forward (moving data, signing up for a third-party service, provisioning access). The agent automates it where it can, otherwise hands the human a precise checklist, and records any resulting facts later tickets depend on. diff --git a/.changeset/grilling-gate-and-leading-word.md b/.changeset/grilling-gate-and-leading-word.md deleted file mode 100644 index 34c8bfd..0000000 --- a/.changeset/grilling-gate-and-leading-word.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -Add a confirmation gate to **`grilling`**: the agent won't enact the plan until you confirm the shared understanding has been reached, turning the skill's existing "shared understanding" completion criterion into an explicit stop-gate. The `description` also recruits the pretrained **`grill`** leading word ("Grill the user relentlessly") to sharpen invocation, and the docs page is re-synced with the new gate behaviour. diff --git a/.changeset/grilling.md b/.changeset/grilling.md new file mode 100644 index 0000000..cd38df6 --- /dev/null +++ b/.changeset/grilling.md @@ -0,0 +1,9 @@ +--- +"mattpocock-skills": minor +--- + +Sharpen **`grilling`** on two fronts. + +**A confirmation gate.** The agent won't enact the plan until you confirm the shared understanding has been reached — turning the skill's existing "shared understanding" completion criterion into an explicit stop-gate. The `description` also recruits the pretrained **`grill`** leading word ("Grill the user relentlessly") to sharpen invocation, and the docs page is re-synced. + +**Facts vs. decisions.** Grilling now splits *facts* (look them up — explore the codebase) from *decisions* (put each one to the human and wait for their answer). The old blanket line — "if a question can be answered by exploring the codebase, explore the codebase instead" — was written for the live-human case, but once another skill runs grilling inside a resolve-the-ticket frame it read as license to answer *decisions* autonomously too. Separating the two keeps a grilling agent from racing ahead and answering its own questions. diff --git a/.changeset/review-smell-baseline.md b/.changeset/review-smell-baseline.md deleted file mode 100644 index d435788..0000000 --- a/.changeset/review-smell-baseline.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"mattpocock-skills": patch ---- - -Give the in-progress **`code-review`** skill an always-on Fowler smell baseline on its Standards axis. A curated ~12 high-signal "Bad Smells in Code" (Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Repeated Switches, Shotgun Surgery, Divergent Change, Speculative Generality, Message Chains, Middle Man, Refused Bequest) are inlined into `SKILL.md` as a fixed baseline alongside whatever the repo documents — not a new third axis. Two binding rules keep it safe: a documented repo standard overrides the baseline, and every smell is reported as a judgement call, never a hard violation. diff --git a/.changeset/tdd-reference-only-seams.md b/.changeset/tdd-reference-only-seams.md deleted file mode 100644 index 6696d46..0000000 --- a/.changeset/tdd-reference-only-seams.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -"mattpocock-skills": patch ---- - -Reshape the `tdd` skill into reference-only. The red → green → refactor loop is anchored by leading words the model already holds, so the step-by-step Workflow was largely restating the loop and duplicating the horizontal-slicing anti-pattern. Dropped the Workflow and per-cycle checklist; folded their one durable idea — vertical slices / tracer bullets — into the Anti-patterns section and a short Rules-of-the-loop list. Introduced **seam** as the leading word for where tests go, collapsing the old Philosophy "public interfaces" prose and the Planning "confirm interface / behaviors" handshake into one rule: test only at pre-agreed seams, confirmed with the user before any test is written. - -Also dropped the refactor stage — TDD is now red → green, not red → green → refactor. Refactoring belongs to the review stage, not the implementation loop, so the refactor rule and `refactoring.md` were removed (its home is the `review` skill). diff --git a/.changeset/tdd-tautological-tests.md b/.changeset/tdd-tautological-tests.md deleted file mode 100644 index 782e9de..0000000 --- a/.changeset/tdd-tautological-tests.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"mattpocock-skills": patch ---- - -Add the **tautological test** anti-pattern to the `tdd` skill. Tests whose assertion is recomputed the way the code computes it pass by construction and give zero confidence — distinct from the implementation-coupling anti-pattern already covered. Added as a peer at the same three sites: a Philosophy principle (expected values must come from an independent source of truth), a per-cycle checklist gate, and a BAD/GOOD example pair in `tests.md`. diff --git a/.changeset/tdd.md b/.changeset/tdd.md new file mode 100644 index 0000000..de5ab0c --- /dev/null +++ b/.changeset/tdd.md @@ -0,0 +1,9 @@ +--- +"mattpocock-skills": patch +--- + +Reshape **`tdd`** into a reference-only skill and add a missing anti-pattern. + +**Reference-only.** The red → green → refactor loop is anchored by leading words the model already holds, so the step-by-step Workflow was largely restating the loop. Dropped the Workflow and per-cycle checklist; folded their one durable idea — vertical slices / tracer bullets — into the Anti-patterns section and a short Rules-of-the-loop list. Introduced **seam** as the leading word for where tests go: test only at pre-agreed seams, confirmed with the user before any test is written. Also dropped the refactor stage — TDD is now red → green; refactoring belongs to the review stage, so the refactor rule and `refactoring.md` moved out (its home is `code-review`). + +**Tautological tests.** Added the tautological-test anti-pattern: a test whose assertion is recomputed the way the code computes it passes by construction and gives zero confidence — distinct from the implementation-coupling anti-pattern already covered. Added as a peer at the same sites: a Philosophy principle (expected values must come from an independent source of truth), a checklist gate, and a BAD/GOOD example pair in `tests.md`. diff --git a/.changeset/to-issues-sub-issues-and-prototype.md b/.changeset/to-issues-sub-issues-and-prototype.md deleted file mode 100644 index 273605c..0000000 --- a/.changeset/to-issues-sub-issues-and-prototype.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -Sharpen how the **`to-issues`** skill records structure. The "What to build" template now adds a context pointer to where the **`/prototype`** skill's code lives, rather than inlining a snippet from it. And publishing now prefers the tracker's **native sub-issues** for parent → slice and **native blocking edges** for `Blocked by` where the tracker supports them (mechanics already live in the issue-tracker doc), keeping the `## Parent` / `## Blocked by` body sections as the fallback. diff --git a/.changeset/unify-to-tickets.md b/.changeset/unify-to-tickets.md index b3ad9f1..0a40de6 100644 --- a/.changeset/unify-to-tickets.md +++ b/.changeset/unify-to-tickets.md @@ -6,5 +6,6 @@ Unify the planning skills. **`to-prd` is renamed to `to-spec`** — "spec" is no `to-tickets` breaks a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring its **blocking edges**. That one artifact reads two ways depending on the tracker `/setup-matt-pocock-skills` configured: a **local file** (`tickets.md`) writes the edges as text and you work it top-to-bottom by hand; a **real tracker** writes them as native blocking links, so any ticket whose blockers are done is on the frontier and several agents can run at once. The edges live in the ticket either way — the medium only decides whether anything acts on them in parallel. +Publishing prefers the tracker's **native sub-issues** for parent → slice and **native blocking edges** for `Blocked by` where the tracker supports them, keeping the `## Parent` / `## Blocked by` body sections as the fallback. The "What to build" template points at where a `/prototype`'s code lives rather than inlining a snippet from it. + `ask-matt`'s main flow now routes `idea → /to-spec → /to-tickets → /implement`, and there are human-facing docs pages at `docs/engineering/to-spec.md` and `docs/engineering/to-tickets.md`. - diff --git a/.changeset/wayfinder-assign-to-claim.md b/.changeset/wayfinder-assign-to-claim.md deleted file mode 100644 index 02f3697..0000000 --- a/.changeset/wayfinder-assign-to-claim.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -Change **`wayfinder`**'s claim mechanism from a label to an assignee. - -A session now **claims** a ticket by assigning it to the dev driving the map, rather than setting a `wayfinder:claimed` label. The assignee _is_ the claim — an open, unassigned ticket is unclaimed — which reads more naturally in GitHub's own UI and frees the label vocabulary to `wayfinder:` alone. The *claim* leading word and its "first, before any work" rationale are unchanged; only the physical expression moved. diff --git a/.changeset/wayfinder-collaborative-tracker.md b/.changeset/wayfinder-collaborative-tracker.md deleted file mode 100644 index df96ae0..0000000 --- a/.changeset/wayfinder-collaborative-tracker.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -Make **`wayfinder`** collaborative by moving the map off a local Markdown file and onto the repo's issue tracker. - -The map is now a single `wayfinder:map` issue whose tickets are its child issues — one shared URL the whole team can watch and comment on. Blocking, claiming (`wayfinder:claimed`), and the frontier query all use native tracker semantics, so a session loads the map at low resolution (Notes + one context pointer per closed ticket + Fog prose) and zooms into individual tickets on demand, instead of loading the whole map every time. - -Wayfinder stays tracker-agnostic: the per-tracker mechanics live behind a pointer in `docs/agents/issue-tracker.md`, so `setup-matt-pocock-skills` now seeds a "Wayfinding operations" section for GitHub, GitLab, and local-markdown. Absent that doc, Wayfinder defaults to local-markdown. diff --git a/.changeset/wayfinder-deferred-section.md b/.changeset/wayfinder-deferred-section.md deleted file mode 100644 index 457c64c..0000000 --- a/.changeset/wayfinder-deferred-section.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -Give **`wayfinder`** a first-class notion of **out of scope**, separate from fog. - -Fog and out-of-scope were conflated under one `## Fog` map section, gated by different things: fog by *knowledge* (can't specify it yet — in scope, unripe, graduates as the frontier advances), out-of-scope by *scope* (beyond the destination — never graduates). Cramming both under "Fog" made out-of-scope work read as takeable frontier (an unblocked, unclaimed item is indistinguishable from a live ticket). - -Now the map body has two plainly-named sections — **`## Not yet specified`** and **`## Out of scope`** — and the skill's prose splits to match: the **Fog of war** section teaches only the not-yet-specified bucket and keeps the two-way *fog-or-ticket* sharpness test, while a new **Out of scope** section owns the scope axis (beyond the destination, closed not graduating, returns only as a fresh effort if the destination is redrawn). Charting and working-the-map now rule a beyond-destination ticket out of scope — close it, one line in *Out of scope* — rather than leaving it on the frontier or logging it in *Decisions so far*. - -The **fog of war** leading word is retained: it names the concept and drives the graduate-the-fog behavior in the prose; only the human-facing map headings go to plain language. diff --git a/.changeset/wayfinder-destination-purpose.md b/.changeset/wayfinder-destination-purpose.md deleted file mode 100644 index 5bbe265..0000000 --- a/.changeset/wayfinder-destination-purpose.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -Sharpen **`wayfinder`**'s top-level purpose around **destination** as the leading word: wayfinding finds the *way* to a destination, it doesn't charge at building it. - -The opening now states that the destination varies per effort — a spec to hand off and iterate, a decision to lock before planning, or a change made in place like a data-structure migration — and that naming it is the first act of charting, because it shapes every ticket. The map body gains a `## Destination` field that every session orients to before choosing a ticket, and triage's first step now pins the destination before any ticket exists. The stray `goal` mentions in the description and Fog section are unified onto `destination`. diff --git a/.changeset/wayfinder-grilling-not-self.md b/.changeset/wayfinder-grilling-not-self.md deleted file mode 100644 index 8dbdd75..0000000 --- a/.changeset/wayfinder-grilling-not-self.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -"mattpocock-skills": patch ---- - -Stop **`wayfinder`** grilling *itself* instead of the human, and classify ticket types by **HITL** / **AFK**. - -Students reported `/wayfinder` picking a **grilling** ticket and answering its own questions rather than turning to the human. Root cause: **`grilling`** carried a line written for the live-human case — "If a question can be answered by exploring the codebase, explore the codebase instead" — which, once `wayfinder` runs grilling inside a resolve-the-ticket frame, reads as license to answer questions autonomously and race the ticket to "resolved". - -Two changes: - -- **`grilling`** now splits *facts* (look them up) from *decisions* (put each one to the human and wait for their answer). -- **`wayfinder`** labels every ticket type **HITL** (human in the loop — Prototype, Grilling) or **AFK** (agent alone — Research; Task is either). A HITL ticket only resolves through the live exchange, so the "wait for the human" behaviour falls out of the label instead of being spelled out per type — a grilling agent that answers its own questions has, by definition, broken HITL. diff --git a/.changeset/wayfinder-map-index.md b/.changeset/wayfinder-map-index.md deleted file mode 100644 index f026c8d..0000000 --- a/.changeset/wayfinder-map-index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -Make **`wayfinder`**'s no-duplication contract explicit: the map is an **index**, not a store. - -Adopting "index" as the leading word for the map's role fixes two duplication risks. The map now states up front that a decision lives in exactly one place — its ticket — so it only ever gists and links, never restates the answer (previously this rule was implied inside an HTML comment in the map-body template). And graduating fog into a ticket now clears the graduated patch from the Fog, so a suspected question can't linger in both places at once. diff --git a/.changeset/wayfinder-native-blocking-rationale.md b/.changeset/wayfinder-native-blocking-rationale.md deleted file mode 100644 index bba5264..0000000 --- a/.changeset/wayfinder-native-blocking-rationale.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -"mattpocock-skills": patch ---- - -Sharpen Wayfinder's blocking rule to prefer the tracker's native dependency relationship, and update the GitHub and GitLab issue-tracker templates to match. - -Native blocking is essential rather than cosmetic: it renders the frontier visually in the tracker's own UI, so the human sees what's takeable at a glance without opening the map. `wayfinder`'s SKILL.md now states that preference and rationale; the GitHub template spells out the native issue-dependencies recipe (`gh api .../dependencies/blocked_by`, frontier query on `issue_dependencies_summary.blocked_by`), and the GitLab template names the native `/blocked_by` blocking link (Premium/Ultimate) with the body-convention fallback. Both keep the body fallback for trackers that lack native blocking. diff --git a/.changeset/wayfinder-no-fog-early-exit.md b/.changeset/wayfinder-no-fog-early-exit.md deleted file mode 100644 index f8e685a..0000000 --- a/.changeset/wayfinder-no-fog-early-exit.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -"mattpocock-skills": patch ---- - -Restore **`wayfinder`**'s early exit when the frontier grilling turns up no fog. - -The skill used to have a **Skipping The Decision Map** section: if the opening grilling surfaced no fog of war, there was no map to build, so it offered to skip straight to implementing. That clause was demoted to a parenthetical inside the Handoff section, then deleted as collateral when Handoff was removed — never an intentional cut. - -It's back, co-located in **Chart the map** step 2 (Map the frontier), where the fog/no-fog outcome is actually determined: if breadth-first grilling surfaces no fog — the journey is small enough for one session — you don't need a map, so stop and ask the user how they'd like to proceed. The ask, rather than an auto-skip, is preserved from the original. diff --git a/.changeset/wayfinder-plan-big-work.md b/.changeset/wayfinder-plan-big-work.md deleted file mode 100644 index 07e01ee..0000000 --- a/.changeset/wayfinder-plan-big-work.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -Reframe **`wayfinder`**'s description around the work it's for: planning a huge chunk of work, more than one agent session can hold. - -The description does the skill's invocation work, so it now leads with the trigger that actually reaches for Wayfinder — a big effort you need to break down — instead of the softer "chart a route through a foggy problem". The skill body and fog-of-war mechanic are unchanged. diff --git a/.changeset/wayfinder.md b/.changeset/wayfinder.md new file mode 100644 index 0000000..3ce7de6 --- /dev/null +++ b/.changeset/wayfinder.md @@ -0,0 +1,17 @@ +--- +"mattpocock-skills": minor +--- + +Graduate and reframe **`wayfinder`** — the skill for planning a huge chunk of work, more than one agent session can hold. It moves out of `in-progress/` into `engineering/` (plugin entry, top-level + Engineering READMEs under **User-invoked**, a docs page at `docs/engineering/wayfinder.md`, and a route in `ask-matt`), landing as a mature skill. The rename and reframe that got it there: + +- **`decision-mapping` is renamed to `wayfinder`**, invoked as `/wayfinder`. "Decision map" was jargony and inaccurate — only one ticket type is actually a decision. The reframe charts a route through a foggy problem instead, giving one coherent leading-word frame — **fog of war**, **frontier**, **the map** — rather than an invented term layered on top. +- **Destination as the leading word.** Wayfinding finds the *way* to a destination; it doesn't charge at building it. Naming the destination is the first act of charting — it fixes the scope and shapes every ticket — so the map gains a `## Destination` field every session orients to, and triage pins it before any ticket exists. +- **Plan, don't do.** The map produces **decisions, not deliverables**; it's done when nothing is left to decide before someone builds the thing. An effort can override this in its Notes. +- **The map is an index, not a store.** A decision lives in exactly one place — its ticket — so the map only gists and links, never restates; graduating fog into a ticket clears the graduated patch so nothing lingers in two places. +- **Collaborative by default.** The map moves off a local Markdown file onto the repo's issue tracker: a single `wayfinder:map` issue whose tickets are its child issues — one shared URL the team can watch. Sessions load the map at low resolution and zoom into tickets on demand. Wayfinder stays tracker-agnostic (GitHub, GitLab, local-markdown) behind a pointer in `docs/agents/issue-tracker.md`, and `setup-matt-pocock-skills` seeds the "Wayfinding operations" section. +- **Claim by assignment, not a label.** A session claims a ticket by assigning it to the driving dev — the assignee *is* the claim — freeing the label vocabulary to `wayfinder:` alone. +- **Native blocking.** Blocking prefers the tracker's native dependency relationship, which renders the frontier visually in the tracker's own UI so the human sees what's takeable without opening the map. GitHub and GitLab templates spell out the native recipe, with a body-convention fallback. +- **Fog vs. out of scope, split.** Two plainly-named map sections — `## Not yet specified` (in-scope fog that graduates as the frontier advances) and `## Out of scope` (work ruled beyond the destination, closed, never graduating) — so beyond-destination work no longer reads as takeable frontier. +- **A fourth `task` ticket type.** For literal manual work that blocks a decision (provisioning access, moving data, signing up for a service) — the one type that *does* rather than decides, earning its place by unblocking a decision. +- **HITL / AFK ticket classification.** Every ticket type is **HITL** (human in the loop — grilling, prototype) or **AFK** (agent alone — research; task is either). A HITL ticket only resolves through the live exchange, so "wait for the human" falls out of the label — a grilling agent that answers its own questions has, by definition, broken HITL. (This fixes students' reports of `/wayfinder` grilling *itself* instead of the human.) +- **No-fog early exit restored.** If the opening breadth-first grilling surfaces no fog, the journey is small enough for one session — so it stops and asks how you'd like to proceed rather than building a map nobody needs. diff --git a/.changeset/wayfinding-rename.md b/.changeset/wayfinding-rename.md deleted file mode 100644 index c6c0d7b..0000000 --- a/.changeset/wayfinding-rename.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -"mattpocock-skills": minor ---- - -Rename the **`decision-mapping`** skill to **`wayfinder`**, invoked as `/wayfinder`. - -"Decision map" was jargony and inaccurate — only one of the skill's four ticket types (Grilling) is actually a decision. The reframe charts a route through a foggy problem, resolving investigation tickets one at a time until the way to the goal is clear. This makes one coherent leading-word frame (fog of war / frontier / the map) instead of mixing an invented term on top of it. - -Also a pruning pass: unified `node`→`ticket`, bound "the frontier" to the unblocked tickets, dropped the duplicated "one question at a time" (owned by `/grilling`), and trimmed intro no-ops. diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index e32cc25..db81962 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -10,6 +10,7 @@ "./skills/engineering/tdd", "./skills/engineering/to-spec", "./skills/engineering/to-tickets", + "./skills/engineering/wayfinder", "./skills/engineering/implement", "./skills/engineering/prototype", "./skills/engineering/research", diff --git a/README.md b/README.md index 8095656..cdfe968 100644 --- a/README.md +++ b/README.md @@ -156,6 +156,7 @@ Skills I use daily for code work. - **[setup-matt-pocock-skills](./skills/engineering/setup-matt-pocock-skills/SKILL.md)** — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo before using the other engineering skills. - **[to-spec](./skills/engineering/to-spec/SKILL.md)** — Turn the current conversation into a spec and publish it to the issue tracker. No interview — just synthesizes what you've already discussed. - **[to-tickets](./skills/engineering/to-tickets/SKILL.md)** — Break any plan, spec, or conversation into a set of tracer-bullet tickets, each declaring its blocking edges — written as text in a local file, or as native blocking links on a real tracker. +- **[wayfinder](./skills/engineering/wayfinder/SKILL.md)** — Plan a huge chunk of work, more than one agent session can hold, as a shared map of investigation tickets on the issue tracker — resolve them one at a time until the way to the destination is clear. **Model-invoked** diff --git a/docs/engineering/wayfinder.md b/docs/engineering/wayfinder.md new file mode 100644 index 0000000..3f06254 --- /dev/null +++ b/docs/engineering/wayfinder.md @@ -0,0 +1,44 @@ +Quickstart: + +```bash +npx skills add mattpocock/skills --skill=wayfinder +``` + +```bash +npx skills update wayfinder +``` + +[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/wayfinder) + +## What it does + +`wayfinder` takes an effort too big for one agent session — wrapped in fog, where the way from here to the goal isn't visible yet — and charts it as a **shared map** of investigation tickets on your issue tracker, then resolves them one at a time until the way is clear. It **plans, it doesn't do**: every ticket resolves a decision, and the map is done when nothing is left to decide before someone goes and builds the thing — so it produces decisions, not deliverables. + +## When to reach for it + +You invoke this by typing `/wayfinder` — the agent won't reach for it on its own. + +Reach for it when an effort is **more than one agent session can hold** and the route to its **destination** is still foggy — you can feel the shape of the work but can't yet write it down as a spec or a plan. For turning an *already-clear* thread into a spec, use [to-spec](https://aihero.dev/skills-to-spec); for slicing an already-understood plan into buildable tickets, use [to-tickets](https://aihero.dev/skills-to-tickets). Wayfinder sits upstream of both: it's what you run when there's too much fog to spec directly. + +## Prerequisites + +The map and its tickets live on the repo's issue tracker, so wayfinder needs the tracker wiring that [setup-matt-pocock-skills](https://aihero.dev/skills-setup-matt-pocock-skills) lays down — it seeds a "Wayfinding operations" section describing how the map, child tickets, blocking, and frontier queries are expressed for GitHub, GitLab, or local-markdown. Absent that doc, wayfinder defaults to a local-markdown map. + +## The map is an index, fog is the frontier + +The **map** is a single `wayfinder:map` issue whose tickets are its child issues — one shared URL the whole team can watch. It's an **index, not a store**: each decision lives in exactly one place (its ticket), and the map only gists and links, never restates. A session loads the map at low resolution and zooms into individual tickets on demand. + +Beyond the live tickets lies the **fog of war** — decisions you can tell are coming but can't yet pin down. The test for whether something is a ticket or still fog is whether you can *state the question precisely now*, not whether you can answer it. Resolving a ticket clears the fog ahead of it, **graduating** whatever's now specifiable into fresh tickets. The **frontier** is the open, unblocked, unclaimed tickets — the edge of the known — and it's what the tracker's native blocking renders visually, so you see what's takeable without opening the map. Fog only gathers *toward* the **destination**; work past it is ruled **out of scope**, closed, never graduating. + +Every ticket is **HITL** (human in the loop — grilling, prototype) or **AFK** (agent alone — research); a HITL ticket only resolves through a live exchange, so the agent never answers its own questions. + +## It's working if + +- Naming the **destination** is the first act — before any ticket exists — because it fixes the scope every ticket is measured against. +- One map is one `wayfinder:map` issue; tickets are its child issues, referred to by **name**, never a bare `#42`. +- A session resolves **at most one ticket**, records the answer as a resolution comment, closes the ticket, and appends a one-line pointer to *Decisions so far*. +- If the opening grill surfaces **no fog**, it stops and tells you the journey is small enough to skip the map. + +## Where it fits + +`wayfinder` is a big-idea **on-ramp**: an effort too large and foggy to spec in one sitting generates a cleared map of decisions, which then merges onto the main build flow. When the fog is pushed back and the way is clear, hand off to [to-spec](https://aihero.dev/skills-to-spec) to schedule the multi-session build (or, if the effort turned out small, implement directly). It leans on [grilling](https://aihero.dev/skills-grilling) and [domain-modeling](https://aihero.dev/skills-domain-modeling) to resolve individual tickets, and on [prototype](https://aihero.dev/skills-prototype) and [research](https://aihero.dev/skills-research) for the ticket types that need them. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/skills/engineering/README.md b/skills/engineering/README.md index e23433a..edd212c 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -13,6 +13,7 @@ Reachable only when you type them (`disable-model-invocation: true`). - **[setup-matt-pocock-skills](./setup-matt-pocock-skills/SKILL.md)** — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo. - **[to-spec](./to-spec/SKILL.md)** — Turn the current conversation into a spec and publish it to the issue tracker. - **[to-tickets](./to-tickets/SKILL.md)** — Break any plan, spec, or conversation into a set of tracer-bullet tickets, each declaring its blocking edges — text in a local file, or native blocking links on a real tracker. +- **[wayfinder](./wayfinder/SKILL.md)** — Plan a huge chunk of work — more than one agent session can hold — as a shared map of investigation tickets on the issue tracker, resolved one at a time until the way to the destination is clear. ## Model-invoked diff --git a/skills/engineering/ask-matt/SKILL.md b/skills/engineering/ask-matt/SKILL.md index d7044e8..8d90a38 100644 --- a/skills/engineering/ask-matt/SKILL.md +++ b/skills/engineering/ask-matt/SKILL.md @@ -41,6 +41,8 @@ A starting situation that generates work, then merges onto the main flow. - **Something's broken** → **`/diagnosing-bugs`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. It refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the real finding is that there's no good seam to lock the bug down. +- **A huge, foggy effort — too big for one session** → **`/wayfinder`**. When the way from here to the destination isn't visible yet, it charts a **shared map** of investigation tickets on the issue tracker and resolves them one at a time — producing **decisions, not deliverables** — until the fog is pushed back and the way is clear. Then it merges onto the main flow at **`/to-spec`** (or, if the effort turned out small enough, straight to **`/implement`**). Where **`/grill-with-docs`** sharpens an idea you can hold in one session, wayfinder is for the idea you can't. + ## Codebase health Not feature work — upkeep. diff --git a/skills/in-progress/wayfinder/SKILL.md b/skills/engineering/wayfinder/SKILL.md similarity index 99% rename from skills/in-progress/wayfinder/SKILL.md rename to skills/engineering/wayfinder/SKILL.md index cef653c..2bce062 100644 --- a/skills/in-progress/wayfinder/SKILL.md +++ b/skills/engineering/wayfinder/SKILL.md @@ -1,6 +1,7 @@ --- name: wayfinder description: Plan a huge chunk of work — more than one agent session can hold — as a shared map of investigation tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear. +disable-model-invocation: true --- A loose idea has arrived — too big for one agent session, and wrapped in fog: the way from here to the **destination** isn't visible yet. Wayfinding is about finding that way, not charging at the destination. This skill charts the way as a **shared map** on the repo's issue tracker, then works its tickets one at a time until the route is clear. diff --git a/skills/in-progress/README.md b/skills/in-progress/README.md index 8b91783..68345c2 100644 --- a/skills/in-progress/README.md +++ b/skills/in-progress/README.md @@ -2,7 +2,6 @@ Skills that are still being developed. They're not ready to ship — expect rough edges, breaking changes, and abandoned experiments. They're excluded from the plugin and the top-level README until they graduate to a stable bucket. -- **[wayfinder](./wayfinder/SKILL.md)** — Chart a route through a foggy problem — turn a loose idea into a map of investigation tickets and resolve them one at a time until the way to the goal is clear. User-invoked. - **[loop-me](./loop-me/SKILL.md)** — Grill yourself into implementable workflow specs over multiple sessions, using the current directory as a stateful workspace. User-invoked. - **[wizard](./wizard/SKILL.md)** — Generate an interactive bash wizard that walks a human through a manual procedure (setup, a one-off migration, a state transition) — opening URLs, capturing values, writing `.env` and GitHub Actions secrets. User-invoked. - **[writing-beats](./writing-beats/SKILL.md)** — Shape an article as a journey of beats, choose-your-own-adventure style. Pick a starting beat, write only that beat, then pivot to the next, until the article reaches a natural end. From 0557d57579d9b3d39839fdaf8d4a6542b17539ce Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Tue, 7 Jul 2026 15:19:32 +0100 Subject: [PATCH 7/8] docs: settle wayfinder as a situational on-ramp, not the main entry flow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The grill-led idea→ship chain stays the documented front door; wayfinder is a situational on-ramp (greenfield / huge feature build), reserving "new default spine" for a potential v2. - ask-matt router: name wayfinder's concrete triggers - grill-me / grill-with-docs: signpost up to wayfinder as the too-big-for-one-session on-ramp Resolves the main-flow decision on the Skills v1.1 wayfinder map (#120). Co-Authored-By: Claude Opus 4.8 (1M context) --- .changeset/wayfinder-situational-onramp.md | 5 +++++ docs/engineering/grill-with-docs.md | 2 +- docs/productivity/grill-me.md | 2 +- skills/engineering/ask-matt/SKILL.md | 2 +- 4 files changed, 8 insertions(+), 3 deletions(-) create mode 100644 .changeset/wayfinder-situational-onramp.md diff --git a/.changeset/wayfinder-situational-onramp.md b/.changeset/wayfinder-situational-onramp.md new file mode 100644 index 0000000..275f99d --- /dev/null +++ b/.changeset/wayfinder-situational-onramp.md @@ -0,0 +1,5 @@ +--- +"mattpocock-skills": minor +--- + +Settle wayfinder's place in the docs as a **situational on-ramp**, not the new main entry flow — the grill-led *idea → ship* chain stays the front door (crowning wayfinder as the default spine is a v2-sized move, not a 1.1). The **`ask-matt`** router now names wayfinder's concrete triggers — a greenfield project or a huge feature build, too big for one session — and the two grill front doors (**`grill-me`**, **`grill-with-docs`**) signpost *up* to wayfinder for the effort that's too big to hold in one session, so the on-ramp is discoverable from where a reader actually starts. diff --git a/docs/engineering/grill-with-docs.md b/docs/engineering/grill-with-docs.md index e8c4abc..77c1747 100644 --- a/docs/engineering/grill-with-docs.md +++ b/docs/engineering/grill-with-docs.md @@ -20,7 +20,7 @@ The grilling **leaves a paper trail**. A plain interview sharpens your thinking You invoke this by typing `/grill-with-docs` — the agent won't reach for it on its own. -Reach for it at the very start of a change, when the plan is still fuzzy and the domain language isn't settled, and you want to stress-test both before any code exists. If you only want the interview and don't need the artifacts, use [grilling](https://aihero.dev/skills-grilling); if the plan is already clear and you just need to pin down or record terminology, use [domain-modeling](https://aihero.dev/skills-domain-modeling). +Reach for it at the very start of a change, when the plan is still fuzzy and the domain language isn't settled, and you want to stress-test both before any code exists. If you only want the interview and don't need the artifacts, use [grilling](https://aihero.dev/skills-grilling); if the plan is already clear and you just need to pin down or record terminology, use [domain-modeling](https://aihero.dev/skills-domain-modeling). And if the change is too big to hold in one session and its route is still foggy — a greenfield project, a huge feature build — start upstream with [wayfinder](https://aihero.dev/skills-wayfinder): it charts the effort as a map of decisions, then hands back to this main flow once the way is clear. ## Prerequisites diff --git a/docs/productivity/grill-me.md b/docs/productivity/grill-me.md index 7a8e3fb..5a2e6c0 100644 --- a/docs/productivity/grill-me.md +++ b/docs/productivity/grill-me.md @@ -20,7 +20,7 @@ It asks **one question at a time** and waits. It never dumps a batch of question You invoke this by typing `/grill-me` — the agent won't reach for it on its own. -Reach for it before you build, when a plan feels roughly right but you can sense unresolved decisions hiding in it — the moment you want the soft spots found and forced into the open. If you want that same interrogation to also leave a paper trail of ADRs and a glossary behind, use [grill-with-docs](https://aihero.dev/skills-grill-with-docs) instead. +Reach for it before you build, when a plan feels roughly right but you can sense unresolved decisions hiding in it — the moment you want the soft spots found and forced into the open. If you want that same interrogation to also leave a paper trail of ADRs and a glossary behind, use [grill-with-docs](https://aihero.dev/skills-grill-with-docs) instead. And if the effort is too big to hold in one session and the route to the goal is still foggy — a greenfield project, a huge feature build — start further upstream with [wayfinder](https://aihero.dev/skills-wayfinder), which charts it as a map of decisions first and then merges back into this flow. ## The design tree diff --git a/skills/engineering/ask-matt/SKILL.md b/skills/engineering/ask-matt/SKILL.md index 8d90a38..cc1866a 100644 --- a/skills/engineering/ask-matt/SKILL.md +++ b/skills/engineering/ask-matt/SKILL.md @@ -41,7 +41,7 @@ A starting situation that generates work, then merges onto the main flow. - **Something's broken** → **`/diagnosing-bugs`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. It refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the real finding is that there's no good seam to lock the bug down. -- **A huge, foggy effort — too big for one session** → **`/wayfinder`**. When the way from here to the destination isn't visible yet, it charts a **shared map** of investigation tickets on the issue tracker and resolves them one at a time — producing **decisions, not deliverables** — until the fog is pushed back and the way is clear. Then it merges onto the main flow at **`/to-spec`** (or, if the effort turned out small enough, straight to **`/implement`**). Where **`/grill-with-docs`** sharpens an idea you can hold in one session, wayfinder is for the idea you can't. +- **A huge, foggy effort — a greenfield project or a huge feature build, too big for one session** → **`/wayfinder`**. When the way from here to the destination isn't visible yet, it charts a **shared map** of investigation tickets on the issue tracker and resolves them one at a time — producing **decisions, not deliverables** — until the fog is pushed back and the way is clear. Then it merges onto the main flow at **`/to-spec`** (or, if the effort turned out small enough, straight to **`/implement`**). Where **`/grill-with-docs`** sharpens an idea you can hold in one session, wayfinder is for the idea you can't. ## Codebase health From d6e21b661d2b322d5cd27ee054bf99c50f3fcfe8 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 8 Jul 2026 14:01:47 +0100 Subject: [PATCH 8/8] docs: list implement in the README's engineering user-invoked skills implement is the central Main Flow step but was missing from the public Reference list. Add it after to-tickets. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index cdfe968..1b290f8 100644 --- a/README.md +++ b/README.md @@ -156,6 +156,7 @@ Skills I use daily for code work. - **[setup-matt-pocock-skills](./skills/engineering/setup-matt-pocock-skills/SKILL.md)** — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo before using the other engineering skills. - **[to-spec](./skills/engineering/to-spec/SKILL.md)** — Turn the current conversation into a spec and publish it to the issue tracker. No interview — just synthesizes what you've already discussed. - **[to-tickets](./skills/engineering/to-tickets/SKILL.md)** — Break any plan, spec, or conversation into a set of tracer-bullet tickets, each declaring its blocking edges — written as text in a local file, or as native blocking links on a real tracker. +- **[implement](./skills/engineering/implement/SKILL.md)** — Build the work described by a spec or set of tickets, driving `/tdd` at pre-agreed seams and closing out with `/code-review` before committing. - **[wayfinder](./skills/engineering/wayfinder/SKILL.md)** — Plan a huge chunk of work, more than one agent session can hold, as a shared map of investigation tickets on the issue tracker — resolve them one at a time until the way to the destination is clear. **Model-invoked**