adamjali/explain

<essential_principles>

Como Esta Skill Funciona

Dois modos, roteados automaticamente pelo assunto (veja tabela de roteamento):

• Modo A — Repositório / conceito / docs (caminho barato): pesquisa → clonar (se for repositório) → explorar → sintetizar → gerar saída. Agentes paralelos soltos são suficientes.
• Modo B — Produto web ao vivo / concorrente / produto de dados / algoritmo / cenário (a verdadeira análise completa): reconhecimento → confirmar → reconhecimento profundo orquestrado por Workflow → captura com navegador real → engenharia reversa para código validado → sintetizar. Leia @references/competitor-teardown.md e siga-o.

Roteamento por tipo de assunto

Assunto	Sinal	Modo	Espinha Dorsal
Repositório GitHub	github.com	A	Clonar + agentes Explore
Conceito / tecnologia	sem URL	A	Agentes de pesquisa
Docs / site estático	URL, informacional	A	Pesquisador + WebFetch
Produto ao vivo / app / SaaS / concorrente	URL é um produto; "concorrente/análise/vs nós/como eles fazem"	B	Navegador + Workflow + schema por assunto
Calculadora / estimador / previsor / precificador / ranking	uma fórmula/algoritmo a ser descoberto	B	Grade de sondagem ao vivo → implementação de referência executável → validar
Cenário completo	"encontrar todos os outros / todo mundo neste espaço"	B	Descoberta de namespace → análise do conjunto SIM

Desempate: se uma URL for AMBAS um produto e tiver documentação, o padrão é B — a passagem de reconhecimento é barata e rebaixa para A se não houver nada a ser analisado.

Regras de Execução

1. Ferramenta certa para escala: Modo A = chamadas paralelas de Task/Agent. Modo B = ferramenta Workflow (pipelines, schemas de saída estruturada, retomada) quando houver 3+ assuntos ou trabalho multifásico.
2. Fundamente, depois confirme: Modo B faz uma passagem de reconhecimento barata + uma porta de confirmação (escopo + limite de reconhecimento + navegador) antes do mergulho caro — a menos que o usuário já tenha dito "análise completa / vá fundo / tudo".
3. Engenharia reversa para código executável e validado para qualquer calculadora/algoritmo; compare com a verdade fundamental autoritativa, não com a afirmação do próprio concorrente.
4. Visual pesado: cada conceito principal recebe um diagrama ou tabela.
5. Saída dupla: exiba o resumo executivo + índice de arquivos na conversa; salve o conjunto completo de documentos em ~/.claude/explanations/<data>_<slug>/.
6. Resiliente: pesquisa pesada do Modo B roda como Workflow em segundo plano; persista artefatos incrementalmente; retome (resumeFromRunId) em caso de interrupção.
7. Limpeza: ofereça-se para excluir repositórios clonados / arquivos salvos quando terminar. </essential_principles>

<scope_boundary>

Limite de reconhecimento do Modo B (crítico — leia antes de qualquer sondagem ao vivo)

Reconhecimento competitivo é legal e normal em superfícies PÚBLICAS. Regras completas em @references/competitor-teardown.md. Os invariantes:

• PERMITIDO: páginas/recursos públicos, OpenAPI /docs públicos, bundles JS públicos, uma grade modesta e educada (~15-40, baixa taxa) de requisições normais de nível de usuário a endpoints públicos para derivar uma fórmula, fingerprinting de cabeçalho, WHOIS/DNS.
• NUNCA: quebrar CAPTCHA/desafios de bot, burlar autenticação, coletar em massa conjuntos de dados inteiros (apenas amostrar), testar estresse, ou invocar endpoints destrutivos/admin/mutantes (DOCUMENTE-os, não os chame). Observe exposições; nunca as explore. Nunca envie dados reais do usuário em um formulário de concorrente. Se não tiver certeza, não faça — e diga o porquê. </scope_boundary>

<intake_gate>

<no_context_handler> SE $ARGUMENTOS estiver vazio: → Use AskUserQuestion:

• header: "Explicar"
• question: "O que você gostaria que eu explicasse?"
• options:
  • "Repositório GitHub" - Analisar uma base de código do GitHub
  • "Site ou documentação" - Entender um site, documentação ou API
  • "Concorrente / produto ao vivo / cenário" - Analisar um produto ao vivo, fazer engenharia reversa de uma calculadora ou mapear um espaço competitivo completo (Modo B)
  • "Conceito ou tecnologia" - Explicar um conceito, framework ou ferramenta

