grill-with-docs

Visão geral do skill grill-with-docs

grill-with-docs é um skill de planejamento e documentação para equipes que querem testar uma proposta contra a linguagem e as decisões já registradas no repositório. Ele é ideal para Technical Writing, engenharia com mentalidade de produto e trabalho de arquitetura assistido por IA, em que os termos precisam permanecer alinhados com CONTEXT.md e ADRs, em vez de derivar para um texto vago “só de prompt”.

A função principal é simples: entrevistar o usuário uma pergunta por vez, sugerir respostas e usar o codebase ou a documentação quando uma questão puder ser resolvida pela fonte. Isso torna o skill grill-with-docs mais útil do que um prompt genérico de brainstorming quando o risco real é desencontro de terminologia, pressupostos não documentados ou registros de decisão desatualizados.

O que diferencia o grill-with-docs

Ele foi construído em torno de consciência de domínio, não apenas de conversa. O skill incentiva você a verificar arquivos de contexto existentes, analisar ADRs e atualizar a documentação à medida que as decisões ficam claras, por isso funciona tão bem para grill-with-docs for Technical Writing e outros fluxos de trabalho com forte dependência de documentação.

Casos de uso ideais

Use grill-with-docs quando você precisar:

• validar um plano contra um modelo de domínio já existente,
• escolher terminologia precisa para o projeto,
• registrar decisões conforme elas vão sendo tomadas,
• ou manter um rascunho alinhado com a documentação estabelecida antes do início da implementação.

Quando ele não é a melhor opção

Se você quer só um resumo rápido, uma especificação polida ou ideação livre sem ancoragem no repositório, este skill vai parecer mais lento do que um prompt comum. O valor está no questionamento disciplinado e na checagem orientada pela documentação.

Como usar o skill grill-with-docs

Instale o grill-with-docs

Instale o skill grill-with-docs no seu diretório de skills com o gerenciador padrão do repositório e, em seguida, abra os arquivos do skill no contexto do projeto-alvo. O padrão básico de instalação é:

npx skills add mattpocock/skills --skill grill-with-docs

Trate isso como o ponto de partida de grill-with-docs install e confirme depois que o skill está disponível no ambiente de agente que você realmente usa.

Comece com a entrada certa

O skill funciona melhor quando a primeira mensagem inclui:

• o objetivo que você está planejando,
• o nome do sistema ou funcionalidade,
• quaisquer termos conhecidos que importam,
• e o limite da decisão que você quer resolver.

Um prompt fraco diz: “Me ajude a projetar esta funcionalidade.”
Um prompt mais forte diz: “Use grill-with-docs para testar este plano de feature contra o domínio atual de billing. Preciso do termo certo para ‘subscription period’, da estrutura de dados e de quaisquer decisões dignas de ADR antes de escrever a documentação.”

Leia estes arquivos primeiro

Para grill-with-docs usage, comece por:

• SKILL.md para entender o comportamento da entrevista e o fluxo de trabalho,
• CONTEXT.md ou CONTEXT-MAP.md para o modelo de domínio ativo,
• docs/adr/ para decisões anteriores,
• ADR-FORMAT.md e CONTEXT-FORMAT.md se você precisar criar ou atualizar arquivos.

Esses arquivos mostram o que pode ser inferido a partir do repositório e o que precisa ser registrado explicitamente.

Fluxo de trabalho que melhora o resultado

Use o skill em loop:

1. traga um plano concreto ou um rascunho inicial,
2. deixe o skill fazer uma pergunta por vez,
3. responda com o detalhe mais específico possível, ancorado no repositório,
4. permita a exploração do codebase quando a pergunta puder ser respondida a partir dos arquivos,
5. registre terminologia e decisões difíceis em notas de contexto ou ADR.

A dica prática mais importante é separar “precisamos de um nome” de “precisamos de uma decisão”. Isso mantém o grill focado e evita ADRs desnecessários.

FAQ do skill grill-with-docs

O grill-with-docs é só para equipes de documentação?

Não. Ele é útil sempre que um plano precisa corresponder a um vocabulário de domínio já existente, especialmente em engenharia de produto, trabalho de plataforma ou fluxos grill-with-docs for Technical Writing, em que a redação e a estrutura afetam a clareza adiante.

Em que isso difere de um prompt normal?

Um prompt comum pode gerar ideias, mas grill-with-docs foi desenhado para interrogar pressupostos, checar o repositório e ajustar termos com base no contexto existente. Isso reduz a chance de colisões de nomenclatura e de documentação que entra em conflito com o codebase.

Preciso de uma estrutura de documentação madura para usar isso?

Não, mas ele funciona melhor quando CONTEXT.md e ADRs já existem. Se não existirem, o skill ainda pode ajudar você a defini-los aos poucos, conforme as decisões forem surgindo.

Quando devo evitar usar isso?

Evite quando a tarefa for puramente exploratória, o repositório não tiver um contexto de domínio relevante ou você precisar de uma resposta rápida e única, em vez de uma entrevista estruturada.

Como melhorar o skill grill-with-docs

Alimente com material de decisão melhor

O maior ganho de qualidade vem de dar ao skill um prompt estreito e orientado à decisão. Inclua o nome da funcionalidade, a parte do sistema que ela toca e a ambiguidade exata que você quer resolver. Exemplo: “Devemos chamar isso de invoice, billing record ou charge no contexto financeiro, e onde essa decisão deve ficar?”

Traga evidências do repositório cedo

Se você já conhece arquivos relevantes, mencione isso logo de cara. Apontar o skill para CONTEXT.md, um ADR específico ou uma pasta como src/billing/ ajuda a fazer menos perguntas genéricas e mais perguntas úteis. Isso é ainda mais importante para grill-with-docs usage, porque o skill funciona melhor quando consegue comparar seu plano com os termos e a estrutura já existentes.

Fique atento aos modos de falha comuns

O principal modo de falha é especificar pouco o domínio, fazendo a entrevista ficar abstrata. Outro é pedir implementação antes de o modelo de linguagem ter os termos certos. Se a primeira saída parecer ampla demais, reformule a decisão em termos mais restritos e peça ao skill para continuar a partir do último ramo resolvido.

Itere a partir da primeira rodada

Depois da primeira rodada, transforme as respostas em um de três formatos: uma entrada de glossário revisada, um ADR curto ou um brief de implementação ajustado. Em seguida, rode grill-with-docs de novo nas perguntas que ainda ficaram em aberto. Essa segunda passagem costuma ser a que mais vale a pena, porque a terminologia e os limites já estão mais claros.