Razsk/VideoStudio — Roteador de Skills

Ask Matt

Você não lembra de todas as skills, 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 percorre um fluxo principal e duas rampas de acesso que se juntam a ele. Todo o resto é autônomo ou uma camada de vocabulário que roda subjacente.

O fluxo principal: ideia → envio

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

1. /grill-with-docs afia 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 em vez disso, coberto na seção Autônomo. Ambos executam a mesma primitiva /grilling; grill-with-docs é o que deixa um rastro documental, 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 precisar de uma resposta executável (estado, lógica de negócios, uma UI que você precisa ver), desvie por um protótipo, conectado 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, depois abra uma nova sessão naquele arquivo,
   • /prototype para responder à pergunta com código descartável,
   • /handoff de volta o que aprendeu e faça referência a partir do thread da ideia original.

3. Ramificação: esta é uma construção multi-sessão?

   • Sim → /to-spec (transforme o thread 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, limpando o contexto entre cada um (/clear). Em um rastreador local, é 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 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 consolida tudo em um branch de integração. Recorra a ele quando preferir orquestrar a construção a dirigir 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 finalizado 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 um /code-review sobre o branch de integração. Recorra a /tdd por conta própria quando quiser apenas 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 chamada de porta de um ou dois sentidos. É invocado por modelo, então o agente recorre a ele sempre que escreve um PR.

4. /retro fecha o ciclo. Após uma construção, e 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 aplica, 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 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 pensamento. Cada /implement então começa do zero, trabalhando a partir do ticket. Execute /retro na sessão que está sendo analisada, 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 nitidez. Se uma sessão se aproximar dela antes de /to-tickets, não insista na 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 então se funde ao fluxo principal.

• Bugs e solicitações se acumulando → /triage. Ele move issues pelas funções de triagem e produz issues prontas para agente, que /implement pega mais tarde.

  A 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 agente, então não os trie.

• Algo está quebrado → /diagnosing-bugs. Para os difíceis: o bug que resiste a uma primeira olhada, a falha intermitente, a regressão que entrou entre dois estados conhecidamente bons. Ele se recusa a teorizar até ter um ciclo de feedback apertado (um comando que já falha neste bug), então corrige com um teste de regressão. Assim que a correção estiver em vigor, execute /retro na mesma sessão para perguntar o que teria evitado o bug; onde a verdadeira descoberta é que não há uma boa interface 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 mapeia 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 afia uma ideia que você pode manter em uma sessão, wayfinder é para a ideia que você não consegue, e é mais lento e denso, então reserve-o exatamente para isso, nunca para uma funcionalidade bem delimitada.

  Quando o mapa se clareia, ele passa o bastão, não constrói: funda-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. Pular o mapa diretamente para /implement omite 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 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 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 por modelo que rodam abaixo das outras skills, cada uma sendo a fonte única de verdade para seu vocabulário. Recorra a elas diretamente quando as palavras, e não o processo, forem o problema; ou deixe que as skills acima as puxem.

• /domain-modeling: afie a linguagem do domínio do projeto: desafie um termo nebuloso, 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, emenda, adaptador, alavancagem, localidade) para projetar a forma de um módulo: muito comportamento atrás de uma interface pequena em uma emenda limpa. /tdd e /improve-codebase-architecture ambos 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 nebulosa 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 de uma 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 ramo e por que o custo da fonte primária faz Continuar ser a primeira a ser descartada. 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 você não estiver trabalhando em um diretório de trabalho (afiando um plano, um design, um texto, qualquer coisa sem um repositório por baixo). Se você 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 maneiras nomeadas de entrar, e /triage, /wayfinder e /improve-codebase-architecture todos o executam internamente. Recorra a ele 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 UI. Descartável é uma restrição sobre como o código é escrito, não uma promessa de destruí-lo: a resposta é incorporada ao código real, e o próprio protótipo é 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 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 e então deixa um arquivo Markdown citado no repositório. Continue trabalhando enquanto ele lê. O arquivo que ele produz é algo a ser levado 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 o que está te bloqueando não está na sua cabeça ou no código, mas na de outra pessoa, e escreve um questionário para ela 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 as etapas que apenas um humano pode realizar: provisionar infraestrutura, configurar credenciais ou segredos de CI, navegar por 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 nos segredos do GitHub, para que o procedimento pare de ser algo que você reexplica a um agente toda vez. Invocado por modelo, então o agente recorre a ele no momento em que encontra uma barreira que só você pode passar. Se o agente pudesse simplesmente fazer isso sozinho, deveria; isso é para onde um humano está genuinamente no ciclo.
• /wait-what é a correção para uma mensagem que não foi compreendida. Use-a 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 inglês simples, usando o vocabulário do 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 ao longo de várias sessões, usando o diretório atual como um espaço de trabalho stateful.
• /writing-for-agents é a referência para escrever documentos que agentes consomem: skills, AGENTS.md, docs 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.