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):

1. memory/constitution.md (se existir — termos canonicos)
2. docs/repo-audit/current.md (audit)
3. README.md (sintese)
4. 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