hec-ovi/research-skill

Research

Store persistente com escopo de projeto para resultados de pesquisa aprofundada. Você ativou esta habilidade porque o usuário fez uma pergunta de pesquisa substantiva, ou a invocou explicitamente com /research <tópico>.

Se invocada com um argumento de tópico (ex.: /research tailwind-v5), use-o como semente para Recuperação - comece consultando aquele tópico em INDEX.md. Não pesquise às cegas; a consulta pode responder imediatamente.

Quando usar

• "qual é o pacote npm mais recente que faz X"
• "compare A vs B vs C para 2026"
• "quais engines / frameworks / bibliotecas podem clonar X rapidamente"
• "pesquise como Y funciona internamente"
• "mergulho profundo em Z"
• O usuário cola um longo bloco de pesquisa em markdown e pede para salvá-lo

Quando NÃO usar

• Anotações de fase de planejamento
• Pequenos fatos ou preferências de uma linha
• Decisões de código vinculadas a um único arquivo
• Consultas casuais que podem ser respondidas a partir de uma única fonte sem síntese
• Registrar ideias ou divagações pessoais
• Como substituto para uma única WebSearch ou WebFetch

Se uma única WebSearch + 1-2 frases respondem à pergunta, você não precisa desta habilidade.

Configuração (apenas no primeiro uso)

Na primeira ativação em um projeto, faça isso uma vez:

1. Resolva a raiz do projeto: git rev-parse --show-toplevel 2>/dev/null || pwd

2. Crie <root>/.research/ se não existir

3. Crie <root>/.research/INDEX.md com este conteúdo exato:

   # Research index
   
   | Tópico | Caminho | Última verificação | Resumo em uma linha |
   |---|---|---|---|
   

4. Adicione .research/ a <root>/.gitignore. Se .gitignore não existir, crie-o. Os dados de pesquisa podem conter insights proprietários, padrão privado.

Os dados residem em <root>/.research/ (um diretório irmão de .claude/, não aninhado dentro dele). É um diretório de projeto de nível superior, escolhido para que os dados de pesquisa fiquem colocalizados com o projeto, ignorados por git por padrão e fáceis de encontrar pelo nome. A auditoria permanece intacta: cada leitura e escrita passa pelo sistema de permissão normal do host.

Fluxo de trabalho

1. Recuperação (o lado da leitura - é assim que a habilidade salva seu contexto)

O objetivo principal deste sistema é a divulgação progressiva: não carregue o que você não precisa. INDEX.md é seu despachante - ele permite que você decida quais entradas carregar sem pagar para carregá-las. Percorra a hierarquia da mais barata para a mais cara; só escale quando a camada anterior não responder à pergunta.

Hierarquia de carregamento (mais barata → mais cara)

Nível	Carregar	Aprox. tokens	Quando
1	INDEX.md (sempre)	~100-500	Toda recuperação - sua tabela de roteamento
2	Apenas ## Summary da entrada	~50-200	Quando o índice mostra uma correspondência de tópico
3	Corpo completo de FINDINGS.md	~500-3000	Quando o Resumo não cobre a pergunta
4	Documento específico raw/<arquivo>	varia (frequentemente pesado)	Quando uma descoberta o cita e você precisa verificar uma afirmação
5	Entrada referenciada (related:)	repete níveis 2-3	Quando a pergunta abrange múltiplas entradas

Procedimento de consulta

1. Leia INDEX.md primeiro (nível 1). Escaneie a coluna de resumo em uma linha em relação à pergunta do usuário. Este é o despachante - mesmo papel que RESOLVER.md no GBrain.

2. Decisão de correspondência:

   • Correspondência forte - o resumo de uma entrada cobre claramente o tópico → vá para o passo 3 com essa entrada.
   • Múltiplas correspondências plausíveis - carregue ## Summary de cada uma (ainda barato no nível 2). Escolha a(s) que realmente respondem.
   • Correspondência fraca / nenhuma → passe para a Investigação. Uma nova entrada será adicionada.

