chrislacey89/compound

O que compound faz?

Documente um problema recentemente resolvido ou uma funcionalidade entregue para enriquecer o conhecimento do seu projeto. Cada solução documentada torna o planejamento e a implementação futuros mais rápidos — o agente consulta docs/solutions/ durante /research e /write-a-prd, então as lições aprendidas hoje evitam erros amanhã.

Quando o trabalho revelar surpresas de planejamento ou estimativa, capture-as também. A calibração no estilo McConnell só acontece se o trabalho real alimentar a modelagem futura.

Posição de Invocação

Esta é uma habilidade primária do pipeline que fecha o ciclo de reforço. Ela é executada perto do final do caminho de entrega padrão, depois que /pre-merge criou o PR.

Padrão — capture a lição no PR, antes do merge. Quando uma lição durável já é conhecida no momento do PR, execute /compound no branch do PR aberto para que a entrada em docs/solutions/ acompanhe o mesmo PR que o código que a gerou — revisada antes do mesmo merge e mesclada atomicamente com ele. Isso posiciona /compound entre /pre-merge e /closeout, e retorna via /pre-merge uma vez:

… → /pre-merge → /compound (no PR, quando existe uma lição) → /pre-merge (re-executado: o commit composto é o delta pós-carimbo; re-carimba) → /closeout (merge + teardown) → cleanup

A perna de retorno não é decoração. Commitar no branch move a cabeça para além do carimbo que /pre-merge Fase 4 escreveu, e /pre-merge é o único escritor do carimbo — portanto, sem a reexecução, a entrada é mesclada com o código e lida por ninguém, que é exatamente o que o padrão no PR foi escolhido para evitar. A Fase 5 declara a passagem de bastão; é por isso que ela existe.

Fallback — capture pós-merge. Algumas lições só surgem durante ou após o merge: surpresas de integração, descobertas de QA, comportamento observado apenas quando é lançado. Para esses casos, execute /compound depois que /closeout tiver feito o merge. Este é o caminho de fallback, não o padrão.

De qualquer forma, /compound nunca realiza o merge ou o teardown do diretório de trabalho — isso é função de /closeout — e nunca escreve o carimbo de moeda de revisão, que é exclusivo do /pre-merge. Capturar no PR significa commitar no branch do PR aberto e devolver o controle para a revisão que o cobre; não significa fazer o merge.

Não use para edições triviais ou para lições que pertencem inteiramente a um artefato de maior fidelidade, como um teste, regra de linter ou comentário de código, sem nenhum aprendizado durável em nível de projeto. Seja no PR ou pós-merge, a proteção "Quando NÃO Usar" abaixo ainda se aplica — a maioria dos PRs não carrega uma lição durável, e não há uma vaga fixa por PR em docs/solutions/ a ser preenchida.

Por Que Isso Existe

Sem esta etapa, você fez engenharia tradicional com assistência de IA. As três primeiras etapas do fluxo de trabalho (planejar, trabalhar, revisar) produzem uma funcionalidade. Esta quarta etapa produz um sistema que constrói funcionalidades cada vez melhor.

Quando Usar

• Quando o PR de uma funcionalidade está pronto e ela ensinou uma lição durável — capture no PR antes do merge (caminho feliz)
• Após o lançamento, quando uma lição só ficou clara durante ou após o merge (fallback pós-merge)
• Após corrigir um bug complexo onde a causa raiz não era óbvia
• Após um ciclo de QA revelar problemas que poderiam ter sido detectados antes
• Após tomar uma decisão arquitetural com trade-offs significativos
• Quando você descobriu um padrão que deve ser reutilizado

Quando NÃO Usar

• Para correções triviais (correções de digitação, alterações simples de configuração)
• Quando a solução já está bem documentada na documentação oficial da biblioteca
• Quando a lição é específica do projeto, mas você está prestes a descontinuar aquele código
• Quando o trabalho foi uma execução limpa de um plano pré-definido — sem surpresas, sem retrabalho, sem decisões não óbvias. O corpo da issue e a descrição do PR já carregam esse registro; uma entrada em docs/solutions/ sem lição reutilizável treina leitores futuros a apenas passar os olhos
• Quando estiver em dúvida — pular não custa nada, pois a issue e o PR persistem no GitHub. Capturar uma lição de baixo valor custa a atenção dos planejadores futuros toda vez que consultarem docs/solutions/

Fluxo de Execução

Fase 1: Identificar o que Capturar

No caminho padrão (no PR), o trabalho em revisão é o branch do PR aberto, então os comandos abaixo o leem diretamente — um git log e um git diff do branch contra a base na qual ele será mesclado, enquanto ainda não foi mesclado. No caminho de fallback pós-merge, execute-os em uma sessão que ainda possa ver o histórico da funcionalidade mesclada — uma vez que /closeout tenha podado o branch e puxado a base, esse diff fica vazio e você deve ler o diff do PR via gh pr diff <n>. De qualquer forma, revise o trabalho recente.

