Shambhavagrawal/rotless-github-research

Pesquisa no GitHub

Encontre todos os repositórios relevantes e componentes extraíveis para o tópico ou pergunta do usuário: $ARGUMENTS (Claude Code preenche isso; em outros agentes é a solicitação do usuário)

A busca literal por palavras-chave falha em tópicos de nicho: desenvolvedores nomeiam repositórios com base na coisa que eles tocam (um site, uma API, uma organização, uma biblioteca), não no conceito. Busque pelos artefatos que qualquer implementação deve conter, de várias direções (código, repositórios, commits, issues, outros hosts, a web), verifique cada resultado e decomponha candidatos em peças reutilizáveis para integrar em nossa solução alvo.

A família rotless

Parte do rotless, e totalmente utilizável sozinha. Quando a pesquisa é estado da arte para uma skill, o chamador nomeia um arquivo e sua estrutura (prior-art.md, definido por rotless-skill-modernizer): escreva o relatório ali naquela estrutura. Chamadores: rotless-skill-creator (passo 0, antes de construir), rotless-skill-modernizer (fix para uma ferramenta substituída, refresh para todo o panorama) e rotless-skill-refiner (uma lição de "forma melhor" é verificada contra o que existe antes de ser adotada).

Caixa de ferramentas

Os auxiliares vivem na pasta scripts/ desta skill. Defina S para o caminho absoluto dessa pasta uma vez, a partir do diretório base desta skill (a pasta que contém este SKILL.md; Claude Code imprime como "Base directory for this skill: …" quando a skill carrega), e sempre chame os auxiliares através de $S (o diretório de trabalho é o projeto do usuário); -h lista as flags; python3, ou python no Windows. Endpoints fora do GitHub estão em references/sources.md (mesma pasta). Prefira um shell POSIX (bash; Git Bash no Windows) ao PowerShell (escapamento de -, !, jq). Exemplos sarkari/UPSC são ilustrativos apenas.

Ferramenta	O que busca	Melhor para
grepapp.py (= ferramenta searchGitHub se o MCP grep estiver instalado)	conteúdo de arquivos, ~1M repositórios populares, regex, sem autenticação	domínios fixos, linhas de importação, chaves de configuração
gh api -X GET search/code -f q='…'	conteúdo de arquivos, índice legado do GitHub (mais repositórios, sem regex)	segunda fonte de código; assinaturas path:/filename:
ghsweep.py	nome/descrição/readme/tópicos do repositório, muitas consultas, deduplicado	amplitude; contagens totais, tópicos comuns, tags [noise?]
gh search commits …	mensagens de commit	repositórios cujo nome/README não dizem nada
gh search issues … --include-prs	texto de issues/PRs	repositórios + pontos de dor reais (precisa de frases específicas; palavras genéricas se perdem em issues de bots)
ghverify.py	lote GraphQL, 25 repositórios/chamada	existência, renomes, atividade real, saúde, evidências, bandeiras de aviso
gh repo read-dir / read-file, gh api …/contents	arquivos de um repositório, sem clone	confirmar código real
srcsweep.py	21 fontes não-GitHub em paralelo: npm, crates, Packagist, Hex, NuGet, Maven, RubyGems, Hackage, Docker Hub, ArtifactHub, AUR, Open VSX, GitLab, Codeberg, MCP Registry, skills.sh, Hugging Face (modelos/datasets/spaces/papers, com o repositório de código que um paper linka), Hacker News	estado da arte fora do GitHub; termina com um registro de fontes pesquisadas / não alcançadas; --repos canaliza repositórios do GitHub para ghverify.py -
references/sources.md	notas de endpoint + fontes sem API de busca (PyPI, Homebrew, pkg.go.dev, Product Hunt, Reddit)	acompanhamentos manuais

Regras importantes do gh search (testadas; ignorá-las retorna silenciosamente [] ou resultados errados)

