diff --git a/matt-pocock-skills-v1-1-changes.md b/matt-pocock-skills-v1-1-changes.md new file mode 100644 index 0000000..6ef5e08 --- /dev/null +++ b/matt-pocock-skills-v1-1-changes.md @@ -0,0 +1,117 @@ +--- +type: reference +title: Matt Pocock skills repo — v1.1 changes +summary: What changed in mattpocock/skills v1.1 — skill renames (to-prd→to-spec, to-issues→to-tickets), new lifecycle skills (implement, wayfinder, research, prototype), refactor-smell additions to code-review, and TDD simplified to red-green only. +tags: + - type/reference + - tool/mattpocock-skills + - domain/agent-skills + - domain/sdlc-workflow +scope: global +last_updated: 2026-07-14 +date: 2026-07-14 +source: cc-os +--- + +Source: transcript of Matt Pocock's YouTube video announcing v1.1 of the `mattpocock/skills` +repo (merged live during the video). Captured while cc-os was evaluating whether/how to pull +v1.1 changes into its own marketplace skills. + +## Renames + +- **`to-prd` → `to-spec`** — what the skill produced was never a true PRD; "specification" is + the broader, more accurate term (can be technical, non-technical, or a blend). +- **`to-issues` → `to-tickets`** — "issues" felt biased toward GitHub/Linear terminology. + New mental model: a **spec** defines the destination; **tickets** are the journey to enact it. +- Migration note: old installs won't auto-update on rename. Run + `npx skills@latest add mattpocock/skills` and manually re-check the skills folder for + leftover old-named skills — the installer won't detect that `to-prd` became `to-spec`. + +## Grilling skill fixes + +Shared reference "grilling" skill (used by `grill-me` and `grill-with-docs`) got three fixes: +1. Sharpened "asking multiple questions at once is bewildering" — models were still + occasionally asking multiple questions despite prior one-at-a-time direction. +2. Added an explicit confirmation gate: "do not enact the plan until I confirm we've reached + a shared understanding" — some models were skipping straight to implementation after + grilling ended. +3. Fixed the model "grilling itself" (answering its own questions by exploring the codebase + instead of asking the user), notably with Fable — fixed by distinguishing **facts** + (agent finds by exploring code) from **decisions** (must come from the user) in the wording. + +## New end-to-end lifecycle flow + +Previously the skill set was "primarily a planning process" with no implementation hand-holding. +v1.1 adds a full flow: + +1. **Grill** (via `grill-with-docs` or the new `wayfinder`) → produces a glossary + ADRs. +2. **`to-spec`** — turns grilled material into a spec (the destination). +3. **`to-tickets`** — splits the spec into individually-workable tickets. +4. **`implement`** (new, deliberately minimal) — "Implement the work described by the user in + the spec or tickets. Use TDD where possible at pre-agreed seams. Run type checking + regularly. Single test files regularly. Full test sweep once at the end. Once done, use + code review to review the work and then commit your work to the current branch." +5. `implement` calls **`code-review`** automatically, then commits. + +## code-review: refactor-smell axis + +`code-review` runs two axes as **parallel sub-agents**: +1. **Standards axis** — checks code against a repo's own `coding-standards.md`-type file + (Matt's opinion: coding standards belong in a separate file, not folded into + `AGENTS.md`/`CLAUDE.md`, precisely because code review is where they're most useful). +2. **Spec axis** — does the code faithfully implement the originating issue/PRD/spec? + +New in v1.1: incorporates Martin Fowler's *Refactoring* smell taxonomy (mysterious name, +duplicated code, feature envy, data clumps, primitive obsession, repeated switches, divergent +change, speculative generality, message chains, middleman, etc.) — just *naming* the smells in +the prompt is enough to reliably surface them, since they're deep in the model's training +prior. Matt reports this was "outrageously useful" after a couple weeks of use, for ~10 lines +of added prompt. + +## New skill: wayfinder + +For plans too big for one agent session (would blow past context/"smart zone"). Positioned as +a **replacement for `grill-with-docs`** in those cases — Matt's explicit default recommendation +is to reach for wayfinder over `grill-with-docs` whenever the plan is large. + +- Charts the plan as a shared map on the repo's **issue tracker** (GitHub issues), with + sub-issues tracking individual decisions and blocking relationships between them, each + sized to one agent session. +- Ticket types: **research** (AFK — agent researches, returns with findings), **grilling** + (needs a grilling session), **prototype** (build a cheap concrete artifact — UI or logic — + when "how should it look/behave" is a key question; recommended for anything touching + front-end code), **tasks** (config/provisioning/data-moving — mechanical, not AI-automatable). +- Once all tickets close, the accumulated map feeds into `to-spec` as normal. +- Advantage claimed over `grill-with-docs`: removes the anxiety of manually managing + session/context limits — "I just get to close a session, open up the next wayfinder ticket." + Saved in GitHub so it's collaborative/shareable across a team. + +## New supporting skills + +- **`research`** — spins up a background agent to investigate a question against primary + sources, writes findings to a markdown file matching the repo's existing note convention. + Usable standalone or as a wayfinder ticket type. +- **`prototype`** — now **model-invoked** (so wayfinder can call it directly). Offers a choice + between a **logic** prototype and a **UI/state** prototype. + +## TDD skill simplified + +- Previously prescribed specific procedural steps (e.g. confirm which tests to write, walk + through them) — this didn't fit the expectation that an AFK agent should be able to run TDD + unattended. +- Now **reference material only**: red before green, one slice at a time — no other + prescribed steps. +- **Refactoring removed from the TDD loop entirely** — it's "red green," not "red green + refactor." Matt's rationale: refactoring belongs in `code-review` instead, so the + implementation step doesn't get overloaded. + +## Migration guidance (from Matt) + +If nervous about missing updates: clear out all skills and run `npx skills update` to grab the +new set. If you've customized your own forked skills, point your coding agent at the +`mattpocock/skills` repo release notes and ask it to pull down the relevant new material. + +## Related + +- Evaluated for adoption into cc-os's own marketplace skills (2026-07-14) — see cc-os repo + history/backlog for the adoption decision, not duplicated here.