fix

Files (1)

• SKILL.md

SKILL.md (first lines)

Você é o agente de fix autônomo do Vetor. Sua missão é iterar sobre falhas de build/test até atingir verde, dentro de um worktree já criado.

🚫 **NUNCA entre em plan mode (`EnterPlanMode`).** Este skill roda tipicamente em agentes headless
despachados em background (`issue-worker`), sem interlocutor disponível para aprovar a saída via
`ExitPlanMode` — entrar em plan mode aqui trava a sessão sem recuperação. Independente de a tarefa
parecer "não-trivial" pela heurística padrão do Claude Code, vá **direto** para reproduce → fix
(passo 3), nunca produza um plano para aprovação antes de agir.

⚠️ **IMPORTANTE — Fluidez síncrona obrigatória:** Você NUNCA deve invocar ou esperar por padrões de
"monitor em background" (ex.: "I'll wait for this background monitor to notify me"). Seu próprio
fluxo de execução é **síncrono** — execute cada passo até o final, sem pausar para aguardar
notificação externa. Se encontrar algo que pareça monitoramento assíncrono, ignore-o e prossiga.
Parar antes de atingir um estado terminal é uma falha silenciosa que o coordinator não detecta.

**Ação obrigatória inaugural:** Antes de qualquer passo (antes do `vetor-checks.sh`, antes de
detectar módulos, antes de qualquer coisa), grave o status file com `Status: RUNNING`. Isso torna
a ausência total do arquivo um sinal detectável de falha anômala.

---

## Sintaxe

```
/vetor:fix <descrição>
```

- `<descrição>`: texto livre descrevendo o problema a reproduzir e corrigir (ex.: "cargo clippy warnings em embedding-service", "frontend build failing on import")

---

## 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 — defina uma vez:
> ```bash
> SKILL_DIR="<path absoluto informado como 'Base directory for this skill' no carregamento>"
> ```
> e use `"$SKILL_DIR/../../scripts/..."` em todo comando abaixo, nunca o path relativo isolado.

- `../shared/references/project-conventions.md` — resolva `$DEFAULT_BRANCH`
  e o `module-test-map` antes de prosseguir. **A resolução do `module-test-map.md`/`config.json`
  sempre usa o root do repositório (`vetor-checks.sh repo-root`), nunca o `cwd`** — dentro de um
  worktree, arquivos ignorados pelo `.gitignore` do projeto-alvo (ex.: `.claude/`) não existem
  localmente (issue #160).
- `../shared/references/agent-status.template.md` — path, estados e blocos
  obrigatórios do status file.
- `../shared/references/touched-files-cache.md` — formato do cache gravado no §1.
- `../shared/references/delegate-to-runtime.md` — uso opcional de runtime
  externo (Gemini/OpenCode/Codex) para resumir erros ou rascunhar correções. Qualquer delegação de
  mudança de código exige propor previamente o escopo ao desenvolvedor e obter sua anuência (em `--headless`,
  segue inline por padrão); a validação via testes e a decisão de commit/merge permanecem sempre com o agente.
- `../shared/references/mcp-availability.md` — se a `<descrição>` indicar bug
  visual/frontend e o MCP de browser estiver disponível, use-o antes do §3.a para reproduzir o bug e
  capturar evidência. Se o erro envolver comportamento de uma ferramenta/lib/framework/API externa,
  o MCP Context7 é **obrigatório quando disponível** (ver "Documentação de ferramentas/libs
  (Context7)") antes de aplicar o fix.
- `../shared/references/memory-gotchas.md` — consulta opcional de `gotchas/` e `decisions/` no
  diagnóstico e registro opcional de aprendizado no Green; ausência/falha do MCP não bloqueia o loop.
- `../shared/references/frontend-design-enforcement.md` — se a `<descrição>`
  indicar UI/design de frontend, invoque a skill `vetor:design` antes de aplicar o fix (§3.b).
- `../shared/references/tdd-conventions.md` — disciplina completa de TDD
  (bom teste, seams, anti-padrões, mocking) consumida pelo passo TDD de §3.b — não replique o texto
  aqui.
- `../shared/references/evidence-state.md` — vocabulário de rastreabilidade
  epistemológica (`CONFIRMED`/`INFERRED`/`ASSUMED`/`OPEN_QUESTION`, Evidence Conflict) usado ao
  redigir `Blocked on` em `BLOCKED_WAITING` (§2) quando o bloqueio for epistemológico, não uma
  permissão de comando.

---

## Comportamento

### 0 — Status file inaugural + Guarda de contexto

**Primeira ação (antes de tudo):** grave o status file com `Status: RUNNING`. Derive o path conforme
§2 (ou use o path absoluto recebido do `coordinator`).

```bash
bash "$SKILL_DIR/../../scripts/vetor-checks.sh" in-worktree
```

Se sair não-zero, **aborte**: `/vetor:fix` deve rodar de dentro de um worktree.

### 1 — Diagnóstico e detectar módulos

Identifique os arquivos e módulos afetados e faça a consulta preventiva de memória descrita em
`memory-gotchas.md` antes de iniciar o ciclo de fix. A consulta é opcional: ausência ou falha do MCP
não interrompe o fluxo.

```bash
git diff "$DEFAULT_BRANCH" --name-only
```

Mapeie ao módulo usando a tabela do module-test-map, resolvido a partir do root do repositório
(ver `project-conventions.md`), não do `cwd` do worktree. Módulos cujo comando é
`sem suíte de testes` não entram no loop: registre `skipped (no test suite)` e não os trate como
falha.

**Repo Map do módulo (diagnóstico preventivo, RF-04 de `docs/specs/repo-map-ast-context-packet.md`,
issue #507).** Antes de abrir arquivos inteiros ou rodar `grep`/`find` para descobrir onde moram os
tipos e as assinaturas, peça o mapa sintático do módulo onde a falha apareceu:

```bash
REPO_ROOT="$(bash "$SKILL_DIR/../../scripts/vetor-checks.sh" repo-root)"
deno run -A "$SKILL_DIR/../../scripts/repo-map.ts" --module <módulo> \
  --module-test-map "$REPO_ROOT/.claude/vetor/module-test-map.md" \
  --cache-path "$REPO_ROOT/.claude/vetor/cache/repo-map.json" \
  --files <arquivo1,arquivo2>
```

- O comando roda no worktree, então o mapa reflete o código da branch; o `module-test-map` e o cache
  vêm do root (o worktree pode não ter o primeiro, issue #160, e o cache do root poupa o mapa a
  frio). Se a gravação do cache for recusada, o aviso não bloqueia o loop.
- `--files` é opcional: liste os arquivos que o erro cita (stack trace, import quebrado) e os do
  `git diff` acima. Para o módulo catch-all (`root`) ele é o que dá foco ao mapa; sem ele o CLI
  avisa que o escopo é largo.
- O mapa traz só as assinaturas exportadas (sem corpos): use-o para decidir quais arquivos abrir e
  que imports usar, e `Read` o trecho real antes de editar.

From Tavaressan/Vetor, MIT.

More from Tavaressan/Vetor