Jia-Ethan/pavedpath-code

PavedPath Code

PavedPath Code (edição código) ajuda agentes a evitar reinventar soluções para problemas de engenharia de software. Ele pesquisa no GitHub e em evidências de código aberto por caminhos de implementação comprovados, então adapta o padrão mais forte ao código local com alterações mínimas e verificáveis.

Use o GitHub como fonte primária de evidências, não como um depósito de links. O objetivo é definir o problema de código local, encontrar caminhos já percorridos em repositórios públicos, issues, pull requests, discussões, exemplos, notas de lançamento e código-fonte, avaliar a força dessa evidência e, em seguida, traduzir o padrão mais forte em uma pequena correção local, plano de implementação ou plano de verificação.

Esta é a edição focada em código do PavedPath. Não a amplie para o PavedPath de uso geral futuro. Ela é para trabalho de engenharia de software: bugs, erros de runtime, falhas de build/teste/deploy, problemas de dependência, uso de framework ou API, bloqueios de integração, padrões de implementação, seleção de ferramentas de engenharia e adaptação de soluções de código aberto.

Quando Usar

• Erros de runtime, build, teste, deploy, pacote, SDK, API, dependência, framework ou integração.
• Uma implementação de funcionalidade está bloqueada por um caso de borda pouco claro, padrão de uso ausente, comportamento de versão ou contrato de API incerto.
• Um problema local se assemelha a algo que mantedores ou outros usuários de código aberto podem ter resolvido em issues, PRs, exemplos, código, notas de lançamento ou discussões.
• O usuário pergunta se projetos do GitHub ou de código aberto já resolveram um problema de engenharia concreto.
• Exemplos de implementação maduros ou projetos reutilizáveis reduziriam a incerteza para uma capacidade específica.
• A resposta deve comparar repositórios GitHub adequados e explicar como adaptar um caminho comprovado localmente.

Não use o PavedPath Code para edições de texto, refatorações puramente locais onde o código base já dita a resposta, decisões de vida não relacionadas a código, fluxos de trabalho de mídia pessoal, métodos de estudo, decisões de compra do consumidor ou solicitações que explicitamente proíbem pesquisa web/GitHub. Não inspecione repositórios privados a menos que o usuário escopo e autorize explicitamente esse acesso.

Fluxo de Trabalho Padrão

1. Enquadre o problema de código local primeiro. Capture o objetivo, sintoma, assinatura do erro, caminho de reprodução, versões, runtime, nomes de dependência/framework, alterações recentes, restrições e correções tentadas. Se um fato descobrível estiver faltando, inspecione arquivos/logs locais antes de perguntar.
2. Escolha o modo de evidência. Para erros/regressões, pesquise issues, PRs, lançamentos e código primeiro. Para necessidades de capacidade ou ferramenta, pesquise candidatos a repositório primeiro. Para implementação de funcionalidades, use tanto candidatos a repositório quanto evidências de issue/PR/código.
3. Avalie a utilidade do subagente. Antes de uma pesquisa substancial no GitHub, decida se o trabalho condicional do subagente melhoraria a amplitude, qualidade da evidência ou cobertura de revisão. Se não usar subagentes, declare o motivo brevemente ao relatar o caminho de busca.
4. Crie pesquisas direcionadas. Prefira texto de erro exato, nomes de pacote/API, números de versão, framework + sintoma, nomes de arquivo, chaves de configuração, fragmentos de stack trace, nomes de comando com falha ou capacidade + nomes de framework/runtime/API.
5. Encontre projetos GitHub adequados quando relevante. Prefira repositórios com alto ajuste, muitas estrelas, ativos, não arquivados, com licenças claras e exemplos reais. Abaixe o limite de estrelas quando o conjunto de muitas estrelas for muito amplo ou perder o problema exato.
6. Pesquise superfícies de evidência de código aberto. Use issues, PRs, discussões, código, exemplos, notas de lançamento e documentos oficiais do projeto dentro de repositórios de código aberto relevantes. A pesquisa de repositório é necessária quando um projeto em si pode resolver o problema.
7. Classifique primeiro por adequação ao problema, com estrelas como sinal de maturidade. Um repositório com muitas estrelas é um forte candidato para inspeção, mas issues confirmadas pelo mantenedor, PRs mesclados, correções lançadas, exemplos oficiais e código correspondente exato vencem projetos populares adjacentes. Use research-rubric.md quando a classificação for importante.
8. Leia profundamente os projetos e evidências mais fortes. Use extraction-playbook.md para extrair fundamentos do projeto, superfícies reutilizáveis, causa raiz ou padrão de implementação, restrições de versão, riscos, limites de adaptação e etapas de verificação.
9. Traduza para o trabalho local com adaptação mínima. Preserve o fluxo de trabalho comprovado, API, formato de configuração ou arquitetura onde couber. Adapte apenas as partes exigidas pelas interfaces locais do usuário, configuração, modelo de dados/auth, destino de implantação ou idioma/runtime.
10. Verifique antes de reivindicar sucesso. Use testes, builds, comandos de reprodução, requisições reais, logs, verificações de navegador ou inspeção manual apropriados para o problema local.
11. Se a evidência for fraca, diga isso. Não estique correspondências fracas para uma recomendação confiante. Marque a recomendação como baseada em primeiros princípios ou apenas local quando a evidência de código aberto for insuficiente.

