pedro-oscar/shorts-ai

Pergunte ao Matt

Você não se lembra de cada skill, então pergunte.

Antes de afirmar o que uma skill faz ou recomendar que uma etapa seja pulada, leia o SKILL.md dessa skill: os resumos aqui são apenas para orientação.

Um fluxo é um caminho através das skills. A maioria dos caminhos segue um fluxo principal e duas rampas de acesso se juntam a ele. Todo o resto é independente, ou uma camada de vocabulário que roda por baixo.

O fluxo principal: ideia → lançamento

A rota que a maior parte do trabalho percorre. Você tem uma ideia e quer que ela seja construída.

1. /grill-with-docs aguça a ideia por meio de entrevista. Comece aqui sempre que estiver trabalhando em um diretório de trabalho: é stateful, retendo o que aprende em GLOSSARY.md e ADRs. (Sem diretório de trabalho? Use /grill-me, coberto em Independente. Ambos executam a mesma primitiva /grilling; grill-with-docs é aquele que deixa um rastro documental, o que o torna o melhor dos dois sempre que um repositório existe para deixar esse rastro.)

2. Ramificação: você consegue resolver todas as perguntas em conversa? Se uma pergunta precisar de uma resposta executável (estado, lógica de negócio, uma UI que você precisa ver), desvie por um protótipo, intermediado por /handoff em ambas as direções (um protótipo vive em seu próprio diretório, que é exatamente para isso que /handoff serve; veja Fronteiras de fase):

   • /handoff para fora, depois abra uma nova sessão naquele arquivo,
   • /prototype para responder à pergunta com código descartável,
   • /handoff de volta o que aprendeu, e referencie-o a partir do thread de ideia original.

3. Ramificação: é uma construção de várias sessões?

   • Sim → /to-spec (transforme o thread em uma especificação), depois /to-tickets para dividi-la em tickets de marcador traçador, cada um declarando suas arestas de bloqueio. Em seguida, trabalhe os tickets de uma das duas maneiras:
     • /implement por ticket, limpando o contexto entre cada um. Em um rastreador local, isso é um arquivo por ticket em .scratch/<feature>/issues/, trabalhados primeiro os bloqueadores manualmente; em um rastreador real, as arestas se tornam links de bloqueio nativos, então qualquer ticket cujos bloqueadores estejam concluídos pode ser pego. Cada ticket é autocontido, então o contexto do último é descartável.
     • /implement-spec para toda a especificação em uma execução. Ele lê os tickets como um grafo de tarefas, executa subagentes implementadores na fronteira pronta em paralelo e integra tudo em um único branch de integração. Use-o quando preferir orquestrar a construção em vez de conduzir cada ticket você mesmo.
   • Não → /implement aqui mesmo, na mesma janela de contexto.

   De qualquer forma, o código é construído dirigindo /tdd (uma fatia vermelho-verde de cada vez) e encerra com /code-review, uma revisão de dois eixos (Padrões + Especificação) do diff. /implement executa ambos por ticket; os implementadores de /implement-spec cada um dirige /tdd, e ele executa uma /code-review sobre o branch de integração. Use /tdd sozinho quando quiser apenas construir um comportamento concreto test-first sem uma especificação completa, e /code-review sozinho sempre que quiser revisar um branch ou PR contra um ponto fixo.

   Quando o trabalho sobe como um pull request, /pr molda o corpo: o menor visual que mostra a mudança, evidência antes/depois de que funciona, e uma chamada de porta unidirecional ou bidirecional. É invocado pelo modelo, então o agente o usa sempre que escreve um PR.

4. /retro fecha o ciclo. Após uma construção, e especialmente uma que deu errado, ele olha para trás na sessão e sugere mudanças no ambiente do agente, não no código: ponteiros de navegação, verificações automatizadas, os padrões de codificação que /code-review aplica, arquivos de direção, ferramentas. Erros mecânicos se tornam verificações determinísticas; julgamentos se tornam padrões de codificação. A próxima construção então começa de um ambiente melhor.

Higiene de contexto

Mantenha as etapas 1–3 em uma janela de contexto ininterrupta (não compacte ou limpe até depois de /to-tickets) para que a entrevista, a especificação e os tickets sejam construídos sobre o mesmo raciocínio. Cada /implement então começa fresco, trabalhando a partir do ticket. Execute /retro na sessão que está revisando, antes de limpar; depois de limpar, aponte-o para o log dessa sessão.

