Castle-Solutions/landing

Pergunte ao Matt

Você não se lembra de todas as habilidades, então pergunte.

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

Um fluxo é um caminho através das habilidades. A maioria dos caminhos percorre um fluxo principal e duas rampas de acesso se fundem a ele. Todo o resto é autônomo ou uma camada de vocabulário que funciona por baixo.

O fluxo principal: ideia → lançamento

A rota pela qual a maioria do trabalho passa. Você tem uma ideia e quer que ela seja construída.

1. /grill-with-docs aprimora 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 um diretório de trabalho? Use /grill-me, abordado em Autônomo. Ambos executam a mesma primitiva /grilling; grill-with-docs é aquele que deixa um rastro de papel, o que o torna o melhor dos dois sempre que houver um repositório para deixá-lo.)

2. Ramificação: você consegue resolver todas as perguntas em conversa? Se uma pergunta precisa de uma resposta executável (estado, lógica de negócio, uma IU que você precisa ver), desvie por um protótipo, interligado 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 Limites de fase):

   • /handoff para fora, então abra uma nova sessão contra esse arquivo,
   • /prototype para responder à pergunta com código descartável,
   • /handoff de volta o que você aprendeu, e referencie-o a partir do tópico de ideia original.

3. Ramificação: esta é uma construção de múltiplas sessões?

   • Sim → /to-spec (transforme o tópico em uma especificação), depois /to-tickets para dividi-lo em tickets de bala traçadora, cada um declarando suas arestas de bloqueio. Em seguida, trabalhe os tickets de uma das duas maneiras:
     • /implement por ticket, /clearando o contexto entre cada um deles. Em um rastreador local, isso é um arquivo por ticket em .scratch/<feature>/issues/, trabalhados primeiro pelos bloqueadores manualmente; em um rastreador real, as arestas se tornam links de bloqueio nativos, então qualquer ticket cujos bloqueadores estão prontos pode ser pego. Cada ticket é autossuficiente, 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 consolida tudo em um único branch de integração. Recorra a ele 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 conduzindo /tdd (uma fatia vermelho-verde de cada vez) e finaliza com /code-review, uma revisão de dois eixos (Padrões + Especificação) do diff. /implement executa ambos por ticket; /implement-spec's implementadores cada um conduz /tdd, e ele executa uma única /code-review sobre o branch de integração. Recorra a /tdd por conta própria quando você só quiser construir um comportamento concreto test-first sem uma especificação completa, e /code-review por conta própria sempre que quiser revisar um branch ou PR contra um ponto fixo.

   Quando o trabalho é enviado como um pull request, /pr molda o corpo: o menor visual que mostra a mudança, evidências de antes/depois de que funciona, e uma decisão de porta de mão única ou dupla. É invocado pelo modelo, então o agente recorre a ele sempre que escreve um PR.

4. /retro fecha o ciclo. Após uma construção, especialmente uma que deu errado, ele analisa a 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 impõe, arquivos de direção, ferramentas. Erros mecânicos se tornam verificações determinísticas; decisões de julgamento se tornam padrões de codificação. A próxima construção começa então de um ambiente melhor.

Higiene de contexto

Mantenha as etapas 1–3 em uma janela de contexto ininterrupta (não comprima ou limpe até depois de /to-tickets) para que a entrevista, especificação e tickets se baseiem no mesmo pensamento. Cada /implement então começa novo, trabalhando a partir do ticket. Execute /retro na sessão que está revisando, antes de limpar; após 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 clareza. Se uma sessão se aproximar dela antes de /to-tickets, não continue com degradação; use /compact no limite de fase mais próximo e continue (veja Limites de fase).

Rampas de acesso