Em seguida, prossiga para context_analysis. </no_context_handler>

<context_analysis> Analise $ARGUMENTOS para extrair:

• Tipo: repositório GitHub, site, conceito ou outro
• URL/Tópico: a coisa específica a ser explicada
• Objetivo implícito: Aprender a usar? Avaliar? Entender arquitetura? Contribuir?

Detecte o tipo automaticamente:

• Contém github.com → repositório GitHub (Modo A)
• Sinais de Modo B → "concorrente", "análise", "engenharia reversa", "vs nós", "como eles fazem", "encontrar todos os outros", ou uma URL que é um produto/app/calculadora → Modo B
• Contém http (informacional/docs) → Site (Modo A)
• Caso contrário → Conceito (Modo A) </context_analysis>

<initial_questions> Use AskUserQuestion apenas para lacunas genuínas (máximo 2-3 perguntas):

Objetivo (se não estiver claro):

• "Qual é o seu objetivo?" com opções:
  • "Entender como funciona" - Arquitetura, fluxo, implementação
  • "Avaliar para adoção" - Prós/contras, alternativas, adequação ao meu caso de uso
  • "Aprender a usar" - Configuração, API, primeiros passos
  • "Aprender a contribuir" - Estrutura da base de código, workflow de desenvolvimento

Foco (se o tópico for amplo):

• "Algum foco específico?" com opções:
  • "Tudo" - Análise completa e abrangente
  • "Apenas arquitetura" - Estrutura e padrões de alto nível
  • "Funcionalidade específica" - Um aspecto particular (especifique)

Contexto (se útil):

• "Seu nível técnico?" com opções:
  • "Não técnico" - Explique a partir dos primeiros princípios com analogias
  • "Técnico, mas novo neste domínio" - Pule o básico, foque nos específicos
  • "Especialista" - Técnico profundo, assuma conhecimento </initial_questions>

<decision_gate> Após as respostas, use AskUserQuestion (Modo A):

• question: "Pronto para começar o mergulho profundo?"
• options:
  • "Sim, vamos" - Iniciar análise multifásica
  • "Mais perguntas primeiro" - Tenho esclarecimentos
  • "Deixe-me adicionar contexto" - Quero adicionar detalhes

Modo B substitui esta porta pela B2 (snapshot + escopo + limite de reconhecimento + ir fundo/navegador) — não pergunte ambas; B2 é a única porta autoritativa para análises. </decision_gate>

</intake_gate>

Seleção de Modo

Execute <intake_gate>, depois roteie pela tabela de tipo de assunto. Modo B (produto ao vivo / concorrente / produto de dados / calculadora / cenário) → carregue @references/competitor-teardown.md e siga seu fluxo de reconhecimento → confirmar → profundo → sintetizar (esqueleto abaixo). Modo A (repositório / conceito / docs) → Fases 1-7 abaixo.

Modo B — Análise de produto ao vivo / concorrente / produto de dados

Manual completo em references/competitor-teardown.md. Esqueleto:

• B0 Base: verifique memória + ~/.claude/explanations/ para análises anteriores; estenda, não refaça.
• B1 Reconhecimento: um agente de reconhecimento passivo leve por alvo (WebFetch + cabeçalhos + WebSearch) → snapshot fundamentado + o que precisa de navegador.
• B2 Porta de confirmação: apresente snapshot + escopo + o limite de reconhecimento (<scope_boundary>); AskUserQuestion para ir fundo/navegador — pule apenas se o usuário já disse "vá fundo / análise completa".
• B3 Reconhecimento profundo (Workflow): um agente estruturado por assunto, todos compartilhando o schema por assunto (na referência). pipeline() por padrão; divida saídas grandes em disco.
• B4 Navegador (Claude-in-Chrome): capture rede ao carregar, renderize SPAs, sondagem ao vivo de estimadores em uma grade de entrada, cabeçalhos de segurança, conteúdo atrás de paywall/auth — dentro do limite (sem quebrar CAPTCHA/auth, sem endpoints mutantes, nunca envie dados do usuário). Persista capturas conforme avança.
• B5 Engenharia reversa: cada calculadora → implementação de referência executável em TypeScript → valide contra a grade ao vivo → compare com verdade fundamental autoritativa.
• B6 Namespace (se "mais algum?"): DNS+curl+pesquisa de domínios candidatos, classifique, encontre clusters de operadores, sinalize domínios de compra defensiva, analise apenas o conjunto SIM genuinamente distinto.
• B7 Sintetizar: agentes de síntese em leque → DETAILED-<slug>.md ×N + ESTIMATORS.md + COMPARISON.md (incluindo seção de integridade de dados + cluster de operadores) + REPLICATION-BLUEPRINT.md + ARCHITECTURE.md + NAMESPACE.md + SOURCES-*.md + SUMMARY.md (resumo executivo + índice de arquivos). Em seguida, Fase 7 de saída/limpeza.