• Aspas: gh search <kind> "duas palavras" = frase exata. Para AND passe palavras sem aspas; OR funciona sem aspas.
• Para qualquer coisa não trivial use a API bruta (sintaxe completa + total_count): gh api -X GET search/{repositories|code|commits|issues} -f q='<consulta>' -f per_page=100 --cache 1h
• Todas as palavras devem corresponder na busca de repositórios, então mantenha cada consulta com 2–3 palavras e varie a redação em vez de empilhar termos em uma consulta. Se uma varredura retornar < 5 repositórios, encurte as consultas.
• Exclusão: palavras com NOT palavra; qualificadores com -qualificador:valor. -palavra retorna 0. No gh search coloque exclusões após --.
• Busca de código via API = mecanismo legado: sem regex; OR/NOT, path:, filename:, extension:, language: funcionam. Apenas branch padrão; pula arquivos grandes. Use grep.app para regex.
• Limite de resultado 1000 por consulta. Fatia grandes conjuntos de resultados: created:A..B, pushed:>DATA, faixas de estrelas stars:0..24, stars:25..99, stars:100..499 (também revela gems de baixa visibilidade), language:.
• Limites de taxa: busca 30/min; busca de código 10/min (gh skill search compartilha); GraphQL 5000 pts/hr. Verifique: gh api rate_limit --jq '.resources | {search: .search.remaining, code: .code_search.remaining, graphql: .graphql.remaining}'. Use --cache 1h em chamadas repetidas; quando a busca de código estiver exausta, troque de vetor em vez de esperar.
• Privacidade: busca autenticada retorna repositórios privados que a conta pode ver. Nunca os reporte: adicione select(.repository.private == false) (código) / select(.private == false) (repositórios) ao jq; ghsweep.py os filtra. Nunca coloque nomes privados/internos do usuário nas consultas de busca.
• gh repo read-file / read-dir / gh discussion / gh skill precisam de um gh recente (testado 2.103). Se mais antigo, use as alternativas gh api no Passo 3 ou sugira winget upgrade GitHub.cli / brew upgrade gh.

Passo 0 — Briefing (um bloco curto, sem ida e volta a menos que genuinamente ambíguo)

Escreva: Objetivo · Decomposição da Solução Alvo (subproblemas modulares: ex. autenticação/sessão, scraper/parser, normalização/esquema, armazenamento, API/interface — para identificar o que pode ser aproveitado de onde) · Obrigatórios · Desejáveis · Anti-padrões (ex. wrapper fino, abandonado, precisa de API paga, apenas GPU) · Restrições (linguagem, offline…: são verificações de passa/não-passa, não termos de busca) · Corte como uma data absoluta ("recente" → pushed:>2025-10-24) · Esforço: passagem rápida (escolha barata e reversível: ~10 consultas, top 5) ou método completo (padrão para estado da arte / construir-vs-comprar / mesclar). Se a solicitação for "alternativa a X / como X / clone de X", resolva X para seu repositório primeiro e semeie a partir dele (seus tópicos, README, dependentes). Verifique localmente primeiro (grátis, 10 segundos): o que já está instalado pode responder: as pastas de skills que seu agente carrega (nível de projeto e usuário: .agents/skills/, .claude/skills/, ~/.codex/skills/…), sua lista de servidores MCP (ex. claude mcp list), gh extension list. Reporte um resultado antes de pesquisar o mundo.

Passo 1 — Impressão digital do tópico

Escreva 15–30 termos de busca concretos:

1. Pontos de contato — domínios, URLs, endpoints de API, hostnames, caminhos RSS, IDs de aplicativos que qualquer implementação deve atingir.
2. Assinaturas de código — linhas de importação, nomes de classes/funções de SDK, variáveis de ambiente, chaves de configuração, seletores CSS, constantes distintivas.
3. Vocabulário de vários pontos de vista — construtor, usuário final, acadêmico, infraestrutura, e a disciplina vizinha que provavelmente resolveu primeiro; termos regionais/não ingleses, abreviações, erros de ortografia. Palavras ambíguas precisam de um termo companheiro (agent + llm, não agent sozinho).
4. Formas — bot, scraper, API, CLI, biblioteca, extensão, servidor MCP, skill de agente, dataset, modelo, GitHub Action; e suas assinaturas de arquivo (.github/workflows cron, manifest.json, SKILL.md, .claude-plugin/marketplace.json). Skills de agente e plugins frequentemente vivem dentro de repositórios maiores (um skills/x/SKILL.md em um monorepo de 80k★), invisíveis para busca de repositório: encontre-os com busca de código filename:SKILL.md "<frase de sua descrição>" (ruidoso: centenas a milhares de resultados, então use 2 frases distintivas e escaneie 2–3 páginas) e skills.sh (srcsweep.py --sources skills; semântico, funciona melhor no nome da skill do que em seu propósito). A recuperação de skills é o vetor mais fraco: se uma skill âncora nunca surgir, busque seu nome diretamente e diga isso na nota de cobertura.
5. Âncoras — os 3–10 projetos/produtos conhecidos que você esperaria que qualquer boa resposta incluísse. Usados no Passo 2 como uma verificação de recall.
6. Parágrafo ideal de README — duas frases descrevendo o repositório perfeito, escritas da maneira que seu autor escreveria; explore-o em busca de termos de busca.

Passo 2 — Busque em todos os vetores

Execute vetores em paralelo. Registre quais consultas encontraram cada repositório (found_by: mais consultas = relevância mais forte).

A. Busca de código (sinal mais forte). Muitas consultas estreitas, uma por ponto de contato/assinatura:

S="<diretório base desta skill>/scripts"     # ex. S="$HOME/.agents/skills/rotless-github-research/scripts" (ou ~/.claude/skills/… no Claude Code)
python "$S/grepapp.py" "sarkariresult.com" --repos-only
python "$S/grepapp.py" "(sarkariresult|freejobalert)\.com" --regex --lang Python --lang JavaScript --repos-only
python "$S/grepapp.py" "upsc.gov.in" --path .github/workflows/ --repos-only          # bots agendados
gh api -X GET search/code -f q='sarkariresult OR freejobalert language:python' -f per_page=100 \
  --jq '"total \(.total_count)", (.items[] | select(.repository.private == false) | "\(.repository.full_name)\t\(.path)")'

grep.app retorna ~10 arquivos/consulta e 504s em regex amplo: ancore em um literal raro, adicione --lang/--path. Descarte ruído: datasets de URLs rastreadas, listas de adblock, monorepos onde o termo aparece uma vez.

B. Busca de repositório (amplitude + tamanho do panorama).

python "$S/ghsweep.py" --pushed ">2024-01-01" --order hits "sarkari OR naukri NOT resume" "freejobalert" "topic:government-jobs"
python "$S/ghsweep.py" --sort stars "topic:sarkari-result"      # carros-chefe cujas descrições pulam palavras genéricas
python "$S/ghsweep.py" --sort updated "sarkari scraper"         # trabalho recente enterrado por melhor correspondência
python "$S/ghsweep.py" --must "scrap|crawl|alert|job" --exclude "resume|linkedin" "sarkari OR naukri"   # filtro de relevância; homônimos ("prior art" = patentes) inundam resultados
gh api -X GET search/topics -f q=sarkari --jq '.items[].name'      # descobrir slugs de tópicos

ghsweep.py imprime contagens totais (quão movimentado o espaço está), tópicos mais comuns (→ próximas consultas; também tente pares de tópicos compartilhados por ≥2 melhores resultados: topic:a topic:b), e tags [noise?] (tutorial/template/demo/dotfiles/awesome: rebaixe, não descarte automaticamente). Remova --pushed para estado da arte independentemente da idade.

C. Busca de commits: gh search commits sarkariresult --limit 50 --json repository,commit --jq '.[] | "\(.repository.fullName)\t\(.commit.message | split("\n")[0])"'

D. Busca de issues/PRs: gh search issues "freejobalert" --include-prs --limit 50 --json repository,title,url (apenas frases específicas).

E. Bola de neve a partir dos melhores resultados (top 3–5):