3. Leia apenas o ## Summary da entrada correspondente (nível 2):

   sed -n '/^## Summary/,/^## /p' <root>/.research/<slug>/FINDINGS.md
   

   Geralmente suficiente.

4. Escalar um nível apenas quando necessário:

   • A pergunta precisa de detalhes no nível de afirmações além do Resumo → carregue o corpo completo de FINDINGS.md (nível 3).
   • A pergunta é "já tentamos X antes / o que foi descartado?" → use sed apenas nessa seção: sed -n '/^## Discarded approaches/,/^## /p' <root>/.research/<slug>/FINDINGS.md. Não carregue o resto.
   • A pergunta referencia uma afirmação citada em uma colagem → abra o arquivo específico em raw/ (nível 4).
   • A pergunta abrange tópicos cobertos por entradas separadas → siga related: e repita os níveis 2-3 em cada uma.

5. Passe para a Investigação. Escolha o modo:

   • Nenhuma entrada existe em INDEX.md → Investigação no modo nova entrada.
   • Entrada existente não resolve a pergunta (problema ainda não resolvido) → Investigação no modo mesclagem (passe o conteúdo da entrada existente para o subagente).
   • Entrada existente está desatualizada em um tópico que muda rapidamente → Investigação no modo mesclagem (atualize, não cite).

O que NUNCA fazer

• Não carregue tudo. O esquema existe para que você possa ser seletivo.
• Não carregue o corpo completo quando o Resumo for suficiente. Se 3 linhas respondem, não puxe 300.
• Não carregue documentos brutos especulativamente. Eles são pesados; a maioria das perguntas não precisa deles.
• Não releia uma entrada que você já carregou nesta sessão - a menos que ela tenha sido atualizada desde então.

INDEX.md como despachante

INDEX.md existe apenas para que você possa decidir quais entradas carregar sem carregá-las. A coluna de resumo em uma linha é todo o sinal que você tem antes de pagar por uma leitura de entrada - escreva-a especificamente ao armazenar.

Mantenha INDEX.md enxuto: abaixo de ~100 linhas. Se crescer além disso, pode ou arquive. Todo o design de economia de tokens desmorona se o próprio INDEX.md se tornar uma fonte de inchaço.

2. Investigação (quando uma nova pesquisa é necessária)

Crie um subagente de general-purpose com model: "opus" e run_in_background: true. A fase de Investigação precisa de um modelo forte: a passagem de contraponto e as etapas de síntese dependem de profundidade de raciocínio que modelos menores não entregarão. O modo em segundo plano mantém a conversa interativa: o usuário pode continuar trabalhando enquanto a pesquisa é executada. O armazenamento é executado de forma assíncrona quando a notificação de conclusão do agente chega.

O subagente faz a pesquisa e retorna sua síntese como texto estruturado. Ele NÃO escreve nenhum arquivo. Você (agente principal) lida com todas as escritas de arquivos no Armazenamento. Essa divisão mantém a responsabilidade limpa: o subagente tem zero contexto e não precisa conhecer seu esquema ou layout de INDEX.md.

Convenção de nomenclatura. Defina o parâmetro description da ferramenta Agente como Investigação de pesquisa: <tópico> (3 a 5 palavras). Isso torna os spawns do research-skill identificáveis na interface do harness.

Ao receber notificação de conclusão: analise o retorno do agente, aplique o Armazenamento imediatamente, exiba uma breve notificação ao usuário (ex.: "pesquisa sobre <tópico> salva em <caminho>"). Não despeje todas as descobertas no chat, a menos que solicitado.

Subagentes têm zero contexto prévio. Eles não veem esta habilidade, CLAUDE.md ou nossa conversa. Faça um briefing completo para eles. Não há continuação neste harness - a ferramenta SendMessage para retomar um agente não está disponível. Apenas uma tentativa. Se houver lacunas, recrie com um briefing refinado.

O modo (nova entrada vs mesclagem) foi decidido na fase 5 de Recuperação. Faça o briefing do subagente de acordo:

• Modo nova entrada - briefing padrão, sem contexto existente a fornecer.
• Modo mesclagem - cole o ## Summary da entrada existente e quaisquer seções relevantes de ## Findings no briefing, marcadas claramente como "estado atual da entrada - verifique, atualize ou substitua". Diga ao subagente para sinalizar afirmações que agora estão erradas.

