lesson-learned

Visão geral da skill lesson-learned

A skill lesson-learned transforma atividade recente de Git em aprendizados concretos de engenharia de software. Em vez de trazer conselhos abstratos, ela inspeciona diffs reais, histórico de commits e arquivos alterados, e então relaciona o que aconteceu a princípios nomeados como SRP, DRY, KISS, YAGNI e anti-patterns correlatos. Isso faz da lesson-learned uma opção especialmente útil para desenvolvedores que já mexeram no código e querem responder a perguntas como: o que esse trabalho nos ensinou, que trade-off fizemos e o que vale repetir ou evitar na próxima vez?

Para quem a skill lesson-learned é indicada

Os perfis com melhor encaixe são:

• desenvolvedores concluindo uma feature, refatoração, correção de bug ou limpeza de código
• reviewers que querem um resumo orientado a aprendizado depois de uma PR
• líderes técnicos criando hábitos leves de reflexão em engenharia
• agentes que precisam explicar o princípio por trás de mudanças recentes no código

Se você quer uma reflexão de design ancorada no histórico real do repositório, a lesson-learned skill entrega mais do que um prompt genérico do tipo “revise este código”.

Qual problema essa skill realmente resolve

O papel central não é fazer code review no sentido tradicional de aprovado/reprovado. A lesson-learned olha para trás, para um trabalho concluído ou em andamento, e extrai de 1 a 3 lições sustentadas pelo diff. Boas saídas normalmente incluem:

• o nome do princípio
• como a mudança o demonstra
• por que isso importa
• uma recomendação de próximo passo

Esse enquadramento torna a skill especialmente útil para retrospectivas, mentoria e notas de aprendizado em PRs.

O que diferencia a lesson-learned de um prompt genérico

Dois pontos pesam mais:

1. Ela é guiada pelo histórico de Git, então analisa mudanças reais em vez de trechos hipotéticos.
2. Ela exige um catálogo de princípios, em especial references/se-principles.md, que dá ao modelo um vocabulário consistente para nomear padrões.

Essa combinação ajuda a skill a produzir lições que parecem conquistadas pelo código, e não copiadas de um livro-texto de engenharia de software.

Quando não escolher lesson-learned

Evite lesson-learned se o seu objetivo real for:

• encontrar bugs linha a linha antes do merge
• fazer auditoria de segurança
• receber feedback apenas de estilo ou lint
• planejar arquitetura sem ainda haver mudanças de código
• revisar uma base grande sem escopo claro

Nesses casos, uma skill de code review, segurança ou design costuma ser uma ferramenta inicial melhor.

Como usar a skill lesson-learned

Contexto de instalação da lesson-learned

O repositório não publica um comando de instalação dedicado dentro de skills/lesson-learned/SKILL.md, então a instalação depende de como você carrega skills a partir de softaworks/agent-toolkit. Se o seu ambiente suportar adicionar uma skill desse repositório, o padrão mais comum é:

npx skills add softaworks/agent-toolkit --skill lesson-learned

Se o seu agente carregar skills diretamente do repo, use o caminho da skill:

skills/lesson-learned

De qualquer forma, trate o SKILL.md como a especificação de comportamento em runtime, não apenas como um README.

Leia estes arquivos antes do primeiro uso

Para começar rápido e com pouca adivinhação, leia os arquivos nesta ordem:

1. skills/lesson-learned/SKILL.md
2. skills/lesson-learned/references/se-principles.md
3. skills/lesson-learned/references/anti-patterns.md
4. skills/lesson-learned/README.md

O detalhe de adoção mais importante passa fácil despercebido: a skill afirma explicitamente que não se deve prosseguir antes de carregar se-principles.md.

Que entrada a skill lesson-learned precisa

O lesson-learned usage funciona melhor quando o modelo tem acesso a:

• um repositório com histórico de Git
• o nome da branch atual ou um alvo de comparação nomeado como main
• um intervalo de commits, SHA de commit, diff entre branches ou diff da working tree
• contexto suficiente dos arquivos para inspecionar os que mais mudaram

