agent-engineering-skills 1.0.0

package/skills/research/github-reference-research/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: github-reference-research
+description: Researches how features are implemented on GitHub, searching for feature implementation, architecture, database, API, and framework patterns, and evaluating activity, quality, tests, documentation, adoption, license, and architecture to extract ideas without copying.
+category: research
+triggers:
+  - "research github"
+  - "find production implementations"
+  - "compare feature architecture database api framework"
+  - "evaluate a github project"
+  - "what are real projects doing"
+priority: high
+---
+
+# GitHub Reference Research
+
+## Objective
+
+Ensinar o agente a pesquisar como **implementações reais** resolvem o problema, usando
+GitHub como fonte, e a **extrair ideias sem copiar cegamente** (ver `AGENTS.md` § 1).
+
+## When to Use
+
+* Quando o `research-router` despacha para GitHub (problemas de arquitetura,
+  implementação, ou quando documentação oficial não basta).
+* Quando você precisa ver como projetos de produção implementam: `feature
+  implementation`, `feature architecture`, `feature database`, `feature API`,
+  `feature framework`.
+* Quando o pedido menciona "how is this done in production", "GitHub reference",
+  "open source example", "real-world implementation".
+* **Composição:** pareia com `reference-research` (catálogo) e
+  `implementation-research` (como resolver um problema técnico específico). Alimenta
+  `market-research` (produtos reais).
+
+## Mental Model
+
+GitHub é uma biblioteca de decisões de engenharia — cada repositório maduro é uma
+resposta documentada a um conjunto de trade-offs. O modelo é:
+
+```text
+per feature:
+    como a implementação é estruturada?   (feature implementation)
+    como a arquitetura encaixa?           (feature architecture)
+    como o dado é modelado?               (feature database)
+    como a API expõe?                     (feature API)
+    qual framework/primitiva é usado?     (feature framework)
+```
+
+E a avaliação de cada repositório candidato (do `plan.md` §13):
+
+```text
+atividade      — recente? mantido? abandonado?
+qualidade      — código limpo? padrões? complexidade?
+testes         — há testes? cobrem os casos críticos?
+documentação   — README, docs, exemplos?
+adoção         — stars/forks/uso real (com cuidado: stars ≠ qualidade)
+licença        — compatível com o uso pretendido?
+arquitetura    — limpa? modular? acoplada?
+```
+
+A pergunta central: **o que esta implementação decide, e por quê?** Não "copie o
+código", mas "que trade-off esta decisão representa, e ele é bom para o meu caso?"
+
+## Investigation Procedure
+
+1. **Definir a feature e as 5 dimensões** (implementation/architecture/database/API/
+   framework) que importam para o problema.
+2. **Buscar repositórios** com queries de `references/research.yaml` e
+   `references/engineering.yaml` (ex: "<feature> implementation", "<feature> database
+   schema").
+3. **Triar candidatos** — avaliar atividade, qualidade, testes, documentação, adoção,
+   licença, arquitetura. Descartar os que falham nos critérios.
+4. **Ler a implementação relevante** — os arquivos-chave da feature (não o repo
+   inteiro). Entender a estrutura, o modelo de dados, a API, o framework.
+5. **Extrair as decisões** — quais escolhas estruturais, quais trade-offs, quais
+   padrões (idempotência, transações, cache, tratamento de erro).
+6. **Adaptar** — como aplicar ao projeto atual sem copiar. (princípios sim, código
+   específico não).
+7. **Sintetizar** no formato obrigatório de pesquisa (ver `AGENTS.md` § 5).
+
+## Questions to Ask
+
+* A implementação da feature é modular ou um blob?
+* A arquitetura é limpa? (camadas, boundaries) ou acoplada?
+* O modelo de dados reflete o domínio? (unique, FK, enums — ver `data-integrity-audit`)
+* A API expõe primitivas limpas ou vaza detalhes internos?
+* Qual framework/primitiva resolve a parte difícil? (e qual trade-off isso impõe?)
+* O projeto é mantido? (atividade recente, responde a issues)
+* Tem testes? Cobrem os casos críticos (concorrência, erro, edge)?
+* A documentação explica decisões, ou só a API?
+* A adoção é real ou só stars? (forks, dependents, empresas conhecidas)
+* A licença permite o uso? (MIT/Apache vs GPL/copyleft)
+* O que NÃO copiar? (estrutura específica, código proprietário, configuração de
+  ambiente do repo)
+
+## Attack Patterns
+
+A skill não "ataca" o sistema, mas os padrões de investigação são:
+
+```text
+feature específica
+    ↓
+buscar repositórios (implementation/architecture/database/api/framework)
+    ↓
+triar por atividade/qualidade/testes/docs/adoção/licença/arquitetura
+    ↓
+ler a implementação relevante (arquivos-chave da feature)
+    ↓
+extrair decisões e trade-offs (não copiar)
+    ↓
+adaptar ao contexto
+    ↓
+sintetizar e recomendar
+
+busca muito ampla ou vaga
+    ↓
+refinar query (references/research.yaml) + priorizar fonte de alta autoridade
+```
+
+## Evidence Requirements
+
+* **Nomear o repositório e a URL.**
+* **Avaliar os critérios explicitamente** — atividade, qualidade, testes,
+  documentação, adoção, licença, arquitetura. Diga o que você verificou e o que não.
+* **Mostrar o padrão extraído** (não o link — o padrão). Ex: "o projeto usa um
+  idempotency key + unique constraint para evitar duplicação de pedido".
+* **Explicitar a adaptação** — como aplicar sem copiar.
+* **Escalar confiança (Research):**
+  * `CONFIRMED` — leu a implementação e o padrão está claramente presente.
+  * `HIGH CONFIDENCE` — padrão identificado em leitura parcial, forte indício.
+  * `POSSIBLE` — padrão inferido de README/estrutura, não confirmado no código.
+  * `SPECULATIVE` — suposição sobre o repo sem ler a parte relevante.
+
+## False Positives
+
+* **Stars ≠ qualidade** — repositório popular pode ter arquitetura ruim. Avaliar a
+  implementação, não a popularidade.
+* **Repo desatualizado** — um projeto parado há 3 anos pode usar padrões obsoletos.
+  Verificar atividade antes de confiar.
+* **Licença incompatível** — código GPL/copyleft não pode ser copiado livremente.
+  Verificar licença antes de recomendar adoção.
+* **Copiar em vez de extrair** — "este repo faz X assim" ≠ "devemos fazer X assim".
+  Sempre adaptar ao contexto. Ver `AGENTS.md` § 1.
+* **Repo como única fonte** — GitHub é uma perspectiva; combinar com documentação
+  oficial e produtos reais. Não decidir só por um repo.
+
+## Output Format
+
+Usar o formato de síntese do `plan.md` §17:
+
+```markdown
+## Research
+
+### Reference
+[Nome do repositório + link]
+
+### Relevant Pattern
+O que foi encontrado.
+
+### Why It Matters
+Por que este padrão é útil.
+
+### Adaptation
+Como ele poderia se aplicar ao projeto atual.
+
+### Trade-offs
+Que problemas ele introduz.
+
+### Recommendation
+O que deve de fato ser adotado.
+```
+
+### Evidence Requirements
+
+* **Nomear o repositório e a URL.**
+* **Avaliar os critérios explicitamente** — atividade, qualidade, testes,
+  documentação, adoção, licença, arquitetura. Diga o que você verificou e o que não.
+* **Mostrar o padrão extraído** (não o link — o padrão). Ex: "o projeto usa um
+  idempotency key + unique constraint para evitar duplicação de pedido".
+* **Explicitar a adaptação** — como aplicar sem copiar.
+* **Escalar confiança (Research):**
+  * `CONFIRMED` — leu a implementação e o padrão está claramente presente.
+  * `HIGH CONFIDENCE` — padrão identificado em leitura parcial, forte indício.
+  * `POSSIBLE` — padrão inferido de README/estrutura, não confirmado no código.
+  * `SPECULATIVE` — suposição sobre o repo sem ler a parte relevante.
+
+### False Positives
+
+* **Stars ≠ qualidade** — repositório popular pode ter arquitetura ruim. Avaliar a
+  implementação, não a popularidade.
+* **Repo desatualizado** — um projeto parado há 3 anos pode usar padrões obsoletos.
+  Verificar atividade antes de confiar.
+* **Licença incompatível** — código GPL/copyleft não pode ser copiado livremente.
+  Verificar licença antes de recomendar adoção.
+* **Copiar em vez de extrair** — "este repo faz X assim" ≠ "devemos fazer X assim".
+  Sempre adaptar ao contexto. Ver `AGENTS.md` § 1.
+* **Repo como única fonte** — GitHub é uma perspectiva; combinar com documentação
+  oficial e produtos reais. Não decidir só por um repo.

package/skills/research/implementation-research/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: implementation-research
+description: Researches how specific technical problems are solved in practice, prioritizing official documentation, GitHub, maintainer discussions, production code, and technical articles, and synthesizes findings into an actionable recommendation.
+category: research
+triggers:
+  - "research a technical problem"
+  - "find how to implement a pattern"
+  - "official documentation lookup"
+  - "maintainer discussions and production code"
+  - "technical article research"
+priority: high
+---
+
+# Implementation Research
+
+## Objective
+
+Ensinar o agente a pesquisar como **problemas técnicos específicos** são resolvidos na
+prática — com uma hierarquia de fontes priorizada — e a sintetizar em uma recomendação
+acionável, nunca apenas uma lista de links.
+
+## When to Use
+
+* Quando há um problema técnico concreto (biblioteca, API, padrão, integração,
+  performance, concorrência) e você precisa saber como resolvê-lo bem.
+* Quando o `research-router` despacha para implementação (arquitetura, framework,
+  problemas específicos).
+* Quando o pedido menciona "how to implement X", "best way to do X", "library
+  choice", "framework pattern", "technical deep dive".
+* **Composição:** pareia com `github-reference-research` (implementações reais),
+  `reference-research` (catálogo), e `market-research` (produtos).
+
+## Mental Model
+
+A pergunta é: **como este problema técnico é resolvido na prática, e qual solução se
+encaixa no meu contexto?** A resposta vem de fontes em uma hierarquia de confiabilidade
+(do `plan.md` §13):
+
+```text
+official documentation   — a fonte de verdade para a API/framework
+GitHub                   — implementações reais, issues, PRs
+maintainer discussions   — issues/PRs/CHANGELOG explicam decisões e gotchas
+production code          — como projetos maduros fazem na prática
+technical articles       — análises, comparações, benchmarks
+```
+
+Cada fonte responde a uma pergunta diferente:
+* **official docs** — o que a API permite, a forma canônica;
+* **GitHub/issues/PRs** — como é usado na prática, quais problemas apareceram, quais
+  decisões os maintainers tomaram;
+* **production code** — o padrão real em escala, com edge cases reais;
+* **articles** — comparações e análise crítica que sintetizam o acima.
+
+## Investigation Procedure
+
+1. **Definir o problema técnico específico** — não "caching", mas "invalidação de
+   cache com escrita concorrente em Redis".
+2. **Consultar a documentação oficial** primeiro — a API/framework, o pattern
+   canônico. Esta é a base.
+3. **Se a dúvida persiste** (edge case, trade-off, comportamento não documentado):
+   ir para GitHub/issues/PRs e maintainer discussions — como outros resolveram, que
+   problemas relataram.
+4. **Conferir com production code** — como projetos maduros implementam o padrão.
+5. **Sintetizar com artigos** se necessário — comparações, benchmarks, análise.
+6. **Extrair decisões e trade-offs** — a recomendação final.
+7. **Sintetizar** no formato obrigatório de pesquisa (ver `AGENTS.md` § 5).
+
+## Questions to Ask
+
+* O que a documentação oficial diz? (a forma canônica)
+* A documentação resolve o caso específico ou só o happy path?
+* Que issues/PRs existem sobre este caso? (gotchas relatados)
+* Que decisão os maintainers tomaram e por quê? (design rationale)
+* Como projetos de produção implementam? (padrão real, edge cases reais)
+* Que trade-offs a solução escolhida introduz?
+* Há uma alternativa melhor para o meu contexto? (framework, versão, escala)
+* O que é específico do meu projeto e não deve ser copiado?
+* A fonte é de alta autoridade (docs, maintainers) ou inferência? (peso da evidência)
+
+## Attack Patterns
+
+A skill não "ataca" o sistema, mas os padrões de investigação são:
+
+```text
+problema técnico específico
+    ↓
+consultar documentação oficial (fonte de verdade)
+    ↓
+se edge case / trade-off não resolvido → GitHub issues/PRs
+    ↓
+se ainda necessário → production code (projetos maduros)
+    ↓
+se comparação ou benchmark → artigos técnicos
+    ↓
+extrair decisões e trade-offs
+    ↓
+sintetizar e recomendar (nunca lista de links)
+
+hierarquia de fontes:
+    official docs > GitHub/issues > production code > articles
+```
+
+## Evidence Requirements
+
+* **Nomear a fonte e sua autoridade** (official docs > GitHub/issues > production
+  code > articles).
+* **Mostrar a solução encontrada** — o padrão, a API, a decisão. Não só o link.
+* **Explicitar os trade-offs** — a solução tem custo (complexidade, lock-in,
+  performance, manutenção)?
+* **Recomendação acionável** — o que adotar no contexto.
+* **Escalar confiança (Research):**
+  * `CONFIRMED` — padrão confirmado em documentação oficial ou maintainer discussion.
+  * `HIGH CONFIDENCE` — padrão claro de produção/artigos de qualidade.
+  * `POSSIBLE` — padrão inferido, uma fonte de autoridade média.
+  * `SPECULATIVE` — especulação sem fonte verificada.
+
+## False Positives
+
+* **Documentação não lida** — citar "segundo a doc" sem ler é especulação. Baixar
+  confiança.
+* **Stack Overflow como fonte primária** — útil para gotchas, mas não substitui a
+  documentação oficial para a forma canônica. Priorizar hierarquia de fontes.
+* **Copiar em vez de adaptar** — o código de produção de outro projeto raramente se
+  adapta direto. Extrair o padrão, adaptar a solução. Ver `AGENTS.md` § 1.
+* **Artigo desatualizado** — benchmarks e comparações envelhecem. Verificar data e
+  versão.
+* **Pesquisa excessiva** — para um problema bem conhecido, a doc oficial basta.
+  Não acumular fontes além do necessário (ver `AGENTS.md` § 6).
+
+## Output Format
+
+Usar o formato de síntese do `plan.md` §17:
+
+```markdown
+## Research
+
+### Reference
+[Nome da fonte + link]
+
+### Relevant Pattern
+O que foi encontrado.
+
+### Why It Matters
+Por que este padrão é útil.
+
+### Adaptation
+Como ele poderia se aplicar ao projeto atual.
+
+### Trade-offs
+Que problemas ele introduz.
+
+### Recommendation
+O que deve de fato ser adotado.
+```
+
+### Evidence Requirements
+
+* **Nomear a fonte e sua autoridade** (official docs > GitHub/issues > production
+  code > articles).
+* **Mostrar a solução encontrada** — o padrão, a API, a decisão. Não só o link.
+* **Explicitar os trade-offs** — a solução tem custo (complexidade, lock-in,
+  performance, manutenção)?
+* **Recomendação acionável** — o que adotar no contexto.
+* **Escalar confiança (Research):**
+  * `CONFIRMED` — padrão confirmado em documentação oficial ou maintainer discussion.
+  * `HIGH CONFIDENCE` — padrão claro de produção/artigos de qualidade.
+  * `POSSIBLE` — padrão inferido, uma fonte de autoridade média.
+  * `SPECULATIVE` — especulação sem fonte verificada.
+
+### False Positives
+
+* **Documentação não lida** — citar "segundo a doc" sem ler é especulação. Baixar
+  confiança.
+* **Stack Overflow como fonte primária** — útil para gotchas, mas não substitui a
+  documentação oficial para a forma canônica. Priorizar hierarquia de fontes.
+* **Copiar em vez de adaptar** — o código de produção de outro projeto raramente se
+  adapta direto. Extrair o padrão, adaptar a solução. Ver `AGENTS.md` § 1.
+* **Artigo desatualizado** — benchmarks e comparações envelhecem. Verificar data e
+  versão.
+* **Pesquisa excessiva** — para um problema bem conhecido, a doc oficial basta.
+  Não acumular fontes além do necessário (ver `AGENTS.md` § 6).

package/skills/research/market-research/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: market-research
+description: Researches real products and how they solved a problem at scale, comparing UX, onboarding, navigation, information architecture, interaction, empty states, errors, mobile, and terminology.
+category: research
+triggers:
+  - "research the market"
+  - "compare with real products"
+  - "how do products solve this at scale"
+  - "onboarding navigation information architecture"
+  - "market benchmark"
+priority: high
+---
+
+# Market Research
+
+## Objective
+
+Ensinar o agente a pesquisar **produtos reais** que resolveram o problema em escala, e
+a comparar como abordam UX, onboarding, navigation, information architecture,
+interaction, empty states, errors, mobile, e terminology. A pergunta não é "qual é o
+mais bonito?" — é (do `plan.md` §13):
+
+> "Como produtos que resolveram esse problema em escala fazem isso?"
+
+## When to Use
+
+* Quando o `skill-router`/`research-router` despacha para pesquisa de mercado (tarefas
+  de produto, UX, frontend).
+* Quando você precisa saber como a indústria resolve um problema de experiência.
+* Quando o pedido menciona "market research", "what do competitors do", "how do
+  products handle X", "benchmark", "best-in-class".
+* **Composição:** pareia com `reference-research` (metodologia de UX) e
+  `github-reference-research` (implementação). Alimenta decisões de produto e frontend.
+
+## Mental Model
+
+Produtos de sucesso em escala resolveram problemas de experiência que você enfrenta.
+Eles são uma **evidência do que funciona** — não porque são bonitos, mas porque
+sobreviveram a milhões de usuários e ao mercado. O padrão que eles convergem é um forte
+sinal de "isto funciona em escala".
+
+Mas cuidado: convergência de mercado ≠ o que você deve fazer. O modelo é:
+
+```text
+identificar o problema de experiência
+    ↓
+encontrar produtos que o resolveram em escala
+    ↓
+comparar como cada um aborda cada dimensão
+    ↓
+extrair padrões convergentes (o que TODO mundo faz)
+    ↓
+identificar padrões divergentes (onde há espaço para diferenciar)
+    ↓
+adaptar ao nosso contexto, não copiar
+```
+
+Dimensões de comparação (do `plan.md` §13):
+
+```text
+UX                    — usabilidade geral, clareza
+onboarding            — primeira experiência, ativação
+navigation            — como o usuário se move
+information architecture — como o conteúdo é organizado
+interaction           — feedback, micro-interações
+empty states          — o que aparece sem dados
+errors                — como falhas são comunicadas
+mobile                — comportamento responsivo/específico
+terminology           — vocabulário usado (consistente? claro?)
+```
+
+## Investigation Procedure
+
+1. **Identificar o problema de experiência** em escopo.
+2. **Selecionar produtos de comparação** — os que resolveram este problema em escala.
+   (De preferência: líderes de mercado, conhecidos, com produto acessível.)
+3. **Para cada produto, avaliar cada dimensão** — UX, onboarding, navigation, IA,
+   interaction, empty states, errors, mobile, terminology.
+4. **Registrar evidências concretas** — não "boa UX", mas "onboarding pergunta 3
+   perguntas antes de pedir signup; empty state tem CTA 'criar primeiro item'".
+5. **Comparar** — onde os produtos convergem? (padrão maduro) onde divergem? (espaço
+   para diferenciação)
+6. **Adaptar** — o que faz sentido para o nosso produto/contexto/público.
+7. **Sintetizar** no formato obrigatório.
+
+## Questions to Ask
+
+* Quais produtos resolveram este problema em escala? (não só os "bonitos")
+* O onboarding deles pede o mínimo antes do valor? Ou exige tudo primeiro?
+* A navegação deles é óbvia ou precisa tutorial? (menu, tabs, search)
+* A information architecture agrupa por tarefa do usuário ou por estrutura interna?
+* As interações dão feedback imediato? (loading, confirmação, undo)
+* O empty state orienta a próxima ação? (ou é um vazio)
+* Erros são legíveis e acionáveis? (ou genéricos)
+* O mobile é uma extensão natural ou uma versão degradada?
+* A terminology é consistente? (o mesmo termo para a mesma coisa)
+* Onde TODOS convergem? (padrão maduro que devemos adotar)
+* Onde eles divergem? (espaço para diferenciar)
+
+## Attack Patterns
+
+A skill não "ataca" o sistema, mas os padrões de investigação são:
+
+```text
+problema de experiência
+    ↓
+selecionar produtos que resolveram em escala (líderes de mercado)
+    ↓
+avaliar cada dimensão (UX/onboarding/nav/IA/interaction/empty/errors/mobile/terms)
+    ↓
+registrar evidência concreta (o que o produto faz, não opinião)
+    ↓
+comparar convergência vs divergência
+    ↓
+adaptar ao nosso contexto (não copiar)
+    ↓
+sintetizar e recomendar
+
+produtos selecionados demais ou vagos
+    ↓
+refinar: 3-6 produtos líderes, foco nas dimensões críticas
+```
+
+## Evidence Requirements
+
+* **Nomear o produto** e sua relevância (líder de mercado, conhecido, em escala).
+* **Registrar a evidência concreta** por dimensão — o que o produto faz, não opinião.
+* **Mostrar convergência/divergência** — onde os padrões se alinham e onde não.
+* **Explicitar a adaptação** — o que faz sentido para o nosso contexto.
+* **Escalar confiança (Research):**
+  * `CONFIRMED` — padrão observado em múltiplos produtos líderes.
+  * `HIGH CONFIDENCE` — padrão observado em 1-2 produtos com clareza.
+  * `POSSIBLE` — padrão inferido de screenshots/descrição.
+  * `SPECULATIVE` — suposição sobre um produto sem ter visto a experiência real.
+
+## False Positives
+
+* **Beleza ≠ solução em escala** — Dribbble (inspiração) não é mercado; é estética.
+  Comparar com produtos que *funcionam*, não com designs bonitos.
+* **Copiar o produto** — "produto X faz assim" não significa que devemos fazer igual.
+  A convergência de mercado é um sinal, não uma ordem. Ver `AGENTS.md` § 1.
+* **Contexto diferente** — um padrão do B2B enterprise pode não se aplicar a um
+  consumer app, e vice-versa. Avaliar o contexto.
+* **Produto sem acesso real** — julgar por screenshots/YouTube é possível, não
+  confirmado. Baixar a confiança.
+* **Pesquisa excessiva** — comparar 20 produtos é overengineering para uma decisão
+  pequena. Proporcionalidade (ver `AGENTS.md` § 6).
+
+## Output Format
+
+Usar o formato de síntese do `plan.md` §17:
+
+```markdown
+## Research
+
+### Reference
+[Nome do produto]
+
+### Relevant Pattern
+O que foi encontrado.
+
+### Why It Matters
+Por que este padrão é útil.
+
+### Adaptation
+Como ele poderia se aplicar ao projeto atual.
+
+### Trade-offs
+Que problemas ele introduz.
+
+### Recommendation
+O que deve de fato ser adotado.
+```
+
+Para comparações entre múltiplos produtos, produza um bloco por produto e uma seção
+final "Convergência e divergência" resumindo os padrões convergentes (adotar) e
+divergentes (avaliar).
+
+### Evidence Requirements
+
+* **Nomear o produto** e sua relevância (líder de mercado, conhecido, em escala).
+* **Registrar a evidência concreta** por dimensão — o que o produto faz, não opinião.
+* **Mostrar convergência/divergência** — onde os padrões se alinham e onde não.
+* **Explicitar a adaptação** — o que faz sentido para o nosso contexto.
+* **Escalar confiança (Research):**
+  * `CONFIRMED` — padrão observado em múltiplos produtos líderes.
+  * `HIGH CONFIDENCE` — padrão observado em 1-2 produtos com clareza.
+  * `POSSIBLE` — padrão inferido de screenshots/descrição.
+  * `SPECULATIVE` — suposição sobre um produto sem ter visto a experiência real.
+
+### False Positives
+
+* **Beleza ≠ solução em escala** — Dribbble (inspiração) não é mercado; é estética.
+  Comparar com produtos que *funcionam*, não com designs bonitos.
+* **Copiar o produto** — "produto X faz assim" não significa que devemos fazer igual.
+  A convergência de mercado é um sinal, não uma ordem. Ver `AGENTS.md` § 1.
+* **Contexto diferente** — um padrão do B2B enterprise pode não se aplicar a um
+  consumer app, e vice-versa. Avaliar o contexto.
+* **Produto sem acesso real** — julgar por screenshots/YouTube é possível, não
+  confirmado. Baixar a confiança.
+* **Pesquisa excessiva** — comparar 20 produtos é overengineering para uma decisão
+  pequena. Proporcionalidade (ver `AGENTS.md` § 6).