Lista de verificação do briefing

Todo briefing de Investigação DEVE incluir:

• Preâmbulo "Você tem zero contexto prévio"
• Data real de hoje (execute date +%Y-%m-%d primeiro; passe a string literal)
• Regra de fixação de ano para consultas WebSearch (não confie no conhecimento prévio do modelo do subagente sobre o ano atual)
• Pelo menos 2 fontes independentes por afirmação não trivial. As fontes são reunidas em um único bloco ## Sources no final do retorno; NÃO cite inline.
• As fases cognitivas abaixo como etapas numeradas explícitas
• O formato de saída exigido do subagente (abaixo)
• A regra estrita de não usar [n] / nenhuma URL inline no corpo das Descobertas (consulte Formato de saída exigido)
• Apenas modo mesclagem: o conteúdo da entrada existente que o subagente deve verificar / substituir

Fases cognitivas (incluir textualmente no briefing do subagente)

O subagente percorre estas como fases discretas. A fase 4 é crítica:

1. Decompor - liste as sub-afirmações que resolveriam a pergunta; identifique quais evidências resolvem cada uma.
2. Coletar - para cada sub-afirmação, encontre ≥2 fontes independentes (WebSearch com fixação de ano → WebFetch nos principais resultados). Cite textualmente. Ainda não sintetize.
3. Validar - recalcule números, benchmarks, alegações de versão. Sinalize qualquer coisa que falhar.
4. Passagem de contraponto - pesquise ativamente por "por que isso está errado / é golpe / criticado / obsoleto / conhecidamente ruim". Declare a objeção mais forte encontrada. Pular esta etapa é o modo de falha mais comum do subagente. Mencione isso explicitamente no briefing.
5. Sintetizar - veredito + citações + discordâncias residuais listadas explicitamente. Sem escolhas silenciosas.

Formato de saída exigido do subagente

O briefing DEVE incluir regras de citação explícitas. Subagentes treinados em estilo acadêmico usam [1], [2] como citações inline; sem instruções explícitas, eles produzirão saída ruidosa. Declare as regras em linguagem simples. Bloco textual recomendado para colar no briefing:

Regras de citação. Leia com atenção e siga exatamente:

• NÃO use citações numeradas [n]. Sem [1], [2] ou qualquer número entre colchetes no corpo das Descobertas.
• NÃO coloque URLs no corpo das Descobertas.
• NÃO adicione marcadores de nota de rodapé inline, âncoras ou quaisquer tags de citação por afirmação de qualquer tipo.
• Escreva as Descobertas como parágrafos em prosa simples.
• Quando a interpretação de uma afirmação depender de qual fonte a disse, nomeie a fonte em prosa, sem colchetes ("de acordo com o README", "segundo littlemight.com", "o comentarista do HN-simulator argumenta..."). Sem URL, sem [n].
• Coloque TODAS as fontes em um único bloco ## Sources no FINAL do retorno, um marcador por fonte: - url - buscado em AAAA-MM-DD. O agente principal copia este bloco para o frontmatter de FINDINGS.md.
• A disciplina de contagem de fontes é preservada: pelo menos 2 fontes independentes por afirmação não trivial. A disciplina está na contagem de fontes, não na marcação inline.

Formato de saída exigido (o que o subagente retorna):

## Summary
3 a 6 linhas de resumo.

## Findings
Prosa simples. Sem marcadores `[n]`. Sem URLs inline. Nomeação de fonte inline apenas em prosa quando for essencial para a interpretação.

## Strongest objection (da passagem de contraponto)
1 a 2 frases, ou "nenhuma encontrada".

## Sources
- url - buscado em AAAA-MM-DD
- url - buscado em AAAA-MM-DD

## (Apenas modo mesclagem) Supersedes
- afirmação da entrada existente que agora está errada + motivo

O subagente não escreve nenhum arquivo. Você analisa este retorno e aplica as regras de Armazenamento.

Tratamento de lacunas

