Brians-brain/claude-skills

Pergunte ao Matt

Responda ao usuário em português.

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

Antes de explicar o que uma skill faz ou sugerir pular uma etapa, leia o SKILL.md dela: o resumo aqui é apenas para orientação.

Um fluxo é um caminho através dessas skills. A maioria dos caminhos segue um fluxo principal, com duas rampas que se juntam a ele. Os demais são de uso independente ou operam como camadas de vocabulário subjacentes.

Fluxo Principal: Ideia → Lançamento

O caminho que a maior parte do trabalho percorre. Você tem uma ideia e quer transformá-la em algo concreto.

1. /grill-with-docs — Apure a ideia através de entrevistas. Se você estiver trabalhando em um diretório de trabalho, comece aqui: ele tem estado e mantém o aprendizado em GLOSSARY.md e ADRs. (Não tem um diretório de trabalho? Use /grill-me, veja "Uso Independente". Ambos executam o mesmo mecanismo /grilling; grill-with-docs deixa registros escritos, então sempre que houver um repositório, ele é a melhor opção.)

2. Ramificação: Todo problema pode ser resolvido na conversa? Se um problema precisar de uma resposta executável (estado, lógica de negócios, uma interface que você precisa ver), desvie para prototipagem, usando /handoff em ambas as direções (o protótipo fica em seu próprio diretório — é exatamente para isso que serve /handoff; veja "Fronteiras de Fase"):

   • Use /handoff para transferir, depois abra uma nova sessão para aquele arquivo,
   • Use /prototype para responder à pergunta com código descartável,
   • Use /handoff para trazer o aprendizado de volta e referencie-o a partir do tópico da ideia original.

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

   • Sim → /to-spec (transforme o tópico em uma especificação), depois use /to-tickets para dividi-la em tickets bullet tracer, cada um com seu bloqueio indicado. Em seguida, processe os tickets de uma das seguintes formas:
     • Um /implement para cada ticket, limpando o contexto (/clear) entre eles. No rastreador local, isso significa um arquivo por ticket em .scratch/<feature>/issues/, processados manualmente na ordem de prioridade de bloqueio; no rastreador real, os bloqueios viram links nativos, então qualquer ticket cujos bloqueadores já estejam concluídos pode ser iniciado. Cada ticket é autossuficiente, então o contexto do anterior pode ser descartado.
     • Use /implement-spec para executar a especificação inteira de uma vez. Ela lê os tickets como um grafo de tarefas, executa agentes de implementação em paralelo na fronteira pronta, e coloca tudo em um único branch de integração. Use quando preferir coordenar toda a construção em vez de avançar ticket por ticket.
   • Não → Use /implement aqui mesmo, na mesma janela de contexto.

   Em ambos os casos, o código é construído com /tdd (um slice red-green de cada vez) e finalizado com /code-review-zh, uma revisão dupla (Padrões + Especificação) sobre o diff. /implement executa ambos para cada ticket; /implement-spec faz cada implementador usar /tdd e depois executa /code-review-zh no branch de integração. Use /tdd sozinho quando quiser apenas criar um comportamento específico orientado a testes sem uma especificação completa; use /code-review-zh sozinho sempre que quiser revisar um branch ou PR contra um ponto fixo.

   Quando o trabalho for enviado como pull request, /pr determina a forma do conteúdo do PR: a menor apresentação visual da mudança, evidências de antes/depois que provem que funciona, e um julgamento de porta unidirecional vs. bidirecional. Ele é invocado por modelo, então o agente o usa toda vez que escreve um PR.

4. /retro — Feche o ciclo. Após uma construção, especialmente se algo deu errado, ele revisa a sessão e sugere melhorias no ambiente de trabalho do agente, não no código: indicadores de navegação, verificações automáticas, convenções de escrita executadas por /code-review-zh, arquivos de guia, ferramentas. Erros mecânicos viram verificações determinísticas; julgamentos viram convenções de escrita. A próxima construção começa de um ambiente melhor.

Higiene de Contexto

Mantenha os passos 1–3 na mesma janela de contexto ininterrupta (não compacte nem limpe antes de /to-tickets), para que o esclarecimento, a especificação e os tickets sejam construídos sobre o mesmo raciocínio. Depois disso, cada /implement começa do zero, trabalhando a partir do ticket. Execute /retro na sessão a ser revisada, antes de limpar; se já tiver limpado, aponte-o para o registro daquela sessão.

