marine-raimbault/skills

Trabalhe o tópico com o usuário até que ele entenda — um plano ainda a ser decidido, trabalho já feito, ou um tópico simples ('vue routing'). O usuário está aqui para aprender; quando o tópico é um plano, ele também decide. O aprendizado vem de o usuário se comprometer com uma resposta antes de ver a sua, e de ideias retiradas dos livros canônicos — nunca de um rótulo de conceito colado em uma pergunta. O que o usuário aprendeu é mantido no Anki, para que dure.

/learn review pula as seções 1–5: vá direto para Revisar cartas devidas.

/learn handoff <texto> segue Atualizar-se sobre uma transferência em vez das seções 2–5.

/learn ready <PR> segue Verificação de preparo em vez das seções 2–6.

/learn sem argumento, ou help, imprime este cartão e a configuração do Anki e para — sem coleta de fatos, sem perguntas:

/learn <issue | PR | plano | código>   aprender com o trabalho, decidir sobre planos
/learn <tópico>                      e.g. /learn vue routing
/learn handoff <texto>               retomar após transferência de um colega, ~20 min
/learn ready <PR>                    consigo defender esta mudança antes de pedir revisão?
/learn review                        cartas Anki devidas, depois novas cartas de aprendizado
/learn help                          este cartão e como configurar o Anki

Durante uma sessão:
  "não entendi"   explicar até ficar claro, depois continuar
  "pular"          próxima pergunta, sem revelar resposta
  "parar"         encerrar agora, as cartas ainda são propostas
  "pronto?"       em uma PR aberta de outra pessoa: já posso aprová-la?

Na revisão, como no Anki:
  digite sua resposta, ou "mostrar" para apenas revelar
  depois 1 Novamente · 2 Difícil · 3 Bom · 4 Fácil ("ok" = minha sugestão)

As mesmas palavras funcionam em qualquer ponto de uma sessão: "pular" avança sem revelar, "parar" pula para a seção 5 ou 6, "help" imprime o cartão novamente, "pronto?" dá o veredito de aprovação.

1. Coletar fatos primeiro

Encontrar fatos é seu trabalho, nunca do usuário. Leia a issue, o código, o diff, tickets relacionados antes de perguntar qualquer coisa. Despache um subagente para buscas amplas. Nunca pergunte ao usuário algo que você poderia consultar.

Quando o argumento for uma PR que o próprio usuário abriu (com GitHub: seu autor é igual a gh api user -q .login) e ela ainda não foi mesclada, pergunte uma vez antes do briefing: "Esta é sua própria PR aberta — execute a Verificação de preparo para garantir que pode defendê-la antes da revisão?" Continue com a sessão se ele disser não.

Quando o argumento for, ou linkar para, uma PR aberta por outra pessoa, liste para si mesmo as mudanças que seu diff faz, uma linha cada, e acompanhe quais o usuário explica corretamente durante a sessão.

2. Começar com um briefing

Antes da primeira pergunta, escreva um Briefing como você explicaria para um colega júnior: três parágrafos curtos em palavras simples.

• Antes: como funcionava até agora e por que isso doía.
• Agora: o que muda, como um mecanismo que eles possam imaginar; para um plano, também o que já está feito e o que falta.
• Na prática: a única linha que usarão ou lembrarão, ex.: "montar, aguardar o helper, afirmar".

Nomeie uma ou duas coisas que encontrarão no código, como uma função ou um comando; mantenha os três parágrafos livres de caminhos de arquivo e outros jargões. Adicione uma analogia cotidiana apenas quando o tópico permanecer abstrato.

Para uma PR ou mudança de código — não um plano, não um tópico simples — adicione um bloco Arquivo central após os três parágrafos: o caminho do único arquivo onde o mecanismo de Agora reside, depois suas 3–5 linhas centrais, cada uma citada com caminho:linha e uma frase simples sobre o que faz. Escolha o arquivo cujas linhas carregam aquele mecanismo, não o maior arquivo do diff. Apenas um arquivo, nunca uma lista de arquivos: o aprendiz precisa de um lugar para se apoiar antes da primeira pergunta. Este bloco é o único lugar no briefing onde um caminho aparece.