Se o retorno do subagente tiver lacunas:

• Pequena lacuna (um fato faltante, um ângulo específico) → preencha você mesmo com uma WebSearch / WebFetch focada. Mais barato do que recriar.
• Grande lacuna (seções inteiras superficiais, passagem de contraponto claramente pulada) → recrie com um briefing refinado que nomeie a lacuna específica. O retorno anterior é descartado (nenhum arquivo foi escrito ainda).

3. Armazenamento (o lado da escrita - o agente principal é responsável por TODAS as escritas de arquivos)

Revisão antes de armazenar

O formato estruturado do subagente não valida o conteúdo. O formato apenas sinaliza "eu segui o modelo"; ele não confirma que o conteúdo está correto, bem fundamentado ou relevante para o que foi perguntado. Antes de aplicar o Armazenamento, execute esta verificação de 4 pontos:

1. Relevância: o Resumo realmente responde ao que foi perguntado? Se o agente desambiguou um tópico ambíguo (escolheu uma interpretação entre várias), confirme se corresponde à intenção do usuário. Se estiver errado, recrie com um briefing mais restrito; não armazene.
2. Qualidade da fonte: conte URLs primárias vs trechos agregados de WebSearch no bloco ## Sources. Se a maioria das fontes são resumos de resultados de busca sem URLs específicas buscadas, a entrada é mais fraca do que parece. Preencha as primárias você mesmo com WebFetch focado ou armazene, mas sinalize a fraqueza explicitamente em ## Open questions.
3. Evidência de contraponto: "nenhuma encontrada" é raro em qualquer tópico não trivial. Se você recebeu "nenhuma encontrada", seja cético: ou o tópico é genuinamente não controverso (raro), ou o subagente pulou a fase 4 (comum). Se pulou, preencha você mesmo com pesquisas de contraponto focadas ou recrie.
4. Limpeza de citações: se o retorno contiver marcadores [n] no corpo das Descobertas, apesar da regra de não usar [n] no briefing, remova-os antes de escrever FINDINGS.md. Este é um modo de falha conhecido (subagentes recorrem a hábitos acadêmicos de citação). Não propague o ruído adiante. O mesmo vale para URLs inline no corpo das Descobertas: remova-os. As fontes pertencem ao frontmatter.

Se a revisão revelar lacunas corrigíveis, preencha-as você mesmo com uma WebSearch/WebFetch focada (mais barato do que recriar). Se as lacunas forem sistêmicas, recrie com um briefing refinado; não escreva uma entrada malformada.

Aplicar Armazenamento

Depois que a Investigação retornar sua síntese (ou o usuário colar descobertas), você (agente principal, nunca o subagente) finaliza a camada de dados. Dois caminhos, escolhidos com base no modo selecionado na fase 5 de Recuperação:

Caminho de nova entrada:

1. Crie <root>/.research/<slug-do-tópico>/.
2. Escreva FINDINGS.md usando o esquema em Esquemas de arquivo. Frontmatter: created e last_verified = hoje; status: active; sources do retorno do subagente; raw: omitido (ainda sem raw); related: [] a menos que links cruzados se apliquem.
3. Leia INDEX.md, anexe uma linha: tópico, caminho, data de hoje, um resumo específico em uma linha.

Caminho de mesclagem:

1. Leia o FINDINGS.md existente.
2. Atualize o frontmatter: last_verified = hoje; anexe novas fontes.
3. Aplique a lista ## Supersedes do subagente: mova cada afirmação nomeada de ## Findings para ## Discarded approaches com data e motivo. Consulte Tratamento de conflitos.
4. Atualize / estenda ## Findings com novas afirmações.
5. Anexe uma entrada ## Timeline resumindo a alteração.
6. Leia INDEX.md, atualize a coluna Last verified da linha. Atualize o resumo em uma linha se o panorama mudou.

Use slugs em kebab-case que correspondam a como o usuário provavelmente perguntará novamente - ex.: tailwind-v5, 2d-engines-clonable, orm-comparison-2026. O slug deve desambiguar.

4. Passado

…

(truncado para tradução)