---

Modo A — Repositório / conceito / docs

Fase 1: Pesquisa Web Paralela (5 agentes de pesquisa)

Crie TODOS em uma mensagem:

Task(subagent_type="general-purpose", prompt="Pesquise [TÓPICO]: O que é? Quem fez? Quando? Por quê?")
Task(subagent_type="general-purpose", prompt="Pesquise [TÓPICO]: Stack técnico, arquitetura, tecnologias-chave")
Task(subagent_type="general-purpose", prompt="Pesquise [TÓPICO]: Artigos, reviews, discussões da comunidade, opiniões")
Task(subagent_type="general-purpose", prompt="Pesquise [TÓPICO]: Alternativas, comparações, quando usar vs não usar")
Task(subagent_type="general-purpose", prompt="Pesquise [TÓPICO]: Documentação, tutoriais, guias de primeiros passos")

Fase 2: Clonar Repositório (se for GitHub)

REPO_DIR=~/.claude/explanations/$(date +%Y%m%d_%H%M%S)_$(basename [URL] .git)
git clone [URL] $REPO_DIR
cd $REPO_DIR

Fase 3: Exploração Paralela da Base de Código (6 agentes Explore)

Crie TODOS em uma mensagem com thoroughness="very thorough":

Task(subagent_type="Explore", prompt="Arquitetura: Estrutura geral, módulos, como se relacionam")
Task(subagent_type="Explore", prompt="Pontos de entrada: Arquivos principais, CLI, endpoints de API, como inicia")
Task(subagent_type="Explore", prompt="Lógica central: Algoritmos-chave, padrões, abstrações")
Task(subagent_type="Explore", prompt="Configuração: Configurações, ambiente, pontos de extensibilidade")
Task(subagent_type="Explore", prompt="Dependências: Pacotes-chave, integrações, serviços externos")
Task(subagent_type="Explore", prompt="Testes e qualidade: Padrões de teste, cobertura, CI/CD")

Fase 4: Contexto Paralelo do Claude Code (2-3 agentes de propósito geral)

Se relevante para Claude/AI/agentes:

Task(subagent_type="general-purpose", prompt="Explique conceitos relevantes do Claude Code para entender isto")
Task(subagent_type="general-purpose", prompt="Compare com ferramentas/SDK do Claude, se aplicável")

Fase 5: Verificação de Meio do Caminho (se complexo)

Use AskUserQuestion se as descobertas revelarem complexidade:

• "Eu encontrei [X]. Quer que eu foque em algo específico?"
• Opções baseadas nas descobertas

Fase 6: Síntese

Combine todas as descobertas em uma explicação abrangente com:

1. Analogia inicial (comparação não técnica)
2. O que é (1-2 frases)
3. Diagrama de arquitetura (ASCII)
4. Como funciona (passo a passo com diagramas)
5. Tabela de componentes-chave (nome, propósito, como funciona)
6. O que é especial (diferenciadores)
7. Lista de capacidades (o que pode fazer)
8. Tabela de comparação (vs alternativas)
9. Mergulho técnico profundo (detalhes de implementação)
10. Pegadinhas e considerações

Fase 7: Saída

Exibir na conversa

Explicação formatada completa com todos os visuais.

Salvar em arquivos

OUTPUT_DIR=~/.claude/explanations/$(date +%Y%m%d_%H%M%S)_[slug-do-topico]
mkdir -p $OUTPUT_DIR