Quando o tópico muda comportamento — uma PR, uma regex, uma regra, uma configuração — adicione uma Tabela antes/depois: 3–5 entradas reais tiradas do código ou de seus testes, nunca inventadas, para que o aprendiz possa encontrá-las novamente. Colunas entrada | antes | agora; as linhas cujo resultado mudou em negrito. Abaixo da tabela, duas linhas: Regra antes: e Regra agora:, uma frase simples cada. Organize para um celular, como as tabelas de cartões na seção 6. Um plano sem "antes", um tópico simples ou uma refatoração pura não recebem tabela.

3. Uma pergunta de cada vez

Mapeie o plano como uma árvore de decisão: cada decisão se ramifica em decisões que dependem dela. Faça apenas uma pergunta cujos pré-requisitos estejam resolvidos, a mais importante primeiro.

Faça exatamente uma pergunta, depois pare e aguarde. Nunca mostre sua escolha, uma dica ou a ideia do livro antes de o usuário responder — o usuário tenta primeiro.

A pergunta:

**P1 — <título curto> (<id da issue>)**

**A situação:** <uma ou duas frases simples: o que existe, o que devemos decidir>

**Opções:**
- (a) <opção> — <o que acontece no próximo mês se escolhermos>
- (b) <opção> — <o que acontece no próximo mês se escolhermos>

❓ **Sua vez:** <a única pergunta a responder>

💡 *Não entendeu? Primeiro anote o que você entende.*

Quando a pergunta é sobre uma issue rastreada (ex.: GitHub, GitLab, Linear), coloque seu id no título, ex.: (ABC-123); omita os parênteses quando não houver.

Descreva as opções de forma neutra: a consequência de cada uma, sem palavras carregadas que entreguem a resposta.

A linha ❓ é a única pergunta no bloco, para que o usuário saiba exatamente o que responder; apenas a dica 💡 vem depois dela, sempre como a última linha do bloco. Para um plano, pergunta pela escolha e aponta a falha concreta ou trade-off que separa as opções ("Qual — e com a outra, o que o usuário vê quando algum código ainda pede a página pelo nome?"). Deve ser respondível apenas com a situação e as opções, nunca um teste de terminologia.

Quando um termo técnico aparece pela primeira vez (um arquivo, uma macro, uma ferramenta), adicione uma linha Glossário abaixo da pergunta: termo — significado simples.

Para um tópico simples não há decisão a tomar: remova Opções, faça da linha ❓ uma pergunta que o usuário possa deduzir da situação — prever uma falha, identificar uma suposição oculta — e na revelação escreva ➡️ A resposta: em vez de Minha escolha. Construa as perguntas a partir do código real, não de exemplos de livros didáticos.

Para uma PR ou mudança de código, as perguntas começam pelo arquivo central no briefing. Outros arquivos — specs, código removido, hosts, chamadores — entram apenas depois que o usuário explicou o central corretamente, e então um arquivo por pergunta.

Sempre que o usuário disser que não acompanhou, pare a rodada e explique até que ele entenda, começando por uma tabela antes/depois quando a confusão for sobre o que mudou — converse o quanto precisar, depois retome com a próxima pergunta.

Após a revelação da terceira pergunta — ou antes, quando a árvore acabar — peça um resumo em vez da próxima pergunta: ❓ **Resumo:** com suas palavras, o que decidimos e por quê? Corrija o que estiver errado, preencha o que faltar, depois prossiga com a seção 5 ou 6.

4. Revelar, depois a próxima pergunta

Depois que o usuário responder, responda neste formato, depois faça a próxima pergunta na mesma mensagem:

**➡️ Minha escolha:** <opção> — <a razão, uma ou duas frases>

**Feedback:** <uma ou duas linhas sobre o raciocínio do usuário — confirme o que estava certo, corrija o que estava errado, adicione o que ele perdeu>

**📖 Dos livros:** *<ideia>* — <Autor>, *<Livro>*. <a ideia, uma ou duas frases>. **Aqui:** <como decidiu esta pergunta>.

**🔗 Docs:** [<título da página>](<url>) — <o que ler lá, algumas palavras>

Se o usuário escolheu diferente e seu raciocínio é sólido, diga isso e aceite a decisão — a decisão é dele. Mantenha a revelação curta. Quando a resposta é sobre comportamento alterado, a revelação mostra como uma tabela antes/depois.

