Módulo 1.6 — Workflow Completo | Skills For Real Engineers

⚙️ Setup inicial: `/setup-matt-pocock-skills`

Antes de rodar qualquer outra skill, o repositório precisa estar configurado uma vez. O /setup-matt-pocock-skills entrevista você sobre três pontos e grava as decisões em arquivos versionados — todas as outras skills leem esse contexto para se comportarem do jeito certo.

🎯 O que o setup decide

• Issue tracker: GitHub Issues, Linear, ou pasta local issues/ em markdown. Define onde /to-prd e /to-issues vão escrever.
• Label vocabulary: os roles do /triage (needs-triage, ready-for-afk, blocked, etc.) viram labels reais no tracker.
• Doc layout: onde mora CONTEXT.md, onde vão os ADRs, e como o /grill-with-docs deve atualizá-los.

💻 Prompts típicos da skill

$ /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 ...`)

💡 Dica prática

Rode /setup-matt-pocock-skills uma única vez por repo, logo depois do clone. Faz commit do .claude/skills-config.json e do stub do CONTEXT.md — assim todo mundo do time herda o mesmo workflow.

CONCEITO 1

Setup é por repo, não global

CONCEITO 2

Decisões viram arquivos versionados

CONCEITO 3

Habilita as outras skills

CONCEITO 4

Roda uma vez, não toda hora

🔥 Etapa 1 — Grilling (alinhamento)

Toda feature nova começa pelo /grill-with-docs. Ele interroga sua ideia contra o domínio existente: vocabulário do CONTEXT.md, ADRs anteriores, restrições conhecidas. O output não é código — é alinhamento.

📝 O que sai do grilling

• CONTEXT.md atualizado: novos termos do domínio, ambiguidades resolvidas, escopo refinado.
• ADRs novos: decisões arquiteturais que apareceram durante o grilling viram arquivos em docs/adr/.
• Conversa salva: o transcript fica disponível para o /to-prd usar como insumo.

🚫 NÃO pule essa etapa

Pular o grilling é o erro #1 de quem começa com as skills. Sem alinhamento, você gera PRDs em cima de premissas erradas — e a cascata vira retrabalho. 15 minutos de grilling economizam 3 horas de refatoração.

CONCEITO 1

Grilling vem primeiro, sempre

CONCEITO 2

Output é alinhamento, não código

CONCEITO 3

Atualiza CONTEXT.md inline

CONCEITO 4

Gera ADRs quando decide

📄 Etapa 2 — `/to-prd` (sintetizar)

Com a conversa de grilling fresca, /to-prd sintetiza tudo em um PRD e cria uma issue no tracker. Note: não há nova entrevista — a skill usa o contexto da sessão atual + CONTEXT.md.

🧠 Por que sem entrevista nova

Re-perguntar tudo seria desperdício — o agente já viu a discussão. A skill extrai, não coleta. Isso muda o tipo de relação com o agente: cada skill é um nó de um pipeline, não uma conversa isolada.

67% menos perguntas redundantes vs PRDs feitos do zero
Contexto preservado: termos, restrições e ADRs já estão na narrativa

📋 PRD gerado (exemplo)

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

CONCEITO 1

Sintetiza, não entrevista

CONCEITO 2

Cria issue no tracker

CONCEITO 3

Cita ADRs herdados

CONCEITO 4

Define "fora de escopo"

🔪 Etapa 3 — `/to-issues` (fatiar)

Um PRD não é executável. /to-issues quebra o PRD em vertical slices — cada slice é uma issue independente que entrega valor visível sozinha.

✓ Slices verticais (FAZER)

✓ "Aceitar upload de CSV e retornar contagem de linhas" — testável end-to-end
✓ "Validar colunas obrigatórias com erro 400" — entrega comportamento visível
✓ "Deduplicar por email no insert" — pode mergear sozinho
✓ Cada uma tem critério de aceite no PR

✗ Tasks técnicas isoladas (EVITAR)

✗ "Criar schema Zod" — não entrega nada sozinho
✗ "Adicionar dependency csv-parse" — invisível
✗ "Refatorar service de leads" — mergeável?? Para quê?
✗ "Setup do endpoint sem lógica" — PR vazio

💡 Dica prática

Teste cada slice com a pergunta: "Se eu mergear só essa, alguém usa amanhã?" Se a resposta for "não, precisa das outras junto", o slice está horizontal — quebre de novo.

CONCEITO 1

Vertical, não horizontal

CONCEITO 2

Cada slice mergeável sozinho

CONCEITO 3

Critério de aceite por issue

CONCEITO 4

Teste: "alguém usa amanhã?"

🚦 Etapa 4 — `/triage` (priorizar)

Issues frescas chegam com label needs-triage. O /triage as move por uma state machine de roles — cada estado descreve onde a issue está no funil e quem pode agir.

needs-triage

Estado inicial — saiu fresca do /to-issues

Ninguém revisou ainda. Pode estar mal-fatiada, duplicada, ou fora de prioridade. Bloqueia execução.

needs-discussion

Tem ambiguidade que /grill não resolveu

Precisa de conversa síncrona com humano. Volta pro grilling se necessário.

ready-for-human

Pronta, mas precisa de dev sênior

Tem nuance arquitetural — agente sozinho não basta. Humano pega.

ready-for-afk

Agente roda sozinho, você sai pra almoçar

Critério de aceite cristalino, escopo curto, baixo risco. /tdd resolve enquanto você não está.

blocked

Depende de algo externo

API de terceiro, decisão de produto, outra issue não mergeada. Volta pra fila quando desbloquear.

in-progress → done

Estados terminais do ciclo

PR aberto → in-progress. PR mergeado → done. Issue fecha automaticamente via "Closes #N".

CONCEITO 1

Cada issue tem um role

CONCEITO 2

Roles são labels reais no tracker

CONCEITO 3

ready-for-afk = candidato a TDD

CONCEITO 4

Estados transitam, não acumulam

🧪 Etapa 5 — Implementação com `/tdd`

Pega uma issue ready-for-afk, abre branch, roda /tdd. A skill executa o loop clássico red → green → refactor guiado pelos critérios de aceite da issue.

🔄 O loop por slice

RED Escreve teste que falha. Critério de aceite #1 vira o primeiro teste. Roda — vermelho.
GREEN Implementa o mínimo para passar. Nada além. Roda — verde.
REFACTOR Limpa o código sem mudar comportamento. Testes continuam verdes. Próximo critério vira próximo RED.

💡 Dica prática

Se o /tdd tentar pular o RED ("vou só implementar e depois testo"), interrompa. RED primeiro, sempre. Sem o teste falhando antes, você não sabe se ele vale alguma coisa.

CONCEITO 1

Branch por issue

CONCEITO 2

RED → GREEN → REFACTOR

CONCEITO 3

Critérios de aceite = testes

CONCEITO 4

Sem RED, sem skip

👀 Etapa 6 — Review e merge

Branch verde, hora do PR. Use /verify (rodar o app de verdade e ver funcionando) ou code-review (revisão estática do diff). Comentários endereçados, merge.

✓ Checklist antes do merge

✓Testes passam em CI
✓Critérios de aceite da issue todos verdes
✓/verify mostrou comportamento real
✓code-review sem findings de severidade alta
✓PR descrição cita "Closes #N"

✗ Não mergeie se

✗"Testes locais passam mas CI tá lento, vai assim mesmo"
✗Critério de aceite #3 ficou pra outra PR
✗Diff tem arquivos não relacionados à issue
✗Mudou comportamento sem atualizar CONTEXT.md
✗PR sem link pra issue ("Closes")

📊 /verify vs code-review

/verify: roda o app, faz a ação real, prova que funciona end-to-end. Use quando o slice muda comportamento visível.
code-review: análise estática do diff, busca bugs sutis, edge cases. Use sempre — barato e rápido.
Ambos: em features críticas. Custo baixo, sinal alto.

CONCEITO 1

/verify prova funcionamento

CONCEITO 2

code-review pega bugs sutis

CONCEITO 3

"Closes #N" fecha automático

CONCEITO 4

Merge altera estado para done

🗺️ Visão geral — o ciclo completo

Costurando tudo: o ciclo se realimenta — o próximo grilling já começa com um CONTEXT.md mais maduro, ADRs novos e vocabulário refinado pela feature anterior.

🔀 Fluxograma do workflow

  ┌─────────────────────────────────────────────────────────┐
  │  /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)

♻️ O ciclo se realimenta

Cada volta deixa o CONTEXT.md mais denso, os ADRs mais completos, e o vocabulário do domínio mais preciso. Grilling #10 é mais rápido e mais profundo que o grilling #1 — porque o agente já entende seu domínio. Esse é o composto real das skills do Matt Pocock.

CONCEITO 1

8 etapas, 1 ciclo

CONCEITO 2

CONTEXT.md como artefato vivo

CONCEITO 3

Cada volta deixa repo melhor

CONCEITO 4

Composto, não linear

🎓 Conclusão do curso

Você fechou a Trilha 1. Vamos recapitular os 4 problemas que abriram o curso — e como cada skill resolve um pedaço.

"O agente esquece tudo entre sessões" → CONTEXT.md + /grill-with-docs dão memória versionada e refinável.

"Especificações ambíguas viram código errado" → grilling antes do PRD pega ambiguidade no nascedouro; /to-prd sintetiza com escopo claro.

"Tarefas grandes nunca terminam" → /to-issues em vertical slices torna cada pedaço mergeável sozinho.

"Não dá pra confiar no que o agente entrega" → /tdd + /verify + code-review formam o tripé de confiança: testes que provam, execução que demonstra, revisão que questiona.

🚀 Próximos passos

→ Pratique em um projeto real. Escolha um repo seu, rode /setup-matt-pocock-skills, e use o workflow numa feature pequena (1-2 slices). Não tente aplicar tudo de uma vez em projeto grande.
→ Itere o CONTEXT.md. Releia depois de cada feature mergeada. Acrescente o que aprendeu. É o seu maior ativo.
→ Compartilhe com o time. O workflow só compõe se mais gente usa — todos lendo o mesmo CONTEXT.md, todos respeitando os mesmos roles do /triage.

🔗 Links úteis

• Newsletter do Matt Pocock sobre skills: aihero.dev/s/skills-newsletter — recebe novidades direto da fonte.
• Repositório do curso: github.com/inematds/mp-skill — código-fonte das skills e do curso.

← Módulo 1.5 Voltar à Trilha →

⚙️ Setup inicial: /setup-matt-pocock-skills

🎯 O que o setup decide

💻 Prompts típicos da skill

💡 Dica prática

🔥 Etapa 1 — Grilling (alinhamento)

📝 O que sai do grilling

🚫 NÃO pule essa etapa

📄 Etapa 2 — /to-prd (sintetizar)

🧠 Por que sem entrevista nova

📋 PRD gerado (exemplo)

🔪 Etapa 3 — /to-issues (fatiar)

✓ Slices verticais (FAZER)

✗ Tasks técnicas isoladas (EVITAR)

💡 Dica prática

🚦 Etapa 4 — /triage (priorizar)

needs-triage

needs-discussion

ready-for-human

ready-for-afk

blocked

in-progress → done

🧪 Etapa 5 — Implementação com /tdd

🔄 O loop por slice

💡 Dica prática

👀 Etapa 6 — Review e merge

✓ Checklist antes do merge

✗ Não mergeie se

📊 /verify vs code-review

🗺️ Visão geral — o ciclo completo

🔀 Fluxograma do workflow

♻️ O ciclo se realimenta

🎓 Conclusão do curso

🚀 Próximos passos

🔗 Links úteis

⚙️ Setup inicial: `/setup-matt-pocock-skills`

📄 Etapa 2 — `/to-prd` (sintetizar)

🔪 Etapa 3 — `/to-issues` (fatiar)

🚦 Etapa 4 — `/triage` (priorizar)

🧪 Etapa 5 — Implementação com `/tdd`