mattpocock/skills v1.1: coding with alignment surfaces

Repeatable style: Dither Night — same STYLE LOCK every time; only the subject line changes.
Full recipe: _dither-night-prompt.md · also in _illustration-styles.md under DISPATCH · Dither Night.

ID	Article beat	Image
A	Alignment before build — the plan is the product until coding starts
B	Broken loop — weak alignment → fast build → overloaded verification (PR as late discovery)
C	Target loop — grill → research → spec → tickets → build → verify
E	Grill guardrail — facts the agent can discover vs decisions only humans make
F	Wayfinder — foggy work becomes investigation beacons, not a premature spec

---

Matt Pocock shipped v1.1 of mattpocock/skills, and the interesting part is not the number of new commands.

It is that the commands now line up with the way agent-assisted coding actually fails.

Maggie Appleton put the problem cleanly in her AI Engineer Europe / GitHub Next talk, “One Developer, Two Dozen Agents, Zero Alignment”. Implementation is collapsing. The time between “we should change this” and “an agent opened a PR” is now measured in minutes. That sounds like progress, until you notice where the discussion went.

Before agents, software work had a slow middle. Planning, building, and review stretched out long enough that teams had lots of little alignment points: issue comments, Slack threads, Zoom calls, draft PRs, pairing, hallway conversations, senior engineers squinting at the shape of the thing.

Now the build phase has shrunk.

So the alignment graph often becomes:

weak alignment → very fast build → overloaded verification

The PR becomes the place where everyone discovers the plan, the tradeoffs, the missing context, the duplicate work, and the fact that nobody wanted this exact thing. The PR was not designed to carry all of that. It is too late in the loop.

That is why these skills are useful. Not because /to-spec is a better magic incantation than /to-prd. Because the new set gives us small, explicit surfaces for alignment before and during coding.

Our target loop is closer to:

align ↔ research/prototype → spec → tickets → build → verify

The build step is still fast. Good. But the saved time gets spent on figuring out the right thing, slicing it cleanly, and verifying it intentionally.

The new vocabulary is better

/to-prd is now /to-spec. Good. Most of what coding agents need is not a Product Requirements Document in the capital-P product-manager sense. It is a spec: what are we trying to make true, what constraints matter, what is out of scope, and what evidence will convince us we got there.

/to-issues is now /to-tickets. Also good. Issues are what GitHub calls them. Tickets are the more general unit of work underneath a spec. The word matters because the skill now wants blocked vertical slices, not just a pile of TODOs.

The full coding loop looks like this:

1. Grill the idea until the important decisions are explicit.
2. Research or prototype where the facts or shape are still unclear.
3. Write a spec that captures the destination.
4. Break the spec into tickets with blocking edges.
5. Implement one ticket with tests at agreed seams.
6. Review the code against the spec, repo standards, and refactoring smells.

That is much more useful than a bag of prompts. It is a lightweight development process that agents can participate in.

Example: a normal feature

Say we want to add saved filters to an internal dashboard.

The bad agent version is familiar:

“Add saved filters to the dashboard.”

The agent makes a button, invents a persistence model, stores something somewhere, opens a PR, and now the team starts arguing about whether filters are per-user, per-team, shareable, searchable, visible in the URL, included in exports, or audited.

All useful questions. All late.

With the v1.1 flow, we use the skills like this:

/grill-with-docs

The agent reads CONTEXT.md, ADRs, and the existing dashboard code, then asks one question at a time. The output is not code. It is alignment:

• Saved filters are per-user, not shared.
• Filters should round-trip through the URL.
• The first version only supports the existing filter types.
• Exports should use the currently active filter, but saved filter names do not appear in export metadata.
• No audit trail yet.

Then:

/to-spec

Now the conversation becomes a spec. Not a vibes transcript. A durable destination.

Then:

/to-tickets

The spec becomes blocked vertical slices:

1. Persist saved filter definitions for the current user.
2. Add URL round-tripping for active filters.
3. Add save/load UI around the existing filter panel.
4. Make exports respect the active filter.
5. Add tests for malformed saved filters and missing filter fields.

The blocking edges matter. The UI ticket depends on the persistence ticket. The export ticket depends on URL round-tripping. Two agents can work in parallel only where the graph says they can.

Then each implementation session is boring in the best way:

/implement ticket 2
/code-review

Build one slice. Verify it against the ticket. Review it against standards and the spec. Merge or revise.

This is how we get agent speed without turning every PR into an archaeological dig.

Example: foggy work gets Wayfinder

Some work is not ready for a spec.

“Replace our sync engine.”

That is not a feature request. That is a weather system.