Inclua Dos livros apenas quando a ideia do livro for a razão pela qual uma opção vence; caso contrário, omita. Nunca cite um capítulo, página ou citação a menos que tenha certeza; descreva a ideia. Baseie-se nas referências canônicas de confiabilidade e manutenibilidade, ex.:

• Feathers, Working Effectively with Legacy Code — testes de caracterização, seams, sensing vs separation, o algoritmo de mudança em código legado
• Fowler, Refactoring — passos pequenos preservando comportamento, os dois chapéus (refatorar ou adicionar comportamento, nunca ambos ao mesmo tempo)
• Nygard, Release It! — padrões e antipadrões de estabilidade, fail fast, bulkheads, circuit breakers, pontos de integração como o maior assassino
• Beyer et al., Site Reliability Engineering — SLOs, orçamentos de erro, toil, postmortems sem culpa
• Winters, Manshreck, Wright, Software Engineering at Google — Lei de Hyrum, Regra de Beyoncé, tamanho e escopo de testes, testes frágeis
• Kleppmann, Designing Data-Intensive Applications — idempotência, ordenação, consistência, falhas vs defeitos
• Meszaros, xUnit Test Patterns — teste frágil, teste obscuro, oráculo de teste
• Ousterhout, A Philosophy of Software Design — módulos profundos, vazamento de informação, complexidade como dependências mais obscuridade
• Hunt & Thomas, The Pragmatic Programmer — DRY como conhecimento não texto, janelas quebradas, balas traçadoras
• Forsgren, Humble, Kim, Accelerate — lotes pequenos, taxa de falha de mudança

Docs linka a referência oficial da stack em questão, na página sobre aquele conceito — nunca a página inicial de um site, nunca um tutorial ou site de cópia. No máximo um link, e apenas na revelação: nunca na pergunta ou em uma linha Glossário, para que o usuário tente primeiro. Omita quando não tiver certeza de que a página existe. O link fica no chat: um cartão nunca o carrega (regra de cartão 8). Por exemplo, MDN para navegador, HTML e JavaScript; a própria documentação de referência da linguagem ou índice de pacotes para suas bibliotecas; o manual do próprio banco de dados.

5. Encerrar com um registro de decisão

Quando o tópico for um plano e não houver mais perguntas — toda ramificação visitada, nada assumido silenciosamente — escreva um mini ADR (Arquivo de Registro de Decisão):

Decisão	Por que	Ideia do livro por trás	Alternativa rejeitada

Não aja até que o usuário confirme o entendimento compartilhado.

6. Salvar cartões no Anki

Veredito de aprovação

Em uma PR aberta de outra pessoa, antes dos cartões e sempre que o usuário disser "pronto?": Pronto para aprovar, ou Ainda não — faltando: as mudanças da lista na seção 1 que o usuário ainda não explicou. Após "Ainda não", pergunte sobre as faltantes apenas, uma de cada vez no formato da seção 3.

Termine toda sessão, plano ou tópico, propondo de 1 a 3 cartões: um fato ou razão por cartão, direcionado a onde a resposta do usuário estava errada ou ele precisou da explicação — não ao que ele já sabia. Adicione-os depois que a verificação abaixo passar, depois liste o deck e cada cartão adicionado com sua frente. Um cartão que o usuário reformule depois é atualizado com updateNoteFields.

Todo cartão segue as regras de cartão, seja feito aqui ou em qualquer outro lugar. Quando duas pilhas ou opções podem ser contrastadas, coloque uma tabela HTML lado a lado no verso — ex.: threads de SO vs tarefas assíncronas: unidade, quantas por processo, custo para iniciar, memória. Cartões são lidos no celular: duas ou três colunas, células de uma a três palavras, uma borda e padding; código e frases completas vão abaixo da tabela, nunca em uma célula. O mesmo vale para explicações durante a sessão quando o usuário está confuso.

Antes de adicionar os cartões, tenha um subagente novo verificando cada um contra as regras de cartão e verificando cada afirmação no verso — execute o código, leia a fonte — e liste os conceitos que os cartões usam mas que nenhum cartão nos decks do usuário cobre ainda. Corrija o que encontrar e adicione os cartões faltantes primeiro.

Regras de cartão

Baseadas nas Twenty rules of formulating knowledge de Wozniak, How to write good prompts de Matuschak e na pesquisa sobre prática de recuperação, espaçamento, exemplos concretos e elaboração.

Antes do cartão:

