Getting started
Introduction
Matt Pocock skills run a spec-to-PR workflow: grill the plan, write a spec, slice tickets, implement test-first, review, then open the PR.
- GitHub repository (github.com)
- Agent skills format (devhints.io)
- Grilling sessions (devhints.io)
First run
/setup-matt-pocock-skills
Once per repo, before other engineering skills. It explores the repo, confirms answers one section at a time, and writes repo-local markdown. Only the human can invoke it.
See: Setup skill
What setup writes
| File | Contents |
|---|---|
docs/agents/issue-tracker.md | GitHub, GitLab, local markdown, or described workflow |
docs/agents/domain.md | Single- or multi-context doc layout |
docs/agents/triage-labels.md | Label mapping, only with triage installed |
CLAUDE.md or AGENTS.md | ## Agent skills block pointing at those files |
See: Setup SKILL.md
Blur to decided
/grill-with-docs add SSO for the admin console
The result is shared understanding you hand to /to-spec; the next sheet covers how the interview runs.
See: grill-with-docs
Decided to tickets
/to-spec add SSO for the admin console
/to-tickets #42
/to-spec synthesises the conversation without a new interview; /to-tickets slices the spec into demoable work with blocking edges.
See: to-spec
Tickets to PR
/implement #43
/code-review main
/pr
One ticket per fresh context. /implement drives red-green tests at the agreed seams, calls review and commits; /pr shapes the body.
See: pr
The pipeline
Flow
/grill-with-docs ─▶ /to-spec ─▶ /to-tickets ─▶ /implement
│ │
├─ GLOSSARY.md, ADRs ├─▶ /code-review
└─ /wayfinder when multi-session └─▶ /pr ─▶ /retro
/triage ─▶ ready-for-agent ─▶ /implement
See: Flow map
Gates
| Command | End state |
|---|---|
/grill-with-docs | frontier empty, user confirms shared understanding |
/to-spec | seam check confirmed, spec published ready-for-agent |
/to-tickets | numbered breakdown approved, demoable slices with blocking edges |
/implement | typecheck, single tests, full suite once, review, commit |
/code-review | resolvable fixed point, non-empty diff, Standards and Spec reports |
/pr | body has Summary, before/after Evidence, door and blast radius |
See: Flow map
Which command
Find the skill
| Command | Situation |
|---|---|
/ask-matt | Unsure which skill fits |
/grill-me | Idea is fuzzy, no repo |
/grill-with-docs | Fuzzy, in a repo |
/wayfinder | Fog spans sessions |
/to-spec | Decided, need a durable spec |
Build the work
| Command | Situation |
|---|---|
/to-tickets | Spec ready to slice |
/implement | Decided, ready to code |
/implement-spec | Whole spec, many tickets |
See: Router
Around the flow
| Command | Role |
|---|---|
/triage | Moves incoming issues through state roles to ready-for-agent |
/handoff | Writes a portable summary into the OS temp dir |
/retro | Suggests changes to the agent's environment after a session |
See: Triage
Invocation
- Human only
/grill-me,/grill-with-docs,/to-spec,/implement,/triage,/setup-matt-pocock-skills - Model or human, via Skill tool
grilling,tdd,code-review,pr - Never A Skill tool call to a user-invoked skill
See: Invocation rules
Planning
Spec
- Problem Statement The problem from the user's perspective
- Solution The solution from the user's perspective
- User Stories Numbered "As an actor, I want..." stories
- Implementation Decisions Modules, interfaces, constraints, no file paths
- Testing Decisions Good-test rule, modules, prior art
- Out of Scope Refused work
- Further Notes Anything left over
See: to-spec
Tickets
- Tracer bullet Narrow path through schema, API, UI and tests
- Demoable Verifiable on its own
- Single context Sized for one fresh context window
- Blocking edges Prerequisites; work the frontier first
- Wide refactor Expand, migrate in batches, then contract
See: to-tickets
Domain docs
Glossary
**Invoice**:
A request for payment sent to a customer after delivery.
_Avoid_: Bill, payment request
ADRs
# Write model
Orders go to Postgres; the read model is projected into Redis.
Terms go into GLOSSARY.md inline. An ADR needs all three gates: hard to reverse, surprising, a real trade-off.
See: domain-modeling
Tracker
| Tracker | Ticket store |
|---|---|
| GitHub | Issues via gh |
| GitLab | Issues via glab |
| Local markdown | Files under .scratch/<feature>/issues/NN-slug.md |
| Other | Freeform workflow described in prose |
Building
Implement
| Command | Use |
|---|---|
/implement #43 | One ticket, one commit on the current branch |
/implement-spec | Whole spec on an integration branch |
See: implement
TDD loop
red -> failing test at an agreed seam
green -> minimum code to pass
Pitfalls
- One slice at a time Repeat red-green; refactoring belongs in review
- Implementation-coupled Breaks on refactor, not behaviour
- Tautological Assertion recomputes the expected value
See: tdd
Review and PR
## Summary
<diagram, diff-sketch, or tree>
## Evidence
**Before:** <screenshot or failing run>
**After:** <screenshot or passing run>
## Merge Danger
**Door:** two-way
**Blast Radius:** docs only
See: code-review
0 Comments for this cheatsheet. Write yours!