# Salvar arquivos:
# $OUTPUT_DIR/SUMMARY.md - Referência rápida (versão de 30 segundos)
# $OUTPUT_DIR/DETAILED.md - Análise completa
# $OUTPUT_DIR/ARCHITECTURE.md - Todos os diagramas
# $OUTPUT_DIR/COMPARISON.md - Análise de alternativas

Acompanhamento

Após exibir, pergunte:

• "Qual aspecto você gostaria de explorar mais a fundo?"
• "Alguma dúvida sobre o que expliquei?"
• Incentive acompanhamento

Limpeza

Use AskUserQuestion para limpeza (combine se ambos se aplicarem):

Se repositório clonado:

• question: "Excluir o repositório clonado?"
• options:
  • "Sim, excluir" - Remover $REPO_DIR automaticamente
  • "Não, manter" - Mostrar caminho: "Repositório mantido em: $REPO_DIR"

Se sim: rm -rf $REPO_DIR Se não: Exibir caminho para acesso manual

Sempre (arquivos de explicação):

• question: "Excluir os arquivos de explicação salvos?"
• options:
  • "Sim, excluir" - Remover $OUTPUT_DIR automaticamente
  • "Não, manter" - Mostrar caminho: "Explicações salvas em: $OUTPUT_DIR"

Se sim: rm -rf $OUTPUT_DIR Se não: Exibir caminho para acesso manual

Pergunta combinada (se ambos repositório e arquivos):

• question: "Análise completa. O que você gostaria de limpar?"
• options:
  • "Excluir ambos, repositório e arquivos de explicação"
  • "Excluir apenas repositório, manter explicações"
  • "Excluir apenas explicações, manter repositório"
  • "Manter tudo"

Execute exclusões com base na seleção, exiba caminhos para o que for mantido.

<visual_formats>

Formatos Padrão de Diagrama

Arquitetura:

┌─────────────┐     ┌─────────────┐
│  Componente  │────►│  Componente  │
└─────────────┘     └─────────────┘

Fluxo:

INÍCIO → Passo 1 → Passo 2 → Decisão?
                              ├─ Sim → Caminho A
                              └─ Não → Caminho B

Tabela de comparação:

| Aspecto      | Opção A | Opção B | Vencedor |
|--------------|---------|---------|----------|
| Velocidade   | Rápida  | Lenta   | A        |

Detalhamento de componentes:

┌──────────────────────────────────────┐
│           Nome do Sistema            │
├──────────────────────────────────────┤
│ ┌────────┐ ┌────────┐ ┌────────┐    │
│ │Módulo A│ │Módulo B│ │Módulo C│    │
│ └───┬────┘ └───┬────┘ └───┬────┘    │
│     └──────────┴──────────┘         │
│            Camada Compartilhada      │
└──────────────────────────────────────┘

</visual_formats>

<success_criteria> Ambos os modos:

• Fez perguntas esclarecedoras / fundamentou antes de começar; roteou para o modo correto
• Produziu diagramas visuais para cada conceito principal; incluiu profundidade técnica recriável
• Exibiu resumo executivo na conversa E salvou o conjunto de documentos em arquivos
• Ofereceu acompanhamento + limpeza; honrou a escolha do usuário de manter/excluir

Modo B (produto ao vivo / concorrente / produto de dados / cenário) também:

• Fez uma passagem de reconhecimento + porta de confirmação (ou honrou um explícito "vá fundo") e declarou o limite de reconhecimento
• Permaneceu estritamente dentro do limite: sem quebra de CAPTCHA/auth, sem coleta em massa, sem chamar endpoints mutantes/admin, nunca enviou dados do usuário; exposições observadas, não exploradas
• Usou a ferramenta Workflow com um schema compartilhado por assunto quando 3+ assuntos/multifásico; persistiu artefatos; resiliente a interrupções (retomada)
• Sondou ao vivo cada calculadora e entregou uma implementação de referência executável validada N/N contra saídas observadas, comparada com verdade fundamental autoritativa
• Para cenários: descobriu o namespace completo, classificou cada um, encontrou clusters de operadores, sinalizou domínios de compra defensiva, analisou apenas os distintos
• Síntese inclui seção de integridade de dados + seção de cluster de operadores + blueprint de replicação

</success_criteria>