2D0/claude-skills

blackbox

Visão Geral

Uma blackbox é o gravador de voo de um item: um registro de decisão não resumido por unidade de mudança aprovada pelo proprietário — o que o proprietário realmente disse (verbatim), o que significava no contexto, o que o assistente recomendou e construiu, porquê, as evidências que motivaram cada escolha, e o que o assistente errou ao longo do caminho — fixado ao conteúdo que explica e lido apenas sob demanda. Ela existe para que uma sessão futura audite a origem de uma regra em vez de re-litigá-la.

Duas coisas que ela não é:

• Não é uma transcrição. Selecionar não é resumir. A entrada é escrita a partir do rastro de decisões, não do histórico do chat: ensinamentos, analogias e desvios que ajudaram o proprietário a entender, mas que não alteraram nenhuma decisão, são omitidos. O que é mantido é mantido na íntegra.
• Não é um diário sobre o proprietário. Registra o que foi dito e decidido, não quem o proprietário é. Observações sobre estilo de trabalho pertencem à memória do assistente, nunca aqui.

Este item possui uma blackbox?

• blackbox/README.md ao lado do item (ou na raiz do repositório) → a convenção se aplica. Leia esse README E a entrada mais recente antes de escrever a sua — o esquema vem deles, nunca da sua cabeça.
• Sem marcador, e o proprietário pede para adotar um → inicialize: copie blackbox/README.md do diretório deste skill para o item, alterando apenas o nome do item, e registre a própria adoção como a primeira entrada.
• Sem marcador, e você está prestes a editar um documento de especificação / convenção / design pela primeira vez nesta sessão → verifique se há o marcador. Se ausente, ofereça a adoção uma vez, em uma frase, e continue a tarefa do proprietário. A adoção é uma decisão do proprietário; se ele recusar, anote na memória para que o repositório não seja perguntado novamente.

A unidade de adoção é o diretório que contém o marcador — um skill, um pacote ou um repositório inteiro. Qualquer repositório, qualquer método de merge.

Unidade e momento

• Uma entrada por unidade aprovada pelo proprietário: uma especificação confirmada, um PR mergeado, uma convenção revisada. Não por commit, não por turno de conversa. Uma unidade que produziu vários commits recebe uma única entrada.
• Escrita na sessão onde as decisões ocorreram. A troca bruta existe apenas no contexto atual; quando a sessão termina, apenas resumos sobrevivem e as citações verbatim desaparecem. Se uma unidade for longa ou abranger várias sessões, salve um rascunho cedo — Refs: pendente, citações do proprietário e o índice preenchidos — e finalize (fixe os blobs, complete o corpo) na aprovação. Um rascunho é melhor do que uma memória reconstruída.

A receita (por unidade aprovada pelo proprietário)

1. Faça a alteração.
2. Fixe os resultados por conteúdo. Para cada arquivo alterado, git hash-object <caminho> na árvore de trabalho. SHAs de blob são endereçados por conteúdo — os mesmos bytes geram o mesmo hash para sempre, então a fixação sobrevive a squash, rebase e qualquer reescrita de histórico, e existe antes de qualquer commit.
3. Escreva a entrada blackbox/YYYY-MM-DD-<slug>.md no formato abaixo: um índice que aponta para o corpo, depois o corpo bruto.
4. Inclua a entrada junto com a alteração — no mesmo commit ou no mesmo PR, mergeado da forma que o repositório normalmente faz merge.

Verifique uma fixação: git hash-object <caminho> e compare. Recupere um estado fixado: git log --find-object=<sha> ou a API de blobs do GitHub.

Regra de leitura: nunca carregue blackbox/ durante o trabalho normal no item. Leia apenas para questões de proveniência.

Formato da entrada

# YYYY-MM-DD — <título>

Refs:           <caminho> @ blob <sha>            (uma linha por arquivo alterado)
Decisões:       <decisão> <peso> [→ <novo peso>, ver §…] · …
Reversões:      §… · §…   (ou: nenhuma)
Proprietário detectou:   §… · …    (ou: nenhum)
Recusado:       §… · …    (ou: nenhum)
Evidências:     <comando / número / link> · …
Entendimento:   §…        (ou: n/d)
---
<corpo bruto, com cabeçalhos § para os quais o índice aponta>