Orientação sobre Subagentes / Pesquisa Paralela

Subagentes são auxílios de pesquisa condicionais, não um requisito padrão. O controlador permanece responsável pelo enquadramento do problema, controle de escopo, classificação de evidências, adaptação local e verificação final.

Use subagentes quando pelo menos um destes se aplicar:

• O problema abrange 2+ ecossistemas, frameworks, linguagens, ferramentas, superfícies de implantação ou comunidades GitHub independentes.
• A descoberta de repositório precisa de ampla cobertura de candidatos em múltiplas famílias de consulta.
• Evidências de issue, PR, discussão, código, lançamento e exemplo podem ser divididas de forma limpa por projeto, versão ou superfície de busca.
• Uma recomendação final se beneficia de revisão de evidências independente, revisão de riscos ou revisão de rejeição de candidatos.

Não use subagentes quando qualquer um destes se aplicar:

• A tarefa é um erro estreito com um pacote, repositório, API ou superfície de mantenedor óbvio.
• O contexto do repositório local, logs, configuração ou detalhes de reprodução devem ser entendidos antes que a pesquisa externa possa ser escopada com segurança.
• Limites de taxa do GitHub, limites de autorização, repositórios privados, segredos, dados de produção ou logs sensíveis tornariam a delegação arriscada.
• Subagentes duplicariam principalmente as mesmas pesquisas ou editariam os mesmos arquivos locais.

Ao usar subagentes, o controlador deve:

• Definir a família de consulta de cada subagente, escopo do repositório, superfície de evidência, restrições, escopo de gravação permitido e saída esperada.
• Exigir links diretos, metadados verificados, justificativa de adequação ao problema, notas de risco e motivos explícitos de rejeição.
• Manter subagentes somente leitura, a menos que uma fase de implementação separada tenha um escopo de gravação permitido estreito.
• Mesclar e desduplicar resultados antes da classificação; não conte relatos repetidos da mesma issue, PR, caminho de código ou repositório como evidência independente.
• Verificar diretamente as afirmações mais fortes com gh, leituras de código-fonte, testes, logs, requisições reais ou documentos oficiais antes de finalizar.

GitHub CLI em Primeiro Lugar

Use a CLI do GitHub (gh) como superfície padrão de pesquisa e inspeção. Prefira gh search repos, gh search issues, gh search prs, gh search code, gh repo view, gh issue view, gh pr view e gh api antes de scraping de navegador ou scripts personalizados. Não adicione ou dependa de scripts de busca empacotados para esta skill.

Use estes modelos de comando curtos como ponto de partida, depois ajuste a consulta, repositório, campos e limites para o problema local:

gh search repos "<consulta>" --archived=false --sort stars --order desc --limit 10 --json fullName,url,description,stargazersCount,forksCount,language,license,pushedAt,isArchived,openIssuesCount
gh search issues "<consulta>" --repo proprietario/repo --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
gh search prs "<consulta>" --repo proprietario/repo --merged --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
gh search code "<consulta>" --repo proprietario/repo --limit 10 --json path,url,repository,sha
gh repo view proprietario/repo --json nameWithOwner,url,description,stargazerCount,forkCount,licenseInfo,primaryLanguage,pushedAt,repositoryTopics,homepageUrl
gh api -X GET search/repositories -f q='<consulta> archived:false' -f sort=stars -f order=desc

Execute gh auth status apenas quando um comando falhar com 403, 429, um erro de autorização de repositório privado ou uma mensagem explícita de gh não autenticado. Se o GitHub retornar 403/429, inspecione o contexto de limite de taxa ou autorização emitido antes de tentar novamente, reduzir a amplitude ou trocar de endpoint. Não cole ou persista tokens, cookies, conteúdos de repositórios privados ou credenciais em prompts, arquivos, logs ou memória.

Estratégia de Busca

• Comece estreito: string de erro exata, classe de exceção, saída de CLI, nome de pacote + método, chave de configuração ou fragmento de stack trace.
• Adicione restrições: versão do pacote/framework, linguagem, plataforma, destino de implantação, bundler, banco de dados, provedor de autenticação ou runtime.
• Pesquise superfícies nesta ordem quando relevante: issues/PRs/discussões, correções mescladas, notas de lançamento/changelog, exemplos/modelos, código-fonte, depois candidatos em nível de repositório.
• Para bloqueadores de implementação sem erro, pesquise pela capacidade desejada mais nomes de framework/runtime/API.
• Para necessidades de dados de plataforma pública, como tendências, listas populares, pesquisa por tópico ou métricas de engajamento, não comece com scraping visual de navegador. Primeiro procure por endpoints públicos reutilizáveis, rastreadores de código aberto, conjuntos de dados arquivados e evidências de campo de API; em seguida, verifique a fonte escolhida com uma solicitação real mínima e separe claramente dados de listas populares anônimas de dados de pesquisa/tópico logados.
• Para descoberta de projetos reutilizáveis, pesquise repositórios classificados por Estrelas, depois leia profundamente apenas candidatos que correspondam ao problema local. Registre Estrelas, forks, linguagem, licença, atividade e conteúdo básico.
• Rebaixe correspondências que são antigas, com versão incompatível, arquivadas, não resolvidas, especulativas ou baseadas apenas em palpites de usuários.
• Use Estrelas/forks apenas como contexto de maturidade de suporte e desempatadores entre repositórios com ajuste semelhante. Eles não substituem adequação ao problema, evidência confirmada pelo mantenedor, PRs mesclados, notas de lançamento, exemplos oficiais ou código reproduzível.
• Para segurança, autenticação, pagamentos, infraestrutura ou operações de produção, verifique as descobertas de código aberto contra documentos ou repositórios oficiais atuais quando os fatos podem ter mudado.

