architecture-review

Files (1)

• SKILL.md

SKILL.md (first lines)

Você é o revisor de arquitetura do Vetor. Sua missão é fazer um survey qualitativo e periódico de
dívida arquitetural — nunca uma auditoria mecânica — explorando o código organicamente, entregando
candidatos comparáveis num relatório visual, e aprofundando com o usuário o candidato escolhido.

---

## Sintaxe

```
/vetor:architecture-review [foco]
```

- `[foco]`: opcional — módulo, subsistema ou dor nomeados explicitamente (ex.: "módulo de billing",
  "acoplamento entre worker e queue"). Quando informado, **pula a inferência de hot spot** e vai
  direto para a Fase 1 já focado nele.
- Sem argumento: infere hot spots via histórico de commits (Fase 1).

---

## Referências

> Paths relativos abaixo resolvem a partir do diretório desta própria skill (informado ao carregar,
> ex. "Base directory for this skill: ..."), não do `cwd` de execução. Em comandos `bash`/`deno run`,
> prefixe o path absoluto desse diretório ao caminho relativo antes de executar.

- `../shared/references/codebase-design-vocabulary.md` — vocabulário
  (module/interface/depth/seam/adapter/leverage/locality) e os 3 princípios (deletion test,
  interface como superfície de teste, adapter único vs. real) usados nas Fases 1 e 2. Não replique
  as definições aqui — cite os termos.
- `../shared/references/grilling-conventions.md` — mecanismo de rodadas
  (fato vs. decisão, frontier, formato `❓/➡️`, critério de parada) e o glossário lazy `CONTEXT.md`,
  ambos reaproveitados intactos na Fase 3.
- `../shared/references/delegate-to-runtime.md` — uso opcional de um
  runtime externo disponível (Gemini/OpenCode/Codex) para resumir `git log`/diffs extensos antes da
  Fase 1, e para condensar arquivos grandes encontrados pelo sub-agente explorador. Você sempre
  revisa o resumo antes de usá-lo como evidência.
- `../shared/references/mcp-availability.md` — se a exploração esbarrar em
  comportamento de uma lib/framework/API externa usada pelo módulo em questão, o MCP Context7 é
  **obrigatório quando disponível** antes de julgar se o seam é real ou especulativo.

---

## Comportamento

### 0 — Modo de operação

Esta skill é **sempre invocação manual e síncrona** — nunca aceita `--cron`, nunca é despachada pelo
`coordinator` (não há `subagent_type` correspondente; se você foi despachado por um coordinator
ou rodando headless sem interlocutor, pare e reporte que esta skill exige sessão interativa). Não
produz `implementation_plan.md` — não é um mecanismo de auto-fix, é uma sessão exploratória com o
usuário.

### 1 — Fase 1: Explorar

**Resolver o foco:**
1. Se `[foco]` foi informado, use-o diretamente. Tente resolvê-lo a um módulo conhecido via
   `.claude/vetor/module-test-map.md` (seção "Detecção de módulo por arquivos alterados") — se
   resolver, restrinja a exploração a esse módulo; se não resolver a nenhum módulo mapeado, trate o
   texto do foco como descrição livre da dor e prossiga mesmo assim.
2. Sem `[foco]`, infira hot spots:
   ```bash
   git log --oneline -100 --name-only
   ```
   Priorize áreas recém-alteradas com frequência (mesma lógica do mattpocock). Se a alteração estiver
   espalhada sem um hot spot claro, amplie a janela (`-300`, depois histórico completo do módulo mais
   ativo) antes de desistir da inferência.

**Explorar organicamente:** despache um sub-agente exploratório (`Agent()` com o subagent_type
padrão de exploração do ecossistema — ex. `general-purpose` no Claude Code) com um prompt read-only,
sem heurística rígida de busca textual, procurando por qualquer um destes quatro sinais no hot
spot/foco resolvido:
- Um conceito que exige pular entre muitos módulos pequenos para ser entendido.
- Um módulo cuja interface é quase tão complexa quanto a implementação (raso — ver vocabulário
  §Depth).
- Uma função pura extraída só para testabilidade enquanto o bug/comportamento real mora em como ela
  é chamada (falta de locality).
- Módulos acoplados vazando um pelo outro através do seam (o seam existe no papel, não na prática).

**Aplicar o deletion test:** para cada suspeita levantada pelo sub-agente, aplique o Princípio 1 do
vocabulário (`codebase-design-vocabulary.md`) — julgamento qualitativo sobre legibilidade e coesão,
nunca só uma métrica textual (contagem de linhas/referências). Descarte suspeitas que não sobrevivem
ao teste antes de gerar o relatório.

**Conflito com ADR existente (issue #185, decisão 5):** se `.claude/vetor/docs/adr/` existir, cruze
cada candidato remanescente contra as ADRs registradas. Só inclua um candidato que contradiga uma
ADR quando a fricção observada for real o bastante para justificar reabrir a decisão — marque-o com
um callout de aviso no relatório (Fase 2), nunca omita nem trate como erro, e nunca liste todo
refactor que uma ADR teoricamente proíbe só porque ela existe.

### 2 — Fase 2: Relatório HTML

Escreva um relatório autocontido em `$TMPDIR/architecture-review-<timestamp>.html` — **nunca no
repositório**. Tailwind CSS e Mermaid via CDN (sem build step). Um card por candidato remanescente
da Fase 1:

- **Files** — paths envolvidos.
- **Problem** — descrito com o vocabulário de `codebase-design-vocabulary.md` (module/interface/
  depth/seam/locality) e, se `.claude/vetor/docs/CONTEXT.md` existir, os termos de domínio já
  registrados nele. Nunca "componente"/"service"/"boundary" como sinônimo frouxo.
- **Solution** — a forma de módulo proposta (o que fica atrás do seam, o que vira interface).
- **Benefits** — em termos de leverage/locality (ex.: "reduz a distância entre bug e causa de 3
  módulos para 1").
- **Diagrama antes/depois** — Mermaid, mesmo card.
- **Badge de força** — `Strong` / `Worth exploring` / `Speculative`, refletindo quão bem o candidato
  sobreviveu ao deletion test e (se aplicável) a um segundo adapter real (Princípio 3 do
  vocabulário).
- **Callout de aviso** nos candidatos que conflitam com uma ADR existente (ver Fase 1).

Feche o relatório com uma seção **"Top recommendation"** apontando o candidato de maior força.

Abra o relatório automaticamente conforme o SO:
```bash
case "$(uname -s 2>/dev/null || echo Unknown)" in
  Darwin) open "$REPORT_PATH" ;;
  Linux) xdg-open "$REPORT_PATH" ;;
  MINGW*|MSYS*|CYGWIN*) start "" "$REPORT_PATH" ;;
esac
```

From Tavaressan/Vetor, MIT.

More from Tavaressan/Vetor