A limitação disso é a zona inteligente: a janela na qual o modelo ainda consegue raciocinar com agudeza (cerca de 150 mil tokens nos modelos mais avançados). Se uma sessão estiver se aproximando desse limite antes de /to-tickets, não force em estado degradado; execute /compact na fronteira de fase mais recente e continue (veja "Fronteiras de Fase").

Rampas

Contextos iniciais que geram trabalho e depois se juntam ao fluxo principal.

• Bugs e pedidos se acumulam → /triage. Ele faz os issues circularem entre papéis de triagem, produzindo issues prontos para o agente, que depois são assumidos por /implement.

  Use triagem apenas para issues que você não criou: relatos de bugs, solicitações de funcionalidades recebidas, qualquer coisa que chegue sem tratamento. Os tickets gerados por /to-tickets já estão prontos para o agente, então não os trie.

• Algo quebrou → /diagnosing-bugs. Para os difíceis: bugs que não são óbvios à primeira vista, instabilidade intermitente, regressões que entram sorrateiramente entre dois estados conhecidos como bons. Ele se recusa a propor teorias até ter um loop de feedback apertado (um comando que já fica vermelho por causa deste bug), e então corrige com um teste de regressão. Depois de corrigido, execute /retro na mesma sessão e pergunte o que pode prevenir esse bug; se a descoberta real for que não há uma boa costura para travá-lo, esse é um trabalho para /improve-codebase-architecture.

• Um projeto grande e nebuloso: projeto novo ou construção de funcionalidade enorme que não cabe em uma sessão → /wayfinder, o fluxo que mais exige cognitivamente. Quando o caminho daqui até o destino ainda não está visível, ele desenha um mapa compartilhado de tickets de decisão no rastreador de issues, resolvendo um de cada vez, produzindo decisões em vez de artefatos, até a névoa se dissipar e o caminho ficar claro. /grill-with-docs apura ideias que cabem em uma sessão; wayfinder é para ideias que não cabem, e é mais lento e denso, então reserve-o apenas para esse caso, nunca para funcionalidades de escopo claro.

  Quando o mapa estiver claro, ele passa o bastão, não constrói: entre no fluxo principal via /to-spec, que converge as decisões conectadas do mapa em um plano construtível, e então siga normalmente com /to-tickets e /implement. Conectar o mapa diretamente ao /implement pula essa convergência e perde os detalhes das conexões, então só faça isso se o projeto acabar sendo realmente pequeno.

Saúde do Código

Não é desenvolvimento de funcionalidades, é apenas manutenção.

• /improve-codebase-architecture — Execute quando tiver tempo livre para manter o código em um estado adequado para o trabalho do agente. Ele identifica oportunidades de aprofundamento; selecionar uma delas gera uma ideia, que você pode levar para o /grill-with-docs no fluxo principal. É uma prospecção para encontrar candidatos; /codebase-design (veja abaixo) é a bancada onde você projeta o candidato selecionado.

Vocabulário Subjacente

Duas referências invocadas por modelo que operam sob outras skills, cada uma sendo a fonte única da verdade para seu vocabulário. Use-as diretamente quando o problema for de terminologia em vez de fluxo; ou deixe que as skills acima as tragam.

• /domain-modeling: Apure a linguagem de domínio do projeto: desafie um termo ambíguo, resolva uma palavra sobrecarregada (ex.: "código do material" significando três coisas diferentes), registre uma decisão difícil de reverter como ADR. É a disciplina ativa que /grill-with-docs usa para manter GLOSSARY.md limpo.
• /codebase-design é o vocabulário de módulos profundos (módulos, interfaces, profundidade, costuras, adaptadores, alavancas, localidade), usado para projetar a forma dos módulos: muito comportamento atrás de interfaces pequenas, em costuras limpas. /tdd e /improve-codebase-architecture o utilizam.

Fronteiras de Fase

Uma fase é um bloco de trabalho dentro de uma sessão: esclarecimento, implementação, QA. Na fronteira entre duas fases, você tem cinco opções, e escolher entre elas é a decisão mais difusa de todo o mapa:

• Continuar: Fique onde está. Sem custo, sem perda.
• /clear: Limpe a janela, quando nada daqui for importante para o que vem a seguir.
• /handoff: Escreva um arquivo markdown portátil. Uso restrito: apenas para trocar de plataforma de execução, trocar de diretório, passar para um colega, ou desviar uma subtarefa no meio de uma fase. Ele compra portabilidade.
• Subagente: Envie uma tarefa de escopo claro para sua própria janela e receba um relatório de volta.
• /compact: Comprima o contexto e use-o para iniciar uma nova sessão. É o padrão, no fundo da árvore, não o primeiro a pegar.