O limite para isso é a zona inteligente: a janela (~150k tokens em modelos de ponta) dentro da qual o modelo ainda raciocina com nitidez. Se uma sessão se aproximar dela antes de /to-tickets, não continue com degradação; /compact na fronteira de fase mais próxima e prossiga (veja Fronteiras de fase).

Rampas de acesso

Uma situação inicial que gera trabalho, depois se junta ao fluxo principal.

• Bugs e solicitações se acumulando → /triage. Ele move issues através de funções de triagem e produz issues prontas para o agente, que /implement depois pega.

  Triagem é apenas para issues que você não criou: relatórios de bug, solicitações de funcionalidade recebidas, qualquer coisa que chegue crua. Tickets que /to-tickets produziu já estão prontos para o agente, então não os trie.

• Algo está quebrado → /diagnosing-bugs. Para os difíceis: o bug que resiste a um primeiro olhar, a falha intermitente, a regressão que se infiltrou entre dois estados conhecidos como bons. Ele se recusa a teorizar até ter um loop de feedback apertado (um comando que já fica vermelho neste bug), então corrige com um teste de regressão. Uma vez que a correção esteja em vigor, execute /retro na mesma sessão para perguntar o que teria impedido o bug; onde a verdadeira descoberta é que não há uma boa junta para travá-lo, isso é trabalho para /improve-codebase-architecture.

• Um esforço enorme e nebuloso: um projeto greenfield ou uma grande construção de funcionalidade, grande demais para uma sessão → /wayfinder, o fluxo mais cognitivamente exigente aqui. Quando o caminho daqui até o destino ainda não está visível, ele traça um mapa compartilhado de tickets de decisão no rastreador de issues e os resolve um de cada vez, produzindo decisões, não entregáveis, até que a névoa seja empurrada para trás e o caminho esteja claro. Enquanto /grill-with-docs aguça uma ideia que você pode segurar em uma sessão, wayfinder é para a ideia que você não consegue, e é mais lento e denso, então guarde-o exatamente para isso, nunca para uma funcionalidade bem escopada.

  Quando o mapa clarear, ele passa o bastão, não constrói: junte-se ao fluxo principal em /to-spec, que colapsa as decisões vinculadas do mapa em um plano construível, depois /to-tickets e /implement como de costume. Loopar o mapa diretamente em /implement pula esse colapso e joga fora os detalhes vinculados, então vá direto para /implement apenas quando o esforço se revelar genuinamente pequeno.

Saúde do código

Não é trabalho de funcionalidade, apenas manutenção.

• /improve-codebase-architecture é executado sempre que você tiver um momento livre para manter o código-fonte bom para os agentes operarem. Ele revela oportunidades de aprofundamento; escolher uma gera uma ideia que você pode levar para o fluxo principal em /grill-with-docs. É o levantamento que encontra os candidatos; /codebase-design (abaixo) é a bancada onde você projeta o escolhido.

Vocabulário subjacente

Duas referências invocadas pelo modelo que rodam abaixo das outras skills, cada uma a única fonte da verdade para seu vocabulário. Use-as diretamente quando as palavras, não o processo, são o problema; ou deixe as skills acima puxá-las.

• /domain-modeling: aguça a linguagem de domínio do projeto: desafie um termo difuso, resolva uma palavra sobrecarregada ("conta" fazendo três trabalhos), registre uma decisão difícil de reverter como um ADR. É a disciplina ativa que /grill-with-docs dirige para manter GLOSSARY.md um glossário limpo.
• /codebase-design é o vocabulário de módulo profundo (módulo, interface, profundidade, junta, adaptador, alavancagem, localidade) para projetar a forma de um módulo: muito comportamento por trás de uma interface pequena em uma junta limpa. /tdd e /improve-codebase-architecture ambos o falam.

Fronteiras de fase

Uma fase é um pedaço de trabalho dentro de uma sessão: a entrevista, a implementação, a garantia de qualidade. Na fronteira entre duas delas você tem cinco opções, e escolher entre elas é a decisão mais difusa em todo este mapa:

• Continuar: fique parado. Não custa nada, não perde nada.
• /clear: esvazie a janela, quando nada aqui importa para o que vem a seguir.
• /handoff escreve um arquivo markdown portátil. Estreito: apenas para um novo harness, um novo diretório, um colega, ou bifurcar uma tarefa lateral no meio da fase. O que ele compra é portabilidade.
• Subagente: envie uma tarefa de escopo restrito para sua própria janela e receba um relatório de volta.
• /compact comprime este contexto e semeia uma nova sessão com ele. O padrão, no fundo da árvore em vez do primeiro alcance.

Leia PHASE-BOUNDARIES.md para a árvore ordenada: as cinco perguntas, o raciocínio por trás de cada ramificação, e por que o custo da fonte primária faz Continuar ser a primeira a descartar. Tome a decisão na fronteira; no meio da fase, continue ou divida o restante em subagentes.

Independente

Fora do fluxo principal completamente.

• /grill-me: a mesma entrevista implacável que /grill-with-docs, mas stateless: não salva nada localmente e não constrói GLOSSARY.md. Use-o quando não estiver trabalhando em um diretório de trabalho (aguçando um plano, um design, um texto, qualquer coisa sem um repositório por baixo). Se estiver em um diretório de trabalho, use /grill-with-docs em vez disso: ele executa a mesma entrevista e deixa um rastro documental, então é estritamente o melhor.
• /grilling é a primitiva de entrevista em si: rodadas, a fronteira, fatos são trabalho do agente e decisões são suas. /grill-me e /grill-with-docs são as duas formas nomeadas de entrada, e /triage, /wayfinder e /improve-codebase-architecture todas o executam internamente. Use-o diretamente apenas quando quiser a entrevista sem nenhum invólucro.
• /prototype é um programa pequeno e descartável que responde a uma pergunta de design: este modelo de estado parece certo, ou como deve ser esta UI. Descartável é uma restrição sobre como o código é escrito, não uma promessa de destruí-lo: a resposta se dobra no código real, e o protótipo em si é mantido como uma fonte primária em um branch prototype/<name> fora de main, apontado a partir da issue de implementação. É o desvio na etapa 2 do fluxo principal, mas use-o sempre que uma pergunta de design for difícil de resolver no papel.
• /research: delegue trabalho de leitura a um agente de fundo: ele investiga uma pergunta contra fontes primárias, depois deixa um arquivo Markdown citado no repositório. Continue trabalhando enquanto ele lê. O arquivo que ele produz é algo para levar para o fluxo principal em /grill-with-docs, já que a pesquisa alimenta o pensamento em vez de substituí-lo.
• /to-questionnaire entra quando o que está te bloqueando não está na sua cabeça ou no código, mas na de outra pessoa, e ele escreve um questionário para eles preencherem. É o inverso de /grill-me: em vez de entrevistar você sobre o assunto, ele entrevista você sobre o envio (para quem vai, o que você precisa de volta) e aponta as perguntas para a lacuna. O que volta é material para /grill-with-docs ou /to-spec.
• /wizard é para os passos que apenas um humano pode dar: provisionar infraestrutura, configurar credenciais ou segredos de CI, clicar em um dashboard de terceiros desconhecido, executar uma migração ou corte único. Ele gera um script bash interativo que abre cada URL, captura cada valor e o escreve em .env e segredos do GitHub, para que o procedimento pare de ser algo que você reexplica a um agente toda vez. Invocado pelo modelo, então o agente o usa no momento em que encontra uma parede que só você pode passar. Se o agente pudesse simplesmente fazer sozinho, deveria; isso é para quando um humano está genuinamente no loop.
• /wait-what é o corretivo para uma mensagem que não chegou. Use-o no meio da conversa, dentro de qualquer outra skill, e o agente reapresenta o que acabou de dizer com o contexto que você estava perdendo, em português claro, usando o vocabulário de GLOSSARY.md. Funciona depois do fato; /grill-with-docs é a cura proativa, porque uma linguagem compartilhada acordada cedo é o que impede o jargão de chegar.
• /teach: aprenda um conceito ao longo de várias sessões, usando o diretório atual como um workspace stateful.
• /writing-for-agents é a referência para escrever documentos que agentes consomem: skills, AGENTS.md, documentos apontados.

Pré-condição

/setup-matt-pocock-skills: execute antes do seu primeiro fluxo de engenharia para configurar o rastreador de issues, etiquetas de triagem e layout de documentos que as outras skills assumem. Rastreadores de issues personalizados também funcionam.