Learned Lesson Skill

Metadata

• Total de Steps: 4
• Tempo Estimado: 10-15 minutos
• Prerequisito: Conclusao de tarefa complexa, bug fix ou decisao arquitetural
• Artefato Final:

  .aidev/memory/kb/YYYY-MM-DD-<topic>.md

Quando Usar

Ativa apos a conclusao de uma tarefa complexa, correcao de bug, implementacao de um padrao de sucesso ou decisao arquitetural importante. O objetivo e economizar tokens e tempo em sessoes futuras ao reutilizar solucoes de excelencia ou evitar erros repetidos.

Proposito

Capturar conhecimento tacito (como resolvemos algo ou por que algo funcionou tao bem) e transforma-lo em conhecimento explicito reutilizavel.

Step 1: Capturar Contexto

Checkpoint:

context_captured

Acoes

Documentar o contexto do aprendizado:

1. Qual erro, excecao, desafio ou padrao de excelencia foi identificado?
2. Qual era o comportamento esperado vs observado (para bugs) ou qual a vantagem competitiva (para padroes)?
3. Qual a stack/tecnologia envolvida?
4. Qual a frequencia/impacto ou potencial de reuso?

Formato de Captura

## Contexto

**Stack**: [Ex: Laravel 10 + PHP 8.2]
**Ambiente**: [Ex: Producao, Docker]
**Frequencia**: [Ex: Intermitente, sempre]
**Impacto**: [Ex: Critico, Alto, Medio, Baixo]

### Sintoma Observado
[Descricao do comportamento errado]

### Comportamento Esperado
[Descricao do comportamento correto]

### Evidencia
[Stack trace, log, screenshot]

Criterios de Validacao

• Contexto claramente descrito
• Stack/tecnologia identificada
• Sintoma documentado com evidencia
• Impacto avaliado

Step 2: Identificar Causa Raiz

Checkpoint:

root_cause_identified

Acoes

Aplicar tecnica dos 5 Porques:

1. Por que o erro ocorreu?
2. Por que essa condicao existia?
3. Por que nao foi detectado antes?
4. Por que o sistema permitiu?
5. Por que nao havia protecao?

Formato

## Causa Raiz

### Analise (5 Whys)
1. **Por que falhou?** [Resposta]
2. **Por que?** [Resposta]
3. **Por que?** [Resposta]
4. **Por que?** [Resposta]
5. **Por que?** [Causa raiz]

### Causa Raiz Identificada
[Explicacao tecnica clara e concisa]

### Tipo de Problema / Padrao
- [ ] Bug de codigo
- [ ] Configuracao incorreta
- [ ] Padrao de Codificacao (Sucesso)
- [ ] Decisao Arquitetural
- [ ] Otimizacao de Performance
- [ ] Falta de validacao
- [ ] Outro: ___

Criterios de Validacao

• 5 Whys aplicados
• Causa raiz tecnica identificada
• Tipo de problema classificado
• Nao confunde sintoma com causa

Step 3: Documentar Solucao

Checkpoint:

solution_documented

Acoes

Documentar a correcao de forma reproduzivel:

1. O que foi mudado (diff/codigo)
2. Por que essa solucao funciona
3. Alternativas consideradas
4. Testes que validam a correcao

Formato

## Solucao

### Correcao Aplicada
```[linguagem]
// Codigo que resolveu o problema

Por Que Funciona

[Explicacao tecnica de por que essa solucao resolve a causa raiz]

Alternativas Consideradas

Validacao

• Teste adicionado:

  path/to/test.spec.ts

• Comando de verificacao:

  npm test -- --grep "..."

### Criterios de Validacao
- [ ] Codigo/mudanca documentado
- [ ] Explicacao do porque funciona
- [ ] Teste de regressao adicionado
- [ ] Comando de verificacao funciona

---

## Step 4: Armazenar Licao
**Checkpoint**: `lesson_stored`

### Acoes

#### Memoria Local (Projeto)
Salvar em `.aidev/memory/kb/`:

```bash
# Nome do arquivo
YYYY-MM-DD-<slug-do-problema>.md

Memoria Global (Cross-Project)

Se aplicavel a outros projetos:

# Usar basic-memory MCP
mcp__basic-memory__write_note

Template Final da Licao

# Licao: [Titulo Curto e Descritivo]

**Data**: YYYY-MM-DD
**Stack**: [Tecnologias envolvidas]
**Tags**: [bug, success-pattern, arch-decision, performance, security, etc]

## Contexto
[Resumo do contexto - do Step 1]

## Problema
[Sintoma e evidencia - do Step 1]

## Causa Raiz
[Explicacao tecnica - do Step 2]

## Solucao
[Codigo/mudanca - do Step 3]

## Prevencao
Como evitar no futuro:
- [ ] Checklist item 1
- [ ] Checklist item 2

## Referencias
- [Link para PR/commit]
- [Link para documentacao]

Criterios de Validacao

• Arquivo salvo no path correto
• Todas as secoes preenchidas
• Tags apropriadas adicionadas
• Memoria global atualizada (se aplicavel)

Categorias de Licoes

bug

success-pattern

arch-decision

config

performance

security

integration

deployment

Transicoes

Ao Completar com Sucesso

skill_add_artifact "learned-lesson" ".aidev/memory/kb/YYYY-MM-DD-<topic>.md" "lesson"
skill_complete "learned-lesson"
# Licao disponivel para consulta futura

Em Caso de Falha

skill_fail "learned-lesson" "Motivo da falha"
# Salvar estado parcial para retomar depois

Exemplo de Uso com Orquestrador

skill_init "learned-lesson"
skill_set_steps "learned-lesson" 4

# Step 1: Capturar contexto
skill_advance "learned-lesson" "Capturar contexto"
# ... documentar contexto, sintoma, evidencia ...
skill_validate_checkpoint "learned-lesson"

# Step 2: Identificar causa raiz
skill_advance "learned-lesson" "Identificar causa raiz"
# ... aplicar 5 whys, classificar problema ...
skill_validate_checkpoint "learned-lesson"

# Step 3: Documentar solucao
skill_advance "learned-lesson" "Documentar solucao"
# ... registrar correcao, validar com teste ...
skill_validate_checkpoint "learned-lesson"

# Step 4: Armazenar licao
skill_advance "learned-lesson" "Armazenar licao"
# ... salvar arquivo, atualizar memoria ...
skill_add_artifact "learned-lesson" ".aidev/memory/kb/2024-01-15-timeout-api.md" "lesson"
skill_validate_checkpoint "learned-lesson"

skill_complete "learned-lesson"

Recuperacao de Licoes

Para consultar licoes em sessoes futuras:

# Listar e buscar (CLI Otimizado)
aidev lessons
aidev lessons --search "termo"
aidev lessons --read "nome-arquivo"

# Busca global (basic-memory)
mcp__basic-memory__search_notes query="palavra-chave"

Principios

1. Capture Imediatamente - Conhecimento tacito se perde rapido
2. Seja Especifico - Detalhes tecnicos importam
3. Inclua Codigo - Exemplos concretos sao mais uteis
4. Adicione Teste - Previna regressoes
5. Categorize Bem - Facilita busca futura