• Siga a dependência encapsulada: se um resultado "encapsula", "é construído sobre" ou "usa" X, pesquise X também: geralmente é o verdadeiro titular. Lugar mais comum de parar cedo demais.
• Listas awesome: python "$S/ghsweep.py" --sort stars "awesome <kw> in:name"; pegue listas awesome-* com ≥200★, extraia seus links de repositório (gh repo read-file README.md --repo o/awesome-x | grep -oE 'github\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+' | sort -u) e canalize para ghverify.py -. Estar listado é um sinal suave de qualidade.
• Repositórios similares: tópicos + linguagem de um resultado top → topic:a topic:b language:x, prefira faixa de estrelas similar.
• Seções README "Alternativas / Similares / Inspirado por / Créditos"; strings de código distintivas → grep.app (encontra cópias e portes); outros repositórios do autor (gh repo list <owner> --limit 100); forks com trabalho próprio (gh api "repos/o/r/forks?per_page=100" --jq '.[] | select(.pushed_at > .created_at) | .full_name'); página de dependentes da biblioteca via sua ferramenta de busca web ou curl (github.com/o/r/network/dependents).

F. Fora do GitHub: um comando, várias redações (1–3 palavras cada; registros E os termos):

python "$S/srcsweep.py" "repository discovery" --limit 4        # 21 fontes, ~10s, termina com um registro de pesquisado / NÃO ALCANÇADO
python "$S/srcsweep.py" "sarkari" --repos | python "$S/ghverify.py" -   # repositórios do GitHub linkados dos resultados, verificados

Depois use busca web para o que não tem API de busca (PyPI site:pypi.org, Homebrew, pkg.go.dev, Product Hunt, Reddit, blogs, awesome <topic>). Para pesquisa de estado da arte/concorrência também liste produtos comerciais notáveis. Resultados não-GitHub (GitLab, Codeberg, apenas registro) não podem passar por ghverify.py: verifique-os manualmente e marque evidência como Documentada/Metadados.

Parada e recall. Pare quando novas consultas retornarem principalmente repositórios conhecidos, mas três consultas retornando o mesmo repositório é um mínimo local, não cobertura. Verifique as âncoras do Passo 1: qualquer âncora não revelada por suas buscas significa uma lacuna de vocabulário: descubra quais palavras ela usa e busque-as. Zero resultados significa "esta rota não pode ver", não "não existe": reformule ou mude de rota uma vez antes de concluir.

Passo 3 — Verifique e avalie

Todo candidato passa por ghverify.py (nomes inventados mostram como NÃO ENCONTRADO; renomeados mostram o nome atual):

python "$S/ghverify.py" owner/repo https://github.com/o2/r2 ...      # ou: ... | python "$S/ghverify.py" -

Leia suas colunas: último commit substantivo (ignora bump/chore/deps/merge/typo/docs) não pushedAt; % de resolução de issues; PRs mesclados; pessoas; org/usuário; releases/ano; evidências (testes, ci, manifest, security.md; NONE = apenas README, verifique arduamente); bandeiras !velocity (>100★/dia: viral ou comprado, precisa contexto), !lowfork (≥1000★, forks/stars < 0.005), new (<14 dias), stale Ny (nenhum commit substantivo por 2+ anos: sinalizado, nunca rebaixado: uma ferramenta abandonada ainda prova que a ideia foi construída), noise?.

Depois confirme código real para cada repositório que você reportará (READMEs mentem nos dois sentidos). Fixe evidência a um commit:

sha=$(gh api repos/o/r/commits/HEAD --jq .sha)
gh repo read-dir src --repo o/r --ref $sha                    # JSON: --json name,type --jq '.entries[]'
gh repo read-file path/to/main.py --repo o/r --ref $sha       # alternativa: gh api "repos/o/r/contents/PATH?ref=$sha" -H "Accept: application/vnd.github.raw"
gh api "repos/o/r/git/trees/$sha?recursive=1" --jq '"\(.tree|length) files", (.tree[:80][] | .path)'

Cite links permanentes https://github.com/o/r/blob/<sha>/<path>#L10-L40, não links de branch.

• Ajuste e Extraibilidade: forte / parcial / fraco / fora_do_alvo, listando...