A árvore de decisão ordenada está em PHASE-BOUNDARIES.md: cinco perguntas, a razão por trás de cada ramo, e por que o custo de informação de primeira mão faz de Continuar a primeira opção a ser descartada. Tome a decisão na fronteira; no meio da fase, continue ou delegue o resto do trabalho a subagentes.

Uso Independente

Completamente fora do fluxo principal.

• /grill-me: A mesma entrevista rigorosa de /grill-with-docs, mas sem estado: não salva nada localmente, nem cria GLOSSARY.md. Use quando não estiver trabalhando em um diretório de trabalho (apurar um plano, um design, um artigo — qualquer coisa sem um repositório por baixo). Se estiver em um diretório de trabalho, use /grill-with-docs: ele faz a mesma entrevista e ainda deixa registros escritos, então é absolutamente melhor.
• /grilling é o mecanismo básico da entrevista em si: rodadas, fronteira, descobrir fatos é trabalho do agente, tomar decisões é seu trabalho. /grill-me e /grill-with-docs são duas entradas nomeadas, e /triage, /wayfinder e /improve-codebase-architecture o executam internamente. Só use diretamente quando quiser a entrevista sem nenhum invólucro.
• /prototype: Um pequeno programa descartável que responde a uma pergunta de design: este modelo de estado faz sentido, ou como deve ser essa interface? "Descartável" é uma restrição sobre como o código é escrito, não uma promessa de destruí-lo: a resposta é integrada ao código formal, e o protótipo em si é preservado como fonte primária em um branch prototype/<nome> fora do main, referenciado a partir do issue de implementação. É o desvio do passo 2 do fluxo principal, mas pode ser usado sempre que uma pergunta de design for difícil de resolver no papel.
• /research: Delegue o trabalho braçal de leitura a um agente de fundo: ele investiga uma pergunta a partir de fontes primárias e deixa um arquivo Markdown com citações no repositório. Enquanto ele lê, você continua trabalhando. O arquivo que ele produz deve ser levado para o fluxo principal /grill-with-docs, pois pesquisa alimenta o pensamento, não o substitui.
• /to-questionnaire: Use quando o que está te travando não está na sua cabeça nem no código, mas na cabeça de outra pessoa. Ele ajuda a escrever um questionário para essa pessoa preencher. É o oposto de /grill-me: não entrevista você sobre o tópico em si, mas entrevista você sobre o envio (para quem enviar, o que precisa receber de volta) e mira as perguntas nas lacunas. O que você recebe de volta é material para /grill-with-docs ou /to-spec.
• /wizard: Para etapas que só humanos podem fazer: configurar infraestrutura, definir credenciais ou segredos de CI, navegar por um painel de terceiros desconhecido, executar migrações ou chaveamentos únicos. Ele gera um script bash interativo que abre cada URL, captura cada valor e escreve em .env e segredos do GitHub, tornando o procedimento algo que não precisa ser reexplicado ao agente toda vez. É invocado por modelo, então o agente o usa sempre que encontra uma parede que só você pode atravessar. Se o agente puder fazer sozinho, ele deve fazer; isso é para casos em que realmente é necessário um humano no loop.
• /wait-what: Um remédio para mensagens que não foram compreendidas. Pode ser usado no meio da conversa, dentro de qualquer outra skill; o agente preenche o contexto que falta, reexplicando o que acabou de dizer em linguagem simples, usando o vocabulário de GLOSSARY.md. É um remédio a posteriori; /grill-with-docs é o antídoto a priori, porque uma linguagem comum acordada cedo faz com que os termos não surjam inesperadamente.
• /teach: Aprenda um conceito ao longo de várias sessões, usando o diretório atual como espaço de trabalho com estado.
• /writing-for-agents: Referência para escrever documentação voltada a agentes: skills, AGENTS.md/CLAUDE.md, documentos referenciados.
• /handoff: Comprima a conversa atual em um documento de transferência para uma nova sessão, novo diretório ou colega (veja "Fronteiras de Fase").
• /git-guardrails-claude-code: Instala um hook do Claude Code que bloqueia comandos git perigosos (push, reset --hard, etc.) antes de serem executados. Configure uma vez por computador ou por projeto.

Pré-requisitos

/setup-matt-pocock-skills: Execute antes de usar fluxos de engenharia pela primeira vez. Configura o rastreador de issues, as tags de triagem e a estrutura de documentos assumidos pelas outras skills. Também suporta rastreadores de issues personalizados.