Zoom Out — Mapa de Bairro Antes do Codigo

Inspiracao: mattpocock/skills/engineering/zoom-out (MIT). Adaptado: forca uso de graphify-out/graph.json antes de Grep/Read brutos (CLAUDE.md global).

Quando Usar

ao receber task em modulo que o agente nao conhece bem
quando o usuario disse "estou perdido nessa parte"
antes de propor refactor ou architecture change (input pra skill 38)
antes de explorar com Grep ou Read direto (mais economico)
como preludio de detective-spec em codigos legados

Quando NAO Usar

voce ja conhece o modulo (zoom out vira ruido)
task pontual em arquivo unico ja identificado
bug fix com stack trace claro

Governanca Global

Esta skill segue GLOBAL.md, policies/code-exploration.md (graph > grep > read), policies/token-efficiency.md (mapa enxuto, nao dump), policies/handoffs.md (o mapa pode ser consumido por outras skills).

Protocolo

1. Tentar graph primeiro

Antes de qualquer Read/Grep, tentar:

test -f graphify-out/graph.json && echo "graph disponivel" || echo "sem graph"

Se graph existir, ler graphify-out/graph.json + graphify-out/GRAPH_REPORT.md (god nodes, communities). Isso responde 80% das perguntas de mapa.

2. Fallback: descoberta estrutural

Sem graph, descobrir estrutura via Glob:

# Topologia
find <alvo> -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" \) | head -50

Identificar:

entry points (index., main., app., cli.)
agrupamentos por pasta (modulos logicos)
arquivos grandes (provaveis hubs)

3. Mapear callers/callees principais

Para cada hub identificado, Grep por importacoes:

# Quem usa o modulo X?
rg "from ['\"].*<modulo-X>" --type ts --type tsx -l

4. Glossario do projeto

Antes de produzir output, capturar vocabulario do dominio lendo (em ordem de preferencia):

memory/constitution.md (se existir — termos canonicos)
docs/repo-audit/current.md (audit)
README.md (sintese)
Nomes de pastas/arquivos (fallback)

O mapa fala a lingua do projeto, nao termos genericos.

Checkpoint antes de entregar o mapa: para cada "hub" ou "god node" listado, confirmar com um segundo grep (contagem real de importações, não só a posição no graph.json) — graph desatualizado pode listar um arquivo já removido/refatorado como hub. Item que não confirma no código atual sai do mapa ou vira nota "desatualizado desde X".

Output

Tabela markdown ou hierarquia textual:

# Mapa de <area>

## Vocabulario do dominio
- <termo>: <definicao curta>

## Arquitetura geral
<diagrama ASCII opcional — so se reduz complexidade>

## Modulos principais

| Modulo | Proposito | Callers principais | Callees principais |
|--------|-----------|-------------------|-------------------|
| ...    | ...       | ...               | ...               |

## God nodes (>X dependentes)
- <arquivo>: <numero> dependentes — provavel ponto de friccao

## Pendencias visiveis
- <TODO/FIXME publicos>
- <gaps documentacao>

Handoffs

input pra skill 38 (architecture-deepener): mapa identifica god nodes; skill 38 propoe deepening
input pra skill 33 (detective-spec): mapa orienta quais modulos detective deve cavar primeiro
input pra skill 09 (orchestrator): mapa informa onde a feature toca, qual pipeline montar
input pra skill 32 (smart-suggestions): dado o mapa, sugerir proxima acao concreta

Anti-padroes

❌ Dump completo de find . -name "*.ts" — isso e fuga, nao mapa
❌ Ler 50 arquivos pra entender 1 modulo — usa graph primeiro
❌ Mapa generico sem vocabulario do projeto
❌ "vou ler tudo e depois mapeio" — produz o mapa enquanto explora, nao depois

zoom-out