dji-sq/DSH-skill

GitHub Extract

O problema que este skill resolve

O usuário envia um link do GitHub. Na maioria das vezes, ele não quer uma pilha de arquivos — quer entender três coisas:

1. Para que serve este projeto?
2. O que esta alteração resolve?
3. Por que esta abordagem foi escolhida?

Arquivos, diffs e metadados são apenas evidências. Entregar evidências como se fossem a conclusão não é extrair — é como dar uma pilha de tabelas para alguém que nunca ouviu falar do repositório.

Critério de conclusão (em uma frase): Uma pessoa que nunca viu este repositório antes, ao ler os primeiros 300 caracteres, consegue reexplicar com suas próprias palavras "que problema ele resolve, o que mudou desta vez e por que mudou assim". Se não conseguir, a extração não está completa.

Passo 0: Leia o "projeto" antes de ler a "página"

Antes de pegar um PR ou issue, entenda o recipiente. Pular esta etapa faz com que todo o resto fique solto, por mais completo que seja.

Pergunta a responder	Onde ler
O que é este projeto	description do repositório, topics, início do README
Que lacuna ele preenche / o que substitui	Coluna "Por quê" de cada pacote no README
Quem usa e em que cenário	Seções Install / Usage / Develop do README
Onde esta alteração se encaixa	Branch base do PR, papel do pacote alterado na lista

Monorepos / coleções de plugins são obrigatórios: liste primeiro uma tabela de "nome do pacote → responsabilidade em uma frase", senão o leitor não conseguirá localizar a alteração. Se o README usar jargão técnico (ex.: "lifecycle hooks", "ctx.web seam"), traduza para linguagem simples antes de entrar no texto principal.

Passo 1: Identifique o tipo de URL

Formato da URL	Tipo	Fonte principal de dados
github.com/{o}/{r}	repositório	/readme + git/trees?recursive=1
…/issues/{n}	issue	issues/{n}
…/pull/{n}	PR	pulls/{n} + pulls/{n}/files + pull/{n}.diff
…/commit/{sha}	commit	commits/{sha}
…/blob/{ref}/{path}	arquivo	contents/{path}?ref={ref} (base64)

#1 é um fragmento, não parte do caminho. Issues e PRs compartilham o mesmo espaço de numeração: se /issues/1 redireciona (302) para /pull/1, então é um PR e isso deve ser informado claramente.

Passo 2: Use a API para obter o conteúdo completo, não lute com HTML

• O HTML da página só fornece a barra de navegação e o corpo truncado — para o texto completo, use api.github.com.
• O patch use patch-diff.githubusercontent.com/raw/{o}/{r}/pull/{n}.diff (github.com/.../pull/n.diff redireciona entre domínios, então conecte diretamente ao endereço final).
• raw.githubusercontent.com frequentemente não funciona; prefira decodificar o base64 do contents localmente.
• Se git / curl local apresentar erro TLS SEC_E_NO_CREDENTIALS, não tente consertar o shell — use o web_fetch do harness. Não trate "falha ao clonar" como impedimento da tarefa.

Passo 3: Validação cruzada

additions/deletions/changed_files ↔ lista de files ↔ hunks do .diff; SHA do head do PR ↔ ref do patch; merged não depende apenas de state=closed. Se houver inconsistência, investigue mais (provavelmente paginação ou patch desatualizado). Não produza um artefato contraditório.

Passo 4: Organize a saída de forma legível

A ordem é obrigatória: explicação primeiro, evidências depois. O leitor não deve passar por 200 linhas de tabela antes de entender do que se trata.