Resolva a base primeiro. Não codifique main — este repositório usa prod, e um nome não é uma ref: em um fluxo de trabalho com worktrees, ninguém faz checkout do branch base, então o branch local está congelado no momento do checkout enquanto origin/<base> avança. Consulte sidecar.sh base-ref; não derive a base.

SC="<diretório deste skill>/references/sidecar.sh"
BASE_REF="$(bash "$SC" base-ref)" || { echo "base-ref falhou: não vou adivinhar uma base" >&2; exit 1; }
git log --oneline "$BASE_REF..HEAD"
git diff --stat "$BASE_REF...HEAD"

Analise:

1. Git log — Quais commits foram feitos? O que mudou? Relativo à base, não -20: uma contagem fixa lê o histórico da própria base como "o trabalho em revisão" em qualquer branch mais curto que ela. Dois pontos aqui está correto — estes são os commits neste branch que não estão na base. (O git diff é de três pontos pelo motivo oposto: ele diff a partir da base de merge em vez de subtrair o trabalho do lado da base.) No caminho de fallback pós-merge, o branch desapareceu, então use gh pr diff <n> como acima.

2. Thread da issue — Qual era o problema original? O que foi discutido?

3. O diff — Quais arquivos mudaram? Que padrões emergiram?

Pergunte ao usuário: "Qual foi a coisa mais importante que você aprendeu ou a parte mais complicada desta funcionalidade?" A resposta geralmente revela a lição de maior valor a ser capturada.

Antes de escrever, classifique a lição no nível correto:

• Evento — um incidente único ou falha visível
• Padrão — algo que aconteceu repetidamente entre funcionalidades, bugs ou entregas
• Estrutura — uma condição recorrente na base de código, fluxo de trabalho, incentivos ou processo de decisão que continua produzindo o padrão

Prefira capturar o nível mais alto que você puder sustentar com evidências. Se a lição for estrutural, nomeie o loop de feedback, feedback ausente ou efeito atrasado que tornou o resultado provável.

Antes de prosseguir, responda a quatro perguntas:

1. Isso é genuinamente novo? Verifique a documentação oficial da biblioteca e os repositórios que a busca por sobreposição da Fase 4 cobre. Se a lição já estiver bem documentada em outro lugar, pule-a ou link para a fonte existente.
2. Isso ainda será preciso daqui a 3 meses? Se a lição estiver fortemente acoplada a uma versão de dependência ou a uma solução temporária, observe isso — isso afeta a classificação de volatilidade abaixo.
3. Isso poderia ser capturado mais perto da fonte? Um invariante comportamental é melhor como um teste. Uma convenção é melhor como uma regra de linter. Uma explicação do "porquê" é melhor como um comentário de código colocalizado com a decisão — limitado ao porquê atual, a razão que um leitor precisa para entender o código como ele está agora. O incidente que o descobriu pertence à mensagem de commit e ao corpo do PR, onde um leitor reconstruindo o histórico já procura; a Etapa 3 de /execute declara esse roteamento no momento em que o comentário é escrito, e esta pergunta é a verificação retrospectiva dele. Se a lição pode ser capturada em um artefato de maior fidelidade, faça isso em vez de escrever prosa. Trata-se de carregar a lição — a verificação de agrupamento da Fase 4 faz uma pergunta diferente, se um mecanismo deve pegar a próxima instância, e uma recorrência pode exigir um mesmo que a lição em si precisasse de prosa.
4. O processo foi corrigido? (Apenas para compostos de correção de bugs.) A correção foi uma correção (removeu o defeito) ou uma solução alternativa (suprimiu a falha)? Padrões estruturalmente semelhantes em outros lugares da base de código foram encontrados e tratados? Que mudança de processo impediria que esta classe de defeito entrasse na base de código novamente — um teste mais forte, uma regra de linter, uma asserção, um item de checklist de planejamento ou uma issue aberta em chrislacey89/skills (veja Abertura contra o pack abaixo)? Se a resposta for "nada", o mecanismo que produziu este defeito ainda está ativo.

Abertura contra o pack — o quinto mecanismo

Esta subseção não é restrita a correções de bugs. A Q4 acima é (seu título diz isso), mas tanto Q4 quanto a regra de promoção a mecanismo da Fase 4 citam as regras abaixo, e a Fase 4 não é restrita a correção de bugs. O incidente para o qual este mecanismo existe foi um composto de funcionalidade. Um procedimento acessível apenas a partir do caminho que seu próprio incidente não seguiu é o defeito sendo corrigido, um nível abaixo — então as regras são declaradas aqui, uma vez, e ambas as fases apontam para elas.

O quinto nome é definido pela propriedade, não pela dificuldade. Os quatro primeiros são artefatos desta base de código; o quinto existe porque algumas mudanças preventivas não são — são mudanças na prosa de um skill, no portão, na passagem de bastão, ou no teste de contrato em chrislacey89/skills, que nenhum artefato downstream pode carregar. Isso, e apenas isso, é quando o quinto nome se qualifica. Ele não se qualifica porque os quatro primeiros são difíceis, caros ou pouco claros aqui: essa é a saída de conformidade que chrislacey89/skills#257 deixou deliberadamente fechada, e "não consegui construir um" ainda resolve da maneira que sempre resolveu — nomeando na entrada qual dos quatro chegou mais perto e o que o bloqueou.

