A field guide · ten skills, three loops

The Matt Pocock
skills, and how
they fit together.

Each skill is small on purpose. The shape only appears once you see which one hands off to the next — and what they all write to in between.

i. Foundation

Wire the skills into this repo.

Done once. Tells every other skill where issues live, which label vocabulary you use, and whether your domain docs are single- or multi-context.

setup-matt-pocock-skills
Writes the ## Agent skills block and docs/agents/*.md. Read by everything below.
ii. Idea → ready-for-agent work

Turn an idea into issues an agent can grab.

A funnel. Stress-test the thinking, capture the result as a PRD, then slice the PRD into vertical-bullet issues. Each step writes something durable.

grill-with-docs
Stress-tests the plan against CONTEXT.md and ADRs. Sharpens vocabulary; updates docs inline as decisions crystallise.
to-prd
Publishes a PRD issue, labelled ready-for-agent — no further triage needed.
to-issues
Splits the PRD into vertical-slice issues wired with Blocked by. Also ready-for-agent.
Branch · inbound from outside A bug report or feature request from someone else lands unlabelled. It goes through triage instead — a state machine over the five canonical labels. triage can pause mid-flow to invoke grill-with-docs when an issue is too vague to label.
triage
Moves unlabelled issues through needs-triage → needs-info / ready-for-agent / ready-for-human / wontfix.
iii. Execute a ready-for-agent issue

Pick up the work and ship it.

Orient first, optionally prototype the open design question, then build under test. The refactor pass may surface deeper architectural work for later.

zoom-out
A higher-level pass when you're unfamiliar with the surrounding code.
prototype
Throwaway code that answers a question — state shape or UI feel. Two branches: a terminal logic harness, or several switchable UI variants. Capture the answer, then delete or absorb.
tdd
Red → green → refactor, one vertical slice per cycle. Decisions from prototype become the first tests.
improve-codebase-architecture
Triggered from the refactor pass: find deepening opportunities, grilled the same way plans are.
iv. When something is broken

Diagnose, fix, and learn from it.

A separate discipline. The post-mortem is where the fix loop quietly hands back to the build loop — but only if the lesson is structural.

diagnose
Reproduce → minimise → hypothesise → instrument → fix → regression test → post-mortem.
improve-codebase-architecture
Invoked from the post-mortem after the fix lands, if “what would have prevented this?” turns out to be architectural.
The shared substrate

Two stores everything reads from.

MemoryCONTEXT.md (the project's glossary and terminology) and docs/adr/ (the why behind past decisions). Written by grill-with-docs and improve-codebase-architecture; read by almost everything else.

QueueThe issue tracker — GitHub Issues here. Written by to-prd, to-issues, and triage; read by anything that operates on a specific issue.

The skills stay small because each one writes to one of these two stores. The next skill — or the next session, or the next agent — picks up where the last one left off.

In one breath

Plan with grill-with-docs, publish with to-prd and to-issues, triage what comes in, build with prototype and tdd, improve with architecture, repair with diagnose. CONTEXT.md remembers. The tracker queues.