1. O que é (150–300 caracteres, linguagem simples) — razão de existir do projeto, lacuna que preenche. Termos técnicos devem ser explicados na primeira aparição: hookkit = transforma "escrever plugin para usar lifecycle hooks" em "escrever um YAML".
2. O que esta alteração resolve — escreva no formato "antes era assim → agora é assim". Não substitua por uma lista de arquivos.
3. Por que esta abordagem — extraia da descrição do PR / mensagem do commit as escolhas e relações de causa e efeito (por que não usar push trigger, por que tratar o registry como estado).
4. Lista de alterações — tabela: arquivo / status / linhas adicionadas e removidas / função em uma frase.
5. Texto original — descrição do PR, mensagem do commit, citados na íntegra, sem reescrita.
6. Conteúdo completo — texto integral de cada arquivo, sem "... o restante foi omitido".
7. Práticas transferíveis — apenas o que o leitor pode realmente usar depois.
8. Verificação e cobertura — coloque no final como apêndice: resultado de git apply --check, comparação de SHA de blob, o que não foi capturado.

Regras de escrita

• Conclusão primeiro: a primeira frase de cada parágrafo é a conclusão; o resto é a justificativa.
• Tabelas não substituem explicação. Tudo que é "o que é" ou "por que" deve ser escrito em frases completas.
• Não use nomes de arquivo como descrição da funcionalidade: "alterou publish.yml" ❌; "adicionou workflow de publicação manual, que publica apenas ao clicar no botão, por padrão só simula" ✅.
• Números devem ter origem rastreável, mas não coloque logs de verificação no início.
• Escreva no mesmo idioma do usuário.
• Antipadrões: pilha de tabelas, diff arquivo por arquivo como texto principal, começar com metadados, termos sem explicação.

Passo 5: Auto-verificação

• Ao olhar apenas os primeiros 300 caracteres (excluindo título e tabelas), consigo responder "para que serve / o que mudou / por que mudou assim"? Se não, reescreva.
• Há termos não explicados?
• Estou tratando "os arquivos A, B, C sofreram alterações" como a explicação da mudança?
• O patch passou em git apply --check? Se não executou, declare explicitamente "não verificado".

Modos de falha

Sintoma	Causa	Ação
Texto principal cortado no meio	Capturou HTML	Use a API
404 no raw.githubusercontent	Whitelist de rede	Decodifique base64 do contents
403 rate limit	Loop não autenticado	Lote, desacelere, reporte a lacuna honestamente
cross-origin redirect not followed	Redirecionamento .diff	Conecte diretamente a patch-diff…
Número de arquivos difere de changed_files	Paginação	Reobtenha com ?per_page=100
Leitor diz "não entendi"	Só deu evidências, sem explicação	Volte ao Passo 4, seções 1–3 e reescreva

Limites

Prioridade: instrução explícita do usuário > estas restrições > padrão conservador.

Por padrão, extraia apenas conteúdo — não clone, não compile, não instale, não execute testes. Repositórios privados exigem token do usuário; não invente. Repositórios arquivados devem ser informados — o conteúdo ainda pode ser extraído, mas o status afeta a interpretação.

Situações em que é obrigatório parar e perguntar (não agir por conta própria)

• O usuário diz "instale / execute", mas o alvo é um repositório de outra pessoa ou algo que afeta o ambiente global: primeiro confirme o escopo e o plano de rollback.
• A instrução é ambígua ("processe este repositório"): ofereça um plano padrão + uma confirmação; não adivinhe.
• A ação é irreversível ou altera o ambiente do usuário (pnpm install, pacote global, modificar profile, criar PR, push, deletar arquivos): sempre pergunte antes.
• Requer credenciais (repositório privado, token, chave SSH): pergunte uma vez; se obtiver, use; se não obtiver, produza apenas a parte publicamente verificável e anote o que está faltando.

Situações em que pode agir sem perguntar

• O repositório é do próprio usuário e ele explicitamente disse "pode mexer / instalar direto / não precisa perguntar";
• Ou a ação é executada em um diretório temporário, sem tocar no repositório original nem no estado global (neste caso, a permissão vale apenas para "escrever", não para "executar código não confiável").

Ao agir sem perguntar, adicione ao final do artefato uma frase "Conforme sua autorização, executei X" para tornar a ação visível e reversível.