Linhas do índice apontam para o corpo; elas nunca o substituem.

• Decisões — toda decisão que a unidade contém, com o peso que o assistente atribuiu ao perguntar (🔴 deve decidir agora · 🟡 decidir, revisável · 🟢 aceitar a recomendação). Se um peso foi alterado posteriormente, diga e aponte para o porquê. Com o tempo, esta linha é como o proprietário audita sua própria deliberação contra o peso que a decisão merecia.
• Reversões — tudo o que o assistente afirmou e depois retirou ou corrigiu: uma afirmação errada, uma recomendação revertida por medição, uma decisão que tomou sem perguntar. nenhuma é um valor válido e deve ser escrito explicitamente.
• Proprietário detectou — inconsistências ou falhas que o proprietário identificou (uma contagem errada, um item faltando, um bug estrutural). A auditoria do proprietário, não apenas a do assistente.
• Recusado — opções, padrões de ferramentas ou recomendações externas deliberadamente não adotadas, com a razão no corpo.
• Evidências — o que foi realmente consultado ao decidir: o comando executado, os números que produziu, a página ou arquivo exibido. Registre a reprodução, não a imagem — um diagrama é regenerado a partir de seu comando; uma captura de tela não é.
• Entendimento — quando o proprietário aprovou enquanto dizia que não entendia completamente, sua declaração e o que deve ser reexplicado posteriormente.

Idioma

• Corpo: inglês, independentemente do idioma dos documentos do repositório.
• Entrada do proprietário: o original verbatim, depois uma reformulação em inglês. O verbatim primeiro, em uma citação >, exatamente como digitado — erros de digitação, abreviações, ㅇ e tudo. Depois a reformulação: completa em conteúdo, natural na forma, autocontida (um leitor sem nenhum outro contexto a entende). O verbatim é a evidência — um erro de digitação que alterou uma decisão só pode ser encontrado ali. A reformulação é a leitura do assistente na época — se os dois discordam, a entrada já registrou a falha.
• Respostas do assistente, raciocínio e processamento interno: em inglês, na forma completa para tudo que influencia uma decisão. > ㅇ seguido de O proprietário aprovou a opção (a). é um registro completo; não o preencha.

Formas rígidas

Regra	Não isso
Entrada do proprietário = citação verbatim e reformulação em inglês	Apenas o verbatim (ilegível sem contexto), apenas a reformulação (evidência perdida) ou um resumo de uma linha
Índice no topo, corpo bruto abaixo, linhas do índice apontando para cabeçalhos §	Um índice que resume em vez de apontar; um corpo sem índice; seções preenchidas com frases curtas
Corpo extraído do rastro de decisões	Ensinamentos, analogias ou desvios que não alteraram nenhuma decisão
Reversões: presente, mesmo como nenhuma	Uma entrada que lista apenas o que deu certo
Refs: = SHAs de blob por arquivo (git hash-object)	Um número de commit ou PR como âncora — reescritas de histórico matam esses
Entrada incluída no mesmo commit ou PR que a alteração	Um PR de acompanhamento "depois"
Escrita na sessão onde as decisões ocorreram	Reconstruída na próxima sessão a partir da memória
Esquema da entrada vindo do README e da entrada mais recente	Um formato inventado

Sinais de alerta

• Uma entrada sem linha Refs: ou com Refs: nomeando um commit ou PR em vez de blobs
• Uma entrada do proprietário sem citação > verbatim, ou uma citação sem reformulação após ela
• Linha Reversões: ausente
• Linhas do índice que funcionam como resumos em vez de ponteiros
• Um corpo que explica conceitos ao leitor em vez de registrar o que foi decidido
• Uma alteração mergeada sem sua entrada
• Uma entrada escrita na sessão após as decisões que registra (diga isso na entrada se inevitável)

Proveniência

blackbox/ contém o registro completo de decisões para este item — entradas do proprietário (verbatim + reformulações em inglês), raciocínio do assistente, evidências e reversões, fixadas por conteúdo por alteração aprovada. Leia apenas ao investigar por que uma regra existe ou o que o proprietário pediu originalmente. Nunca carregue durante o uso normal.