dbhq-uk/legwork-skill

Legwork

Para que serve

Pesquisa para tomada de decisão. Não é pesquisa acadêmica. A pergunta é sempre alguma versão de "o que devemos fazer sobre X", e o resultado é julgado por ser utilizável, não por ser exaustivo.

Isso molda tudo abaixo. Uma afirmação é julgada se sua fonte é o tipo certo de coisa para aquela afirmação, não se seu domínio é respeitável. Três fontes concordando só conta se elas poderiam ter discordado. E uma execução que não consegue responder a pergunta diz isso em vez de produzir um texto cheio de ressalvas.

Princípio da autonomia. Inferir o que você precisa do contexto, escolher um nível e começar. Anunciar o nível em uma linha e prosseguir; não perguntar ao usuário para escolher. Eles podem redirecionar durante a execução, o que custa muito menos do que uma pergunta bloqueante em cada solicitação. Parar apenas para um erro crítico ou uma consulta incompreensível.

Níveis

A profundidade aumenta o rigor. Nunca aumenta o tamanho.

	rápido	padrão	profundo
Enquadramento	Decisão mais 2-3 subperguntas	Mais falsificadores nomeados	Mais ângulos de segunda ordem
Coleta	Trechos SERP; buscar apenas para fixar um número	Busca direta das principais fontes por descoberta	Uma fonte primária para cada descoberta
Desafio	Apenas agrupamento por independência	Uma pesquisa desconforme por descoberta	Passagem desconforme por descoberta mais auditoria de origem
Formato	breve	breve ou relatório	relatório
Nível de porta	--level quick	--level standard	--level deep
Tempo aproximado	3-5 min	8-12 min	20-40 min

O padrão é padrão. Usar o nível que o usuário nomear (quick, standard, deep, ou um equivalente como "varredura rápida" ou "aprofundar"), senão $LEGWORK_DEFAULT_MODE, senão padrão. "Pesquisa aprofundada" por si só é uma frase de invocação para este skill, não uma solicitação para o nível profundo - cair para o padrão.

Escalar silenciosamente em um nível se o escopo revelar que a pergunta é materialmente de maior risco do que a solicitação implicava, e dizer isso na mesma linha de abertura.

Linha de abertura, então direto para a Fase 1:

Executando padrão (~8-12 min). Diga "profundo" para fontes primárias e uma passagem desconforme.

Pipeline

Quatro fases. Instruções completas em methodology.md.

1. Enquadrar - nomear a decisão, as subperguntas que a resolveriam e que evidências mudariam a resposta.
2. Coletar - recuperar contra cada subpergunta, registrando cada busca.
3. Desafiar - caçar o caso desconforme; agrupar fontes por independência.
4. Escrever - montar o resultado, então submetê-lo à porta.

As fases 2 e 3 se intercalam por descoberta, em vez de funcionar como portas estritas.

Antes de começar

Ancorar a data. Executar date -u +%Y-%m-%d e usar essa string para a execução, no nome da pasta de saída, e em cada consulta de pesquisa que possa retornar material datado. Nunca confiar em seu próprio senso de que ano é, e nunca deixar um subagente descobrir isso sozinho.

Verificar se esta execução já foi feita. Ler o índice primeiro. Ele é um despachante: uma linha por execução passada, e a coluna de resumo de uma linha existe para que você decida se deve abrir um relatório sem pagar para abri-lo.

python3 ${CLAUDE_SKILL_DIR}/scripts/index.py list --base "$OUTPUT_BASE"

Então escolher um dos quatro caminhos, e dizer qual em sua linha de abertura:

O índice diz	Faça isso
Uma execução cobre isso e não está desatualizada	Responder a partir dela. Ler aquele relatório, não a web.
Uma execução cobre isso mas está marcada como desatualizada	Atualizar
Uma execução é próxima mas responde a uma pergunta diferente	Nova execução, e fazer referência cruzada
Nada corresponde	Nova execução

Responder a partir de uma execução anterior é um sucesso, não um atalho. Abrir o relatório, ler as descobertas que dizem respeito à pergunta, e responder com suas bandas de confiança intactas. Dizer claramente que vem de uma execução de uma determinada data. Re-executar pesquisa que já foi feita e ainda é válida é o desperdício que este índice existe para prevenir.

Atualizar em vez de re-executar

Uma atualização atualiza o relatório existente no lugar - mesma pasta, mesmo arquivo. Não criar uma segunda pasta: duas pastas descrevendo uma pergunta é como um leitor acaba agindo com base na que ele abriu.

1. Retomar o log de busca em vez de começar um novo. Tudo nele já está pago.

   python3 ${CLAUDE_SKILL_DIR}/scripts/sources.py resume --tsv "$OUT/$BASE.tsv"
   

   Isso imprime os ângulos já trabalhados, as páginas já buscadas e quais delas ainda não têm citação. Trabalhar os ângulos não cobertos e re-verificar as afirmações que decidem a resposta; não buscar novamente o que já está registrado e atual.