Sem contexto de Git, a saída vira algo genérico muito rapidamente.

Escolha primeiro o escopo certo de análise

Essa skill só é tão boa quanto o escopo que você fornece. O repositório define padrões práticos:

• feature branch: comparar o trabalho da branch com main
• main branch: analisar os últimos 5 commits
• commit específico: inspecionar um único SHA
• mudanças em andamento: inspecionar diffs staged e unstaged

Um bom lesson-learned guide começa forçando essa escolha logo no início. Se o escopo estiver nebuloso, o resultado geralmente mistura lições sem relação entre si.

Comandos Git úteis para melhorar o uso de lesson-learned

O próprio fluxo da skill gira em torno de visualizações comuns de Git, como:

• git log main..HEAD --oneline
• git diff main...HEAD
• git log --oneline -5
• git diff HEAD~5..HEAD
• git show <sha>
• git diff
• git diff --cached

Você não precisa usar todos os comandos sempre. Escolha o que melhor combina com a história que quer que a skill explique.

Como transformar um pedido vago em um prompt forte

Prompt fraco:

“Reflect on my recent work.”

Prompt melhor:

“Use lesson-learned on my feature branch versus main. Read references/se-principles.md first. Focus on the 3 files with the largest behavioral changes. Give me 2 lessons grounded in the diff, each with the principle name, code evidence, trade-off, and one thing I should repeat in future PRs.”

Por que isso funciona:

• define o escopo
• cita o arquivo de referência do qual a skill depende
• limita a área de análise
• especifica o formato de saída

Padrão de prompt da lesson-learned para Code Review

A lesson-learned for Code Review funciona melhor como uma camada de reflexão depois do review normal, não como substituto. Um prompt prático é:

“Run lesson-learned on this PR branch against main. Summarize the engineering lesson behind the changes, not just defects. Highlight 1 positive principle demonstrated, 1 anti-pattern risk if relevant, and cite the changed files that support each point.”

Isso é útil quando você quer um comentário de review que ensine, e não apenas bloqueie.

Formato de saída sugerido para pedir

Peça uma estrutura compacta como:

• Lesson
• Principle
• Evidence from changes
• Why it matters
• Next step

Isso se alinha à intenção do repositório e reduz texto genérico de enchimento.

Como lidar com diffs grandes

Em PRs grandes, não peça para a skill “analisar tudo”. Em vez disso:

• identifique os arquivos com mais mudanças
• agrupe as alterações por tema
• ignore edições mecânicas óbvias
• peça apenas de 1 a 3 lições

A skill funciona melhor extraindo padrões do que catalogando exaustivamente cada mudança em cada arquivo.

Workflow comum que economiza tempo

Um fluxo confiável é:

1. carregar se-principles.md
2. escolher o escopo
3. inspecionar o log e o diff do Git
4. ler os arquivos mais alterados
5. opcionalmente carregar anti-patterns.md
6. gerar de 1 a 3 lições com evidências
7. refinar se o resultado estiver amplo demais ou moralista demais

Essa sequência importa porque o catálogo de princípios dá à análise um vocabulário mais forte.

FAQ da skill lesson-learned

A lesson-learned é boa para iniciantes?

Sim, desde que o iniciante tenha mudanças reais para analisar. A skill explica princípios a partir do trabalho que a pessoa acabou de fazer, o que muitas vezes é mais fácil de absorver do que começar pela teoria. Ela é menos útil para alguém sem acesso ao repositório ou sem diffs recentes.

lesson-learned é a mesma coisa que code review?

Não. A lesson-learned é retrospectiva e orientada a princípios. Code review costuma ser orientado a correção, risco e manutenibilidade. Há sobreposição, mas o objetivo da saída é diferente.

A skill lesson-learned precisa de acesso ao Git?

Para resultados fortes, sim. O repositório foi pensado em torno de histórico e diffs de Git. Se você só colar um trecho de código, o modelo ainda pode comentar sobre princípios, mas já não estará usando a skill no seu modo mais forte.