Uma situação inicial que gera trabalho e depois se funde 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 agente, que /implement posteriormente pega.

  Triagem é apenas para issues que você não criou: relatórios de bug, solicitações de funcionalidades 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 quebrou → /diagnosing-bugs. Para os difíceis: o bug que resiste a uma primeira olhada, a falha intermitente, a regressão que se infiltrou entre dois estados conhecidamente bons. Ele se recusa a teorizar até ter um loop de feedback apertado (um comando que já fica vermelho com esse bug), então corrige com um teste de regressão. Uma vez que a correção está em vigor, execute /retro na mesma sessão para perguntar o que teria prevenido o bug; onde a verdadeira descoberta é que não há uma boa costura para travá-lo, isso é um trabalho para /improve-codebase-architecture.

• Um esforço enorme e nebuloso: um projeto greenfield ou uma enorme 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. Onde /grill-with-docs aprimora uma ideia que você pode segurar em uma sessão, wayfinder é para a ideia que você não pode, e é mais lento e denso, então guarde-o exatamente para isso, nunca para uma funcionalidade bem escopada.

  Quando o mapa clarear, ele faz a transição, não constrói: funda-se no fluxo principal em /to-spec, que colapsa as decisões vinculadas do mapa em um plano construível, então /to-tickets e /implement como de costume. Loopar o mapa diretamente para /implement pula esse colapso e joga fora o detalhe vinculado, então vá direto para /implement apenas quando o esforço se revelar genuinamente pequeno.

Saúde do codebase

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

• /improve-codebase-architecture é executado sempre que você tiver um momento livre para manter o codebase 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. É a pesquisa 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 por baixo das outras habilidades, cada uma a única fonte da verdade para seu vocabulário. Recorra a elas diretamente quando as palavras, não o processo, são o problema; ou deixe as habilidades acima as puxarem.

• /domain-modeling: aprimora a linguagem de domínio do projeto: desafie um termo confuso, 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 conduz para manter GLOSSARY.md um glossário limpo.
• /codebase-design é o vocabulário de módulo profundo (módulo, interface, profundidade, costura, adaptador, alavancagem, localidade) para projetar a forma de um módulo: muito comportamento por trás de uma interface pequena em uma costura limpa. Tanto /tdd quanto /improve-codebase-architecture falam essa linguagem.

Limites de fase

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

• Continuar: fique onde está. 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 apertado 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 o primeiro a descartar. Tome a decisão em um limite; no meio da fase, continue ou divida o restante em subagentes.

Autônomo

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. Recorra a ele quando não estiver trabalhando em um diretório de trabalho (aprimorando um plano, um design, um pedaço de escrita, qualquer coisa sem um repositório por baixo). Se você estiver em um diretório de trabalho, use /grill-with-docs: ele executa a mesma entrevista e deixa um rastro de papel, 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 a executam internamente. Recorra a ela diretamente apenas 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 parece certo, ou como deve ser esta IU. 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/<nome> fora de main, apontado a partir da issue de implementação. É o desvio na etapa 2 do fluxo principal, mas recorra a ele sempre que uma pergunta de design for difícil de resolver no papel.
• /research: delegue o trabalho de leitura a um agente de fundo: ele investiga uma questão contra fontes primárias, então 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 em cena quando a coisa que está te bloqueando não está na sua cabeça ou no codebase, mas na de outra pessoa, e ele escreve um questionário para essa pessoa preencher. É 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 painel de terceiros desconhecido, executar uma migração ou cutover ú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 recorre a ele no momento em que atinge um muro que só você pode passar. Se o agente pudesse simplesmente fazer isso sozinho, deveria; isso é para onde 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 habilidade, 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 preventiva, porque uma linguagem compartilhada acordada cedo é o que impede o jargão de chegar.
• /teach: aprenda um conceito em múltiplas sessões, usando o diretório atual como uma área de trabalho stateful.
• /writing-for-agents é a referência para escrever documentos que agentes consomem: habilidades, 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, rótulos de triagem e layout de documentos que as outras habilidades assumem. Rastreadores de issues personalizados também funcionam.