A single agent session will either produce a suspiciously confident plan or drown in context. This is where /wayfinder is the real addition.

Wayfinder creates a map in the issue tracker. Not implementation tickets yet. Investigation tickets.

For a sync-engine replacement, the map might create:

• Research: Compare the current sync failure modes from logs and support tickets.
• Research: Read the API rate-limit docs and retry semantics for the upstream system.
• Prototype: Build a tiny conflict-resolution simulator with three representative edge cases.
• Grilling: Decide whether offline writes are in scope for v1.
• Task: Get access to the production error sample in the approved secure location.

Each ticket is sized for one agent session. Each ticket has blockers. Each answer goes back onto the map as a decision or a link.

Only after the fog clears do we write the spec.

That is the important distinction: Wayfinder is not “build the big thing.” It is “find the route to the big thing.”

This maps almost directly to Maggie Appleton’s point. The context that matters is often not in the codebase. It is in people’s heads, support queues, product history, business constraints, and taste. Wayfinder gives us a place to pull that context forward before the build phase turns cheap code into expensive confusion.

Example: UI work needs prototypes before tickets

For front-end work, the loop changes slightly:

/grill-with-docs → /prototype → /to-spec → /to-tickets

Suppose we are redesigning an onboarding flow. The questions are not only “what data gets saved?” They are also:

• Does this feel like one flow or three steps?
• Should advanced setup be visible or tucked away?
• What happens when someone skips a required integration?
• What does success look like on an empty account?

A prototype is a cheap artifact to react to. It might be a throwaway route with three UI variations, or a little state machine that shows the onboarding transitions without any production wiring.

The point is not to keep the prototype. The point is to make the conversation less abstract.

Once the team chooses the shape, the spec can say something precise. The tickets can be slices instead of guesses.

Example: wide refactors need blocking edges

The other useful improvement is that /to-tickets understands wide refactors.

A wide refactor is something like renaming a shared database field or changing a cross-package type. A naive “vertical slice” approach breaks down because the blast radius crosses everything at once.

The skill now pushes toward expand–contract:

1. Add the new field beside the old field.
2. Migrate API reads.
3. Migrate background jobs.
4. Migrate UI call sites.
5. Backfill data.
6. Remove the old field.

Those are not independent TODOs. They are a graph. The contract step is blocked by all migration tickets. Each migration ticket is sized by blast radius. CI stays green as long as the old and new forms coexist.

This is where “tickets” is the better word. The ticket is not a place to complain. It is a unit of safe movement through the codebase.

Grilling got safer

The grilling changes are small but important:

• Ask one question at a time.
• Do not implement until the human confirms shared understanding.
• Separate facts the agent can discover from decisions the human must make.

That last one is the sharp edge. Agents are very good at answering questions. Sometimes too good. A planning agent that answers its own product decisions has not accelerated the work; it has silently changed who is in charge.

The facts-versus-decisions split is a tidy guardrail.

It is also exactly the distinction we need for coding. The agent can inspect how authentication currently works. It cannot decide whether enterprise SSO is in scope this quarter. The agent can read the billing provider docs. It cannot decide how much migration risk the business will tolerate.

Research, implementation, TDD, and review move into the loop

The supporting skills round out the coding system:

• /research sends a background agent to primary sources and leaves behind a cited Markdown note.
• /prototype is now model-invoked, with separate logic and UI branches, so Wayfinder can use prototypes to raise the fidelity of a decision.
• /implement is deliberately plain: implement the ticket, use TDD where it fits, typecheck regularly, run the full sweep at the end.
• /code-review checks both standards and spec conformance, and it adds a Fowler-style smell baseline — mysterious names, duplicated code, feature envy, data clumps, primitive obsession, message chains, middlemen, and friends.
• /tdd becomes reference material instead of a ceremony. Red, green, then let refactoring live in review.

That last move is underrated. Agent sessions already have enough going on. Splitting implementation from review keeps each pass simpler.

What we are changing

We are updating our default project standards around the v1.1 vocabulary and flow.

Out:

• /to-prd
• /to-issues

In:

• /to-spec
• /to-tickets
• /wayfinder
• /research
• /implement
• /code-review
• /tdd

And we keep:

• /grill-me
• /grill-with-docs
• /prototype

The practical migration is simple: run the installer for the new skills, then remove the old skill folders and delete their lockfile entries. The installer will not infer renames and merges for you.

The conceptual migration is better: stop treating agent skills as magic phrases. Treat them as process boundaries.

A spec is a boundary. A ticket is a boundary. A code review is a boundary. Wayfinder is a boundary around uncertainty itself.

If implementation is cheap, the expensive thing is alignment. Spend the saved time there.