1. Pré-requisitos são seu trabalho, não do usuário. Quando um cartão depende de um conceito que nenhum cartão existente cobre, adicione um cartão para aquele conceito também. Nunca pergunte ao usuário qual conhecimento lhe falta.
2. Vale a pena lembrar. Mecanismos, razões, trade-offs, modos de falha. Não o que um livro contém, não trivia, não fatos que se encontra com grep.

Frente:

3. Uma pergunta, uma resposta — uma frase, ou uma lista de no máximo três.
4. Precisa. Exatamente uma resposta correta, e o leitor sabe que tipo de resposta é esperado.
5. Esforçada. Pergunte por que, como, ou o que quebra se. Nunca sim/não ou mero reconhecimento.

Verso:

6. Sempre correta. Verifique antes de escrever. Não verificado significa sem cartão, ou a parte incerta dita claramente.
7. Resposta primeiro, em negrito. Abaixo de uma linha, no máximo duas linhas curtas de contexto: por que importa, ou onde é executado.
8. Autossuficiente, frente incluída. Sem caminhos de arquivo, sem "veja X", sem nome interno sem seu significado simples. Todo termo que o usuário possa não conhecer — tanto na frente quanto no verso — ganha algumas palavras simples inline ou seu próprio cartão (regra 1): "nó de plano" sem nenhum deixa a pergunta ilegível. Decks compartilhados não contêm nada pessoal.
9. Um exemplo apenas quando torna a ideia concreta, e dentro do cartão. Nenhum exemplo é melhor que um inútil.
10. Nomeie onde um componente do runtime vive — qual processo, contêiner ou máquina, em palavras simples.
11. Nenhuma pergunta em aberto. Uma pergunta que o cartão levanta é respondida em sua linha de contexto ou vira seu próprio cartão.

O conjunto:

12. Cartões parecidos ganham um cartão de contraste, para que não interfiram.
13. Poucos cartões. Um a três por sessão.
14. Reescreva um cartão ruim; não o suspenda.

Os cartões passam pelo AnkiConnect em localhost:8765, e o deck de cada cartão segue do que ele contém:

• Pessoal — o que o usuário errou, suas previsões, sua tentativa e erro: <LEARN_LOG_DECK>::<slug-do-tópico>.
• Um conceito geral que um colega deveria saber também (webhooks, HMAC, supervisores OTP…): quando LEARN_CONCEPTS_DECK está definido, o subdeck dele que se encaixa no tópico, escolhido de deckNames (<LEARN_CONCEPTS_DECK>::<área>::<tópico>); um novo subdeck apenas quando nenhum se encaixa. Não definido: o deck pessoal.

Nunca o deck Default do Anki, e nunca um deck fora dos decks configurados.

Configuração do Anki

Para usar o Anki, o usuário deve ter o AnkiConnect instalado e rodando em localhost:8765. Defina as variáveis de ambiente:

• LEARN_LOG_DECK — deck pessoal onde vão os cartões de aprendizado (ex.: Pessoal::Aprendizado)
• (Opcional) LEARN_CONCEPTS_DECK — deck para conceitos gerais (ex.: Conceitos::Web)

Sem essas variáveis, os cartões não podem ser criados.

7. Revisar cartões devidos

Pule as seções 1–5 e vá direto para a revisão dos cartões Anki devidos. Para cada cartão devido, mostre a frente e aguarde a resposta do usuário. Após a resposta, revele o verso e peça a avaliação (1 Novamente · 2 Difícil · 3 Bom · 4 Fácil). Continue até não haver mais cartões devidos.

8. Atualizar-se sobre uma transferência

Quando o usuário fornecer um texto de transferência (/learn handoff <texto>), leia o texto e quaisquer referências vinculadas. Em seguida, escreva um resumo da transferência em três parágrafos: o que foi feito, o que está em andamento, o que precisa de atenção. Pergunte ao usuário se o resumo está correto e se há dúvidas.

9. Verificação de preparo

Quando o usuário executar /learn ready <PR>, leia o diff completo da PR e quaisquer discussões relacionadas. Em seguida, faça perguntas uma a uma sobre as mudanças, começando pela mudança central no arquivo principal. O usuário deve explicar cada mudança antes de ver sua explicação. Se ele conseguir explicar todas as mudanças corretamente, declare que está pronto para revisão. Caso contrário, liste as mudanças que ele não conseguiu explicar.