Portão de proprietário de abertura (FAÇA-CONFIRMAR — verifique antes de escrever qualquer saída)

Abrir move palavras do repositório em que você está para um repositório público. Isso é um ato diferente de todos os outros mecanismos na lista — um teste, uma regra de linter, uma asserção e um item de checklist ficam onde estão. Portanto, antes de compor um corpo, confirme se o proprietário do repositório atual é um que você tem permissão para abrir a partir dele:

git remote get-url origin | sed -E 's#(git@[^:]+:|https://[^/]+/)([^/]+)/.*#\2#'

Compare-o com a lista de permissões abaixo. A lista de permissões é o portão inteiro — um proprietário que não está nela não é permitido, incluindo um proprietário que você não reconhece. Não inverta isso em "bloquear os proprietários que sei que são trabalho": uma organização cliente que foi integrada na semana passada não está na lista de ninguém ainda, então uma lista de negação admite exatamente o repositório com a postura de confidencialidade menos conhecida. Falhe fechado em desconhecido.

chrislacey89

Os marcadores ao redor dessa cerca são estruturais: esta subseção contém vários blocos cercados, então "a lista é o bloco de código abaixo" é ambíguo para qualquer coisa lendo mecanicamente — um leitor que adivinha errado extrai prosa e todo proprietário então falha na verificação. Corresponda aos marcadores, não à posição.

Adicione um proprietário a essa lista apenas como uma edição deliberada e revisada — uma linha, offline, pesquisável. Um repositório público para o qual você contribui se qualifica quando você o nomeia; ele não se qualifica meramente por ser público. Visibilidade é uma propriedade remota mutável, um fork público pode estar na frente de um pai privado e — a razão pela qual isso importa aqui — o que é aberto é uma narrativa sobre o trabalho, não o código do repositório. Código fonte público e um compromisso confidencial em torno dele é uma combinação comum, e "nós esbarramos nisso enquanto construíamos X para Y" vaza o relacionamento mesmo quando cada linha é legível mundialmente.

Quando o proprietário não está na lista de permissões, o quinto nome está indisponível. Recorra ao comportamento que precedeu este mecanismo: registre a prescrição no slot Prevenção → Nível de Processo da entrada, recomende /improve-pipeline, e deixe um humano carregá-la adiante. A lição não está perdida; ela simplesmente não viaja automaticamente.

Composição e abertura

Quando tanto a proteção de propriedade quanto o portão de proprietário de abertura passarem, abrir é o mecanismo, e /compound abre — a prescrição que chega a este repositório é o artefato, não uma frase recomendando que alguém a leve para lá. Primeiro verifique sobreposição e comente na issue existente em vez de abrir uma nova; um novo canal de saída para um backlog só vale a pena se não encher com repetições.

gh issue list -R chrislacey89/skills --state all --search "<área do pipeline> <palavras-chave do modo de falha>"
gh issue create -R chrislacey89/skills --title "[improve-pipeline] <área do pipeline> — <prescrição>" --body-file <arquivo>

--title e --body* são obrigatórios, não estilísticos: gh issue create sem nenhum deles falha em qualquer executor não interativo, que é todo caminho AFK que este mecanismo deve suportar.

Escreva o corpo anonimizado e trate isso como parte do contrato, não como boas maneiras. O portão acima decide se você pode abrir; este decide o que cruza. Descreva a forma do incidente, não seu assunto:

• Nomeie o arquivo do pack que a mudança visa, a etapa do pipeline que o perdeu e o que ela deveria ter feito.
• Não nomeie o repositório downstream, seu proprietário, seu cliente, seus caminhos, seus identificadores ou seus números de issue e PR. Caracterize-o — "um repositório TypeScript web/page-analysis downstream" — da maneira que chrislacey89/skills#266 fez, que é o exemplo trabalhado: ele abre Repositório acionador: anonimizado e registra que a fonte foi deliberadamente despojada de identificadores.
• Não cite o caminho desta entrada como evidência. Um caminho docs/solutions/… é um nome de arquivo de um repositório ao qual o leitor pode não ter acesso, então não prova nada para ele e identifica o trabalho para todos os outros. Carregue o raciocínio; a entrada fica em casa.

O arquivo do pack e a forma da falha são o que tornam uma proposta acionável aqui. Tudo o que a regra de anonimização remove é detalhe que só era legível no repositório de onde veio.

Mantenha curto. Isso é um esboço de proposta, não uma proposta elaborada — /improve-pipeline é o que desenvolve uma, e a recomendação de /improve-pipeline mais adiante nesta fase ainda se aplica: recomende-o, não o invoque. Cite o número da issue na entrada. Uma abertura não citada é prosa novamente: a entrada nomeia #N, ou o quinto nome não foi usado.

Revisão de Rabbit Hole.…