2. Mover cada afirmação que agora está errada para ## Substituído com a data e o motivo. Nunca deletar uma afirmação silenciosamente. Alguém pode ter agido com base nela, e uma execução futura precisa saber que este terreno já foi coberto. Se a mesma resposta foi agora revertida duas vezes, dizer isso alto - esse é o sinal mais forte no documento de que a pergunta é instável.

3. Acrescentar uma linha ## Linha do Tempo dizendo o que mudou.

4. Atualizar a linha do índice.

Arquivar a execução

Toda execução termina no índice, incluindo uma que não conseguiu responder - "procuramos e não encontramos nada" é exatamente o que uma sessão futura precisa para não procurar de novo.

python3 ${CLAUDE_SKILL_DIR}/scripts/index.py add --base "$OUTPUT_BASE" \
  --folder "$BASE" --topic "Triagem de Outlook para pequenos consultórios" --level deep \
  --one-liner "Nenhuma triagem nativa abaixo de E5; a lacuna é real, mas estreita"

O resumo de uma linha diz o que a execução concluiu, não sobre o que era. "Notas sobre a galeria de plugins" é inútil seis meses depois; "Nenhuma rota de submissão existe, a instalação é por URL ou não acontece" responde a pergunta por si só. A porta avisa quando uma execução está faltando em um índice que existe.

Política de recuperação

Duas escadas, degraus gratuitos primeiro. Subir apenas até onde for necessário.

Para pesquisar:

Degrau	Chamada	Quando
1	WebSearch	Sempre. Três variantes de consulta por ângulo.
2	platforms.py search --on ...	A resposta é um registro que uma plataforma possui: um tópico, um pacote, um repositório, uma notícia datada, um changelog de fornecedor. Gratuito, sem chave, e retorna o registro em vez de uma página sobre ele.
3	bd_search.py -m general --engine bing --country XX --language yy	Escasso após três variantes, ou a pergunta é geo-específica. Um segundo mecanismo é a razão para pagar.
4	bd_search.py -m discover --intent "..."	Dois mecanismos ainda escassos.

Para abrir uma página:

Degrau	Chamada	Quando
1	fetch.py "<url>" --find "termo"	Sempre primeiro. Grátis, e o único transporte gratuito que produz texto de página, para que figuras possam ser rastreadas e citações verificadas.
2	WebFetch	fetch.py saiu com código 3 e a página não vale a pena pagar.
3	bd_search.py "<url>" -m scrape	Bloqueado: proteção contra bots, paywall, 403.
4	bd_search.py "<url>" -m render	Um shell renderizado pelo cliente.
5	bd_search.py "<url>" -m pipeline --pipeline NOME	Uma plataforma que bloqueia tudo acima. Cobrado por registro; -m reddit é onde é a única rota, não um último recurso.

Executar platforms.py list para as dez plataformas gratuitas, e bd_search.py --help para os modos pagos. No código de saída 2 (autenticação ou cota), dizer ao usuário para executar brightdata login. Não repetir.

Um resultado de pesquisa é uma pista, não uma página que você lê. No padrão e profundo, abrir o que você cita: a porta trata uma citação baseada apenas em linhas websearch como não aberta, um aviso no padrão e um erro no profundo. Rápido é focado em trechos por design e não é questionado.

Registrar a falha antes da alternativa. Uma página que não abriu é evidência sobre a execução - --status blocked - e o recibo a conta.

Limitar o que você puxa. --max-chars 8000 em chamadas de scrape, e preferir --find a um limite cego: em uma página longa, os primeiros oito mil caracteres são geralmente a navegação.

Fontes que você pode usar

Pesquisa é o que um terceiro poderia estabelecer. Esse limite é importante em ambas as direções.

Nunca apresentar os próprios registros do usuário como uma descoberta. Se a pergunta é sobre a própria empresa, produto ou posição de mercado do usuário, não acessar suas contas privadas - seu registrador, sua faturamento, sua caixa de entrada, seus arquivos internos - e relatar o que você encontrou lá como se fosse descoberto. Eles já sabem disso. É circular, infla a evidência aparente e disfarça o quão pouco um terceiro pode realmente ver. Pesquisar o equivalente público e relatar o que um terceiro encontraria, incluindo nada.

Use acesso exclusivo que o usuário lhe deu, em terceiros. Uma assinatura paga, um conjunto de dados privado ou um banco de dados interno que o usuário explicitamente ofereceu é uma vantagem genuína ao pesquisar concorrentes, fornecedores ou um mercado. Use-o, registre-o como uma fonte como qualquer outra, e observe em Limitações que a descoberta depende de acesso que o leitor pode não ter.

Quando uma entidade acaba não tendo nenhuma pegada pública, essa é a resposta. Listar o que você verificou, dizer que a existência ou escala não pôde ser verificada de fora, e não preencher a lacuna a partir de acesso privilegiado. É a forma "não conseguiu responder" aplicada a uma entidade em vez de toda a pergunta.

O log de busca

Toda recuperação, em cada nível, acrescenta uma linha:

python3 ${CLAUDE_SKILL_DIR}/scripts/sources.py log \
  --tsv "$OUT/$BASE.tsv" \
  --url "https://acme.example/pricing" \
  --kind vendor_pricing \
  --angle "quanto o titular cobra" \
  --via webfetch \
  --date 2026-07-01 \
  --title "Preços" \
  --quote "Plano de equipe: 30 dólares americanos por usuário por mês, faturado anualmente." \
  --text-file /tmp/page.txt

Dois campos carregam o peso, e nenhum pode ser verificado por nada a jusante.

--angle é a subpergunta que esta recuperação estava respondendo. Corroboração é contada em ângulos em vez de fontes porque a própria ramificação do legwork infla as contagens de fontes. Registrar o ângulo honestamente - reutilizar uma string em uma execução silenciosamente destrói a verificação, e nenhum script pode detectar que você fez isso.

--quote é a frase literal que tornou a fonte digna de citação. Registrar uma para cada fonte que você pretende citar, ao lê-la. Cerca de metade de todas as descobertas não carregam número, então para essas a citação é a única evidência que existe, e é a única parte que sobrevive à página mudar. Quando o texto da página está em disco - qualquer coisa aberta com fetch.py, ou um -m scrape com --out - a citação é verificada contra ele e quote_verified: false significa que você citou mal a página.

--from-fetch preenche a url, título, data e texto da página a partir do arquivo auxiliar que esses dois escrevem, então nada precisa ser redigitado:

python3 ${CLAUDE_SKILL_DIR}/scripts/sources.py log --tsv "$OUT/$BASE.tsv" \
  --from-fetch /tmp/legwork/ab12cd34ef56.json \
  --angle "quanto o titular cobra" --kind vendor_pricing \
  --query "site:acme.example pricing" --quote "Plano de equipe: 30 dólares americanos ..."

sources.py log --help cobre o resto: --via transportes (incluindo api, local e mcp), --text-file extração numérica, --kind. Registrar o transporte que você realmente usou - re-buscar uma página através de um diferente para torná-la registrável distorce o rastro em vez de registrá-lo. sources.py kinds imprime quais tipos de fonte são adequados para quais afirmações.

Subagentes

Recuperação é a única fase que vale a pena paralelizar, um subagente por ângulo. Instruí-los a partir de subagent-brief.md, que carrega o modelo literalmente, a forma de retorno exigida e a razão pela qual cada linha está nele. Um subagente tem contexto zero, então tudo que ele precisa vai no resumo.

Três coisas permanecem com você em vez do resumo:

• Combinar o modelo à forma do ângulo. Coleta de trechos e fixação de uma figura conhecida funcionam bem em um modelo barato - passar a substituição explicitamente, nunca deixar um herdar o modelo da sessão por acidente. Mas trabalho de fonte primária em nível profundo, e qualquer coisa que reconstrói uma enumeração, permanece no modelo do orquestrador. Medido: em uma comparação, orquestradores abriram 3, 8 e 32 páginas de fornecedores na faixa de barato a capaz, e apenas o mais fraco preencheu cada célula da grade a partir de um único agregador enquanto relatava sucesso.
• Nunca colar a transcrição de um subagente em sua síntese. Pegar o retorno estruturado, verificar se a string do ângulo voltou inalterada, registrar cada linha, trabalhar a partir do log.
• Escopo, desafio e síntese são julgamento. Eles permanecem no modelo principal.

Scripts

Todos apenas com stdlib. Sem virtualenv. Qualquer python3 >= 3.9.

Script	Propósito
fetch.py "<url>" --find TERMO	Abrir uma página gratuitamente e manter seu texto; sai com código 3 em bloqueio ou shell
platforms.py list | search --on X	Dez fontes nativas de plataforma gratuitas, retornando registros em vez de páginas
sources.py kinds | log | score	Vocabulário de tipos de fonte, o log de busca, pontuação de adequação por tipo de afirmação
sources.py receipt	As contagens de recuperação para a linha de recibo, tiradas do log
sources.py stale --claim-kind K	Quais fontes registradas ficaram desatualizadas, na meia-vida daquele tipo de afirmação
sources.py resume	O que uma execução anterior já buscou, para que uma re-executação o pule
independence.py groups | check	Colapsar fontes em vozes independentes; contar corroboração ciente de ângulo
independence.py portfolio	Concentração de fontes em toda a execução, não dentro de uma descoberta
index.py add | list	O índice de pesquisa - arquivar uma execução, encontrar uma passada, identificar desatualizadas
matrix.py check --report PATH	Integridade de uma matriz de comparação
check.py --report PATH --level LEVEL	A porta de prontidão para envio
finish.py --report PATH --level LEVEL	Porta, varredura de desatualização e arquivamento em uma chamada
`bd_search.py "<consulta	url>" -m MODO --json`

Saída

Resolver a base de saída uma vez no início da execução:

OUTPUT_BASE="${LEGWORK_OUTPUT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)/docs/research}"
BASE="[Topic]_Research_$(date +%Y%m%d)"
OUT="$OUTPUT_BASE/$BASE"; mkdir -p "$OUT"

…

[truncado para tradução]