Module 1.6 — Complete Workflow | Skills For Real Engineers

⚙️ Initial setup: `/setup-matt-pocock-skills`

Before running any other skill, the repository needs to be configured once. O /setup-matt-pocock-skills interviews you about three points and records the decisions in version-controlled files—every other skill reads this context to behave the right way.

🎯 What setup decides

• Issue tracker: GitHub Issues, Linear, or a local folder issues/ in markdown. It defines where /to-prd e /to-issues will write.
• Label vocabulary: the roles of the /triage (needs-triage, ready-for-afk, blocked, etc.) become real labels in the tracker.
• Doc layout: where it lives CONTEXT.md, where the ADRs go, and how the /grill-with-docs should update them.

💻 Typical skill prompts

$ /setup-matt-pocock-skills

→ Qual issue tracker este repo usa?
   [1] GitHub Issues  [2] Linear  [3] Local (issues/*.md)

→ Onde fica a documentação viva?
   docs/CONTEXT.md (default)  ou caminho customizado

→ Pasta de ADRs?
   docs/adr/ (default)

✓ Gravado em .claude/skills-config.json
✓ Stub de docs/CONTEXT.md criado
✓ Labels recomendadas listadas (rode `gh label create ...`)

💡 Practical tip

Run /setup-matt-pocock-skills once per repo, right after cloning. Commit the .claude/skills-config.json and of the CONTEXT.md — that way, everyone on the team inherits the same workflow.

CONCEPT 1

Setup is per repo, not global

CONCEPT 2

Decisions become version-controlled files

CONCEPT 3

Enables the other skills

CONCEPT 4

Run it once, not all the time

🔥 Step 1 — Grilling (alignment)

Every new feature starts with the /grill-with-docs. It questions your idea against the existing domain: the vocabulary of CONTEXT.md, previous ADRs, known constraints. The output isn’t code—it’s alignment.

📝 What comes out of grilling

• CONTEXT.md updated: new domain terms, resolved ambiguities, refined scope.
• New ADRs: architectural decisions that came up during grilling become files in docs/adr/.
• Conversation saved: the transcript is available to the /to-prd use as input.

🚫 DO NOT skip this step

Skipping grilling is the #1 mistake people make when starting with the skills. Without alignment, you generate PRDs based on wrong assumptions — and the cascade turns into rework. 15 minutes of grilling save 3 hours of refactoring.

CONCEPT 1

Grilling always comes first

CONCEPT 2

Output is alignment, not code

CONCEPT 3

Updates CONTEXT.md inline

CONCEPT 4

Generates ADRs when it makes decisions

📄 Step 2 — `/to-prd` (synthesize)

With the grilling conversation fresh, /to-prd synthesizes everything into a PRD and creates an issue in the tracker. Note: there’s no new interview — the skill uses the current session context + CONTEXT.md.

🧠 Why no new interview

Asking everything again would be a waste—the agent has already seen the discussion. The skill extracts, don't collection. This changes the kind of relationship you have with the agent: each skill is a node in a pipeline, not an isolated conversation.

67% fewer redundant questions compared with PRDs created from scratch
Context preserved: terms, constraints, and ADRs are already in the narrative

📋 Generated PRD (example)

# PRD: Importação CSV de leads

## Problema
Time comercial cola CSV no Slack; ninguém importa.
~40 leads/semana perdidos.

## Solução proposta
Endpoint POST /leads/import aceita CSV multipart.
Valida colunas obrigatórias (email, nome, fonte).
Deduplica por email. Retorna relatório.

## Fora de escopo
- UI de upload (vem em PRD futuro)
- Enriquecimento de dados

## Critérios de aceite
- [ ] CSV válido importa em <5s para 1000 linhas
- [ ] Linhas inválidas retornam no response, não 500
- [ ] Idempotente: re-upload não duplica

## Decisões herdadas
ADR-012: validação via Zod (não Yup).
ADR-019: jobs >2s vão pra fila, não inline.

CONCEPT 1

Synthesize, don’t interview

CONCEPT 2

Create an issue in the tracker

CONCEPT 3

Cites inherited ADRs

CONCEPT 4

Define “out of scope”

🔪 Step 3 — `/to-issues` (slice)

A PRD isn’t executable. /to-issues breaks the PRD into vertical slices — each slice is an independent issue that delivers visible value on its own.

✓ Vertical slices (DO)

✓ "Accept a CSV upload and return the row count" — testable end to end
✓ "Validate required columns with a 400 error" — delivers visible behavior
✓ "Deduplicate by email on insert" — can be merged on its own
✓ Each one has an acceptance criterion in the PR

✗ Isolated technical tasks (AVOID)

✗ "Create Zod schema" — delivers nothing on its own
✗ "Add csv-parse dependency" — invisible
✗ "Refactor leads service" — mergeable?? What for?
✗ "Endpoint setup with no logic" — empty PR

💡 Practical tip

Test each slice with the question: "If I merge just this one, will someone use it tomorrow?" If the answer is "no, the others need to come along," the slice is horizontal — break it down again.

CONCEPT 1

Vertical, not horizontal

CONCEPT 2

Each slice can be merged on its own

CONCEPT 3

Acceptance criteria per issue

CONCEPT 4

Test: “would someone use this tomorrow?”

🚦 Step 4 — `/triage` (prioritize)

Fresh issues arrive with the label needs-triage. O /triage moves them one at a time roles state machine — each state describes where the issue is in the pipeline and who can act.

needs-triage

Initial state — just came from /to-issues

No one has reviewed it yet. It may be poorly split, duplicated, or out of priority. Blocks execution.

needs-discussion

There’s ambiguity that /grill didn’t resolve

Requires synchronous conversation with a human. Return to grilling if needed.

ready-for-human

Ready, but needs a senior dev

There’s architectural nuance—the agent alone isn’t enough. A human takes over.

ready-for-afk

The agent runs on its own while you go to lunch

Crystal-clear acceptance criteria, short scope, low risk. /tdd works things out while you're away.

blocked

Depends on something external

Third-party API, product decision, another unmerged issue. Back to the queue when unblocked.

in-progress → done

Terminal states of the cycle

PR opened → in progress. PR merged → done. Issue closes automatically via “Closes #N”.

CONCEPT 1

Each issue has a role

CONCEPT 2

Roles are actual labels in the tracker

CONCEPT 3

ready-for-afk = TDD candidate

CONCEPT 4

States transition; they don’t accumulate

🧪 Step 5 — Implementation with `/tdd`

Pick an issue ready-for-afk, opens a branch, runs /tdd. The skill runs the classic loop red → green → refactor guided by the issue’s acceptance criteria.

🔄 The loop by slice

RED Write a failing test. Acceptance criterion #1 becomes the first test. Run it — red.
GREEN Implement the minimum needed to pass. Nothing more. Run it — green.
REFACTOR Clean up the code without changing behavior. Tests stay green. The next criterion becomes the next RED.

💡 Practical tip

If the /tdd try to skip RED ("I'll just implement it and test afterward"), stop. RED first, always. Without the test failing first, you don’t know if it’s worth anything.

CONCEPT 1

Branch per issue

CONCEPT 2

RED → GREEN → REFACTOR

CONCEPT 3

Acceptance criteria = tests

CONCEPT 4

No RED, no skip

👀 Step 6 — Review and merge

Green branch, time for the PR. Use /verify (run the app for real and see it working) or code-review (static diff review). Addressed comments, merge.

✓ Checklist before merging

✓Tests pass in CI
✓All issue acceptance criteria passing
✓/verify showed real behavior
✓code-review with no high-severity findings
✓PR description mentions “Closes #N”

✗ Don't merge if

✗"Local tests pass but CI is slow, ship it anyway"
✗Acceptance criterion #3 was left for another PR
✗Diff includes files unrelated to the issue
✗Behavior changed without being updated CONTEXT.md
✗PR without an issue link (“Closes”)

📊 /verify vs code-review

/verify: runs the app, performs the actual action, and proves it works end to end. Use when the slice changes visible behavior.
code-review: static diff analysis, looks for subtle bugs and edge cases. Always use it — cheap and fast.
Both: for critical features. Low cost, high signal.

CONCEPT 1

/verify proves it works

CONCEPT 2

code-review catches subtle bugs

CONCEPT 3

"Closes #N" closes automatically

CONCEPT 4

Merge changes the status to done

🗺️ Overview — the complete cycle

Putting it all together: the cycle feeds itself — the next grilling already starts with a CONTEXT.md more mature, with new ADRs and vocabulary refined by the previous feature.

🔀 Workflow diagram

  ┌─────────────────────────────────────────────────────────┐
  │  /setup-matt-pocock-skills  (uma vez por repo)        │
  └────────────────────────┬────────────────────────────────┘
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │  /grill-with-docs           CONTEXT.md + ADRs        │
  └────────────────────────┬────────────────────────────────┘
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │  /to-prd                    issue com PRD             │
  └────────────────────────┬────────────────────────────────┘
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │  /to-issues                 N vertical slices         │
  └────────────────────────┬────────────────────────────────┘
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │  /triage                    role por issue            │
  │     needs-triage → ready-for-afk / ready-for-human       │
  └────────────────────────┬────────────────────────────────┘
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │  /tdd                       red → green → refactor    │
  │     (uma branch por issue)                               │
  └────────────────────────┬────────────────────────────────┘
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │  /verify + code-review     PR review                 │
  └────────────────────────┬────────────────────────────────┘
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │  merge                      issue → done              │
  │  CONTEXT.md atualizado pelo próximo /grill              │
  └────────────────────────┬────────────────────────────────┘
                           │
                           └───── volta pro /grill-with-docs ─────┐
                                  (próxima feature)               │
                                                                  ▼
                                                          (ciclo se repete)

♻️ The cycle feeds itself

Each iteration leaves the CONTEXT.md denser, the ADRs more complete, and the domain vocabulary more precise. Grilling #10 is faster and deeper than grilling #1 — because the agent already understands your domain. This is the real combination of Matt Pocock's skills.

CONCEPT 1

8 steps, 1 cycle

CONCEPT 2

CONTEXT.md as a living artifact

CONCEPT 3

Each iteration leaves the repo better

CONCEPT 4

Composite, non-linear

🎓 Course conclusion

You’ve completed Track 1. Let’s review the 4 problems that opened the course—and how each skill handles one piece.

"The agent forgets everything between sessions" → CONTEXT.md + /grill-with-docs provide versioned, refinable memory.

"Ambiguous specifications turn into incorrect code" → Grilling before the PRD catches ambiguity at the source; /to-prd synthesizes with clear scope.

"Large tasks never get finished" → /to-issues in vertical slices makes each piece independently mergeable.

"You can't trust what the agent delivers" → /tdd + /verify + code-review form the three pillars of trust: tests that prove, execution that demonstrates, and review that questions.

🚀 Next steps

→ Practice on a real project. Choose one of your repos, run /setup-matt-pocock-skills, and use the workflow on a small feature (1–2 slices). Don’t try to apply everything at once on a large project.
→ Iterate on CONTEXT.md. Reread after each merged feature. Add what you learned. It’s your greatest asset.
→ Share with the team. The workflow only works if more people use it—everyone reading the same CONTEXT.md, everyone following the same roles in /triage.

🔗 Useful links

• Matt Pocock's newsletter about skills: aihero.dev/s/skills-newsletter — gets updates directly from the source.
• Course repository: github.com/inematds/mp-skill — source code for the skills and the course.

← Module 1.5 Back to Track →

⚙️ Initial setup: /setup-matt-pocock-skills

🎯 What setup decides

💻 Typical skill prompts

💡 Practical tip

🔥 Step 1 — Grilling (alignment)

📝 What comes out of grilling

🚫 DO NOT skip this step

📄 Step 2 — /to-prd (synthesize)

🧠 Why no new interview

📋 Generated PRD (example)

🔪 Step 3 — /to-issues (slice)

✓ Vertical slices (DO)

✗ Isolated technical tasks (AVOID)

💡 Practical tip

🚦 Step 4 — /triage (prioritize)

needs-triage

needs-discussion

ready-for-human

ready-for-afk

blocked

in-progress → done

🧪 Step 5 — Implementation with /tdd

🔄 The loop by slice

💡 Practical tip

👀 Step 6 — Review and merge

✓ Checklist before merging

✗ Don't merge if

📊 /verify vs code-review

🗺️ Overview — the complete cycle

🔀 Workflow diagram

♻️ The cycle feeds itself

🎓 Course conclusion

🚀 Next steps

🔗 Useful links

⚙️ Initial setup: `/setup-matt-pocock-skills`

📄 Step 2 — `/to-prd` (synthesize)

🔪 Step 3 — `/to-issues` (slice)

🚦 Step 4 — `/triage` (prioritize)

🧪 Step 5 — Implementation with `/tdd`