SecondBrain/matt-pocock-skills-v1-1-changes.md at 016763d3b3d671ad228f46b16d435f755b5e9653

6.4 KiB

Raw Blame History

type

title

summary

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:

Sharpened "asking multiple questions at once is bewildering" — models were still occasionally asking multiple questions despite prior one-at-a-time direction.
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.
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:

Grill (via grill-with-docs or the new wayfinder) → produces a glossary + ADRs.
to-spec — turns grilled material into a spec (the destination).
to-tickets — splits the spec into individually-workable tickets.
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."
implement calls code-review automatically, then commits.

code-review: refactor-smell axis

code-review runs two axes as parallel sub-agents:

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).
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.

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.

6.4 KiB Raw Blame History