O que torna a lesson-learned melhor do que um prompt comum?

A vantagem está na estrutura: seleção explícita de escopo, referências obrigatórias de princípios e um workflow que conecta as lições a sinais concretos do código. Prompts comuns muitas vezes pulam direto para “boas práticas” genéricas.

Posso usar lesson-learned em mudanças ainda não commitadas?

Sim. A skill dá suporte a mudanças em andamento com git diff e git diff --cached. Isso é útil antes do commit, quando você quer entender a lição ou o trade-off embutido no que está prestes a entregar.

Quando a lesson-learned não é uma boa escolha?

Evite quando:

• não há mudanças recentes relevantes
• o diff é majoritariamente gerado ou ruído de formatação
• você precisa mais de triagem de defeitos do que de reflexão
• a branch mistura muitas tarefas sem relação

Nesses casos, reduza o escopo ou use outra skill primeiro.

Como melhorar a skill lesson-learned

Dê à lesson-learned uma história mais estreita

A maior alavanca de qualidade é o escopo. “Meu último mês de trabalho” é amplo demais. “Esta refatoração que separou chamadas de API da renderização da UI” é melhor. Escopo estreito gera lições com princípios mais nítidos e evidências mais fortes.

Carregue a referência de princípios sempre

O repositório é incomumente explícito nesse ponto: references/se-principles.md deve ser carregado antes da análise. Se você pular isso, o modelo ainda pode produzir observações, mas terá menos chance de rotular padrões com consistência ou conectá-los a princípios reconhecidos.

Use anti-patterns para equilibrar, não para negativar

references/anti-patterns.md ajuda mais quando o diff traz sinais de risco como edições espalhadas, abstração em excesso ou módulos “god” crescendo demais. Peça uma formulação cuidadosa para que o resultado continue útil, em vez de soar punitivo.

Peça evidências ligadas aos arquivos alterados

Um modo de falha comum é produzir conselhos de alto nível sem prova. Melhore a saída de lesson-learned pedindo:

• quais arquivos alterados estão envolvidos
• que mudança estrutural ocorreu
• que trade-off isso implica
• por que isso corresponde a um princípio específico

A evidência é o que separa uma lição real de um comentário genérico.

Limite o número de lições

Mais lições normalmente significam lições mais fracas. Peça apenas de 1 a 3 aprendizados. Isso força priorização e torna a saída mais crível e mais fácil de usar em notas de PR, retros ou coaching.

Diga à skill que tipo de lição você quer

Você pode direcionar a análise adicionando uma lente:

• lição de manutenibilidade
• lição de refatoração
• lição de correção de bug
• lição sobre trade-off de design
• lição de processo de time ligada a mudanças no código

Isso aumenta a relevância sem brigar com o workflow previsto da skill.

Corrija rascunhos genéricos com uma segunda passada

Se o primeiro resultado vier vago, não rode tudo de novo do zero imediatamente. Em vez disso, peça:

• “Tie each lesson to a specific file or diff hunk.”
• “Replace general advice with what this branch actually demonstrates.”
• “Name the principle only if the code evidence clearly supports it.”
• “Drop any lesson that is not visible in the diff.”

Isso normalmente melhora a saída mais rápido do que reescrever o prompt de forma ampla.

Fique atento a estes modos de falha da lesson-learned

Saídas fracas típicas incluem:

• princípios nomeados sem evidência no código
• lições demais extraídas de um único diff
• confundir defeitos de code review com aprendizados
• linguagem moralista em vez de trade-offs práticos
• tentar resumir mudanças não relacionadas como se fossem uma única lição

Perceber isso cedo torna a iteração bem mais simples.

Melhor caminho de melhoria para uso recorrente em equipe

Se um time pretende usar lesson-learned com frequência, padronize um template de prompt com:

• regra de escopo
• alvo de comparação
• número máximo de lições
• formato obrigatório de evidência
• checagem opcional de anti-pattern

Isso reduz inconsistência e torna a lesson-learned skill muito mais confiável em PRs e retrospectivas.