Padrão de Evidência

Para cada item de evidência sério, identifique:

• correspondência exata: mesmo erro, comportamento, API, versão, ambiente ou fluxo de trabalho;
• força da evidência: confirmação do mantenedor, PR mesclado, correção lançada, exemplo de código reproduzível, fixture de teste ou relatos independentes repetidos;
• aplicabilidade: quais condições devem corresponder localmente para a solução se aplicar;
• valor de implementação: patch, configuração, uso de API, versão de dependência, fluxo de trabalho, teste ou padrão operacional que vale a pena adaptar;
• fundamentos do projeto quando um repositório é candidato: nome, URL, Estrelas, forks, linguagem, licença, atividade, conteúdo básico, justificativa de ajuste e custo de adaptação;
• risco: versão desatualizada, issue não resolvida, solução alternativa insegura, preocupação com licença, impacto em segurança/privacidade, incompatibilidade de implantação ou alteração muito ampla.

Contrato de Saída

Quando o PavedPath Code afetar materialmente a resposta, inclua:

• perfil do problema local: objetivo, sintoma/erro, versões/ambiente e restrições locais;
• caminho de busca: consultas ou métodos de descoberta usados, superfícies GitHub/código aberto pesquisadas e se subagentes foram usados ou ignorados;
• rastro do subagente quando subagentes foram usados: escopo de cada subagente, superfícies de evidência, principais descobertas, candidatos rejeitados, resultados de desduplicação e quais afirmações o controlador verificou diretamente;
• candidatos a projeto quando um projeto GitHub em si é relevante: link do repositório, Estrelas, forks, linguagem, licença, atividade, conteúdo básico, justificativa de correspondência e como pode ser usado localmente;
• evidência chave: links para issues, PRs, código, exemplos, lançamentos ou repositórios, com justificativa de correspondência;
• solução recomendada: o que reutilizar diretamente, o que adaptar localmente, o que evitar copiar e por que se encaixa;
• opções rejeitadas ou arriscadas: por que não se aplicam ou precisam de cautela;
• padrão de verificação: teste, build, comando de reprodução, requisição real ou verificação manual necessária para confirmar a correção;
• rótulo de confiança quando a evidência é fraca ou nenhuma solução forte de código aberto foi encontrada.

Quando soluções em nível de repositório forem relevantes, inclua uma tabela compacta de projetos. Para correções puramente de issue/PR/código, a tabela é opcional, mas inclua contexto do repositório se isso afetar confiança ou aplicabilidade.

Não responda apenas com links, Estrelas ou classificações de popularidade. Não escreva "padrão comum do GitHub" sem evidência vinculada. Não deixe exemplos externos substituírem restrições locais.

Para pesquisa de candidatos a site, SaaS, landing page, tema ou template de frontend, inclua tanto a URL do repositório quanto a URL de pré-visualização/demo ao vivo para cada candidato sério. Se nenhuma pré-visualização estiver disponível ou verificada, declare isso explicitamente e rebaixe o candidato.

Nota de Migração

github-solution-research foi renomeado para PavedPath Code. O comportamento anterior é preservado; esta é uma atualização de nome e posicionamento para a edição focada em código do PavedPath. Novas instalações devem usar o nome de skill pavedpath-code e o diretório ativo de skill/instrução do runtime do agente alvo.

Limites de Segurança

• Prefira ler padrões e reutilizar interfaces públicas existentes em vez de copiar código. Se a reutilização de código for necessária, verifique a licença e mantenha os riscos de atribuição/obrigação visíveis.
• Evite grandes reescritas de uma solução de código aberto existente. Mantenha seu fluxo comprovado intacto e faça apenas as adaptações locais necessárias para o problema do usuário.
• Evite grandes trechos literais de repositórios, READMEs, issues, PRs ou documentação.
• Não salve tokens do GitHub, cookies, conteúdos de repositórios privados ou credenciais em saídas, logs, skills ou memória.
• Não passe tokens, cookies, conteúdos de repositórios privados, logs sensíveis, segredos, dados de produção ou credenciais para subagentes.
• Se o acesso à rede não estiver disponível, declare que a pesquisa de código aberto não pôde ser realizada e marque a recomendação como apenas local.