Imported from pauloborini/talos (hosts/opencode/.opencode/skills/talos-slice-review/SKILL.md). Install upstream with npx skills add pauloborini/talos --skill talos-slice-review. Copyright stays with the author.

Talos Slice Review

Use this skill when --review is present after talos-plan-execute (or any equivalent implementation pass has finished a specific plan slice), or when the sprint file's policy_manifest.critical_review.required: true makes the review mandatory (CN5/D06 — dispatched by the orchestrator without --review).

Review only the slice that was executed. Do not widen into a generic repo audit unless the user explicitly asks for that.

Invocation gate

Dispatch conditions are: (1) --review in the user command; or (2) policy_manifest.critical_review.required: true in the sprint file §10 (declared contract value — mandatory review, G8). Do not auto-trigger from heuristics, diff size, risk level, or validator observations. If neither condition is present, report that external review was skipped by contract.

Uso standalone — rótulo de garantia reduzida obrigatório (PRD D10/D11)

Esta skill é análise de leitura: revisa código, não muta código. Pela fronteira de determinismo do Talos (mutação de código, PRD D10), leitura standalone é permitida, mas carrega risco epistêmico — a análise não passou pela defesa fria do pipeline (talos-task-validator, que é pipeline-only, só state_path). Esse risco é mitigado por rótulo, não por gate.

Regra dura: quando talos-slice-review roda fora do pipeline (sem o talos-task-validator ter fechado a slice via state file), a saída SEMPRE sai rotulada como garantia reduzida. É proibido simular validator_status: passed ou qualquer veredito de validação aprovado — a review é leitura, não validação fria.

Formato exato do rótulo (obrigatório no topo da saída standalone)

guarantee_level: reduced_standalone
validator_status: not_run (sem validator-closed)
scope: standalone

• guarantee_level: reduced_standalone — enum fixo (PRD D12); nunca full_pipeline em uso standalone.
• validator_status: not_run (sem validator-closed) — declara explicitamente que a defesa fria não rodou. Proibido escrever passed/pass.
• scope: standalone — marca que a review não está ancorada num state file de pipeline.

Quando a review roda dentro do pipeline (despachada pelo orquestrador após o validator frio fechar a slice), o nível de garantia da slice vem do pipeline (full_pipeline) e este rótulo de redução não se aplica — mas a própria review continua sendo leitura e nunca emite veredito de validador.

Invariante: uma análise de leitura standalone nunca se declara fechada por validação; sai rotulada reduced_standalone e jamais simula validator_status: passed (PRD D10/D11, fecha Q-08).

State persistence

Use talos_run_state as the primary source for run state, dispatch status, and validator status. Do not read or write run ledger files directly. If MCP state is unavailable, block the review rather than accepting a local file fallback.

Review Contract

Base the review on three inputs:

1. The plan artifact produced by talos-plan-handoff (Section 2 - Invariantes, Section 6 - Contratos, Section 8 - Validação).
2. The executed task ids or slice boundaries.
3. The real code touched by the implementation.

Required Workflow

1. Build the slice boundary first

Before reviewing code, identify:

• boundary físico do diff a partir do state/task ids; use a base configurada ou upstream e inclua mudanças não commitadas pertencentes à slice.
• Section 2 - Invariants of Execution (contract).
• Section 6 - Technical Contracts (signatures and shapes).
• Section 8 - Validation and Checklist (QA criteria).
• touch files expected vs actual.
• resolved conflicts and permission matrices that apply.

If the diff and the plan disagree materially, call that out as a structural finding or blocker. Do not silently review an invented scope.

2. Review in code-review mode, not implementation mode

This skill is not for fixing code first. It is for finding problems first. Look for:

• behavioral regressions introduced by the slice.
• hidden logic gaps or missing business scenarios.
• state-transition bugs and view/store mismatches.
• security or privacy issues.
• contract drift from the plan.
• validation and tests gaps.

3. Use the plan to hunt missing scenarios

For each executed task, compare: stated objective, expected change, invariants preserved, and done criteria with real code. Ask what the implementation forgot:

• State & orquestration: transition states reativity (loading, success, empty, error), rapid triggers concurency, setup/cleanup symmetry, async stale.
• Business rules: negative paths, closed decisions, fallsback that weaken invariants.
• View & rendering: inputs empty, null, partial, out of order, UI permission conditional.
• Contracts: shape drift, enums, mappers, RLS server-side, i18n parity.

Aplique estes probes determinísticos a cada símbolo ou hunk alterado relevante:

• Linha a linha: leia cada hunk alterado e a função completa que o contém; construa entradas, estados, timings ou plataformas concretas capazes de provocar falha.
• Comportamento removido: para cada guard, validação, cleanup, error path ou teste removido/substituído, identifique o invariante protegido e prove onde o novo código o restabelece.
• Rastreamento cross-file: inspecione callers e callees quando assinaturas, shapes de retorno, erros, timing, ordem ou pré-condições mudarem.
• Altitude: confirme que a mudança corrige o componente proprietário do invariante, sem empilhar um caso especial local sobre um defeito compartilhado.
• Regras aplicáveis: inspecione arquivos de instruções do repo que governam os arquivos alterados. Reporte apenas violações exatas, com path da regra, texto da regra, linha violadora e impacto concreto.

Reuse, simplificação e eficiência só viram findings quando o diff atual cria custo comportamental, operacional ou de manutenção concreto. Não reporte preferências de estilo.

4. Distinguish current-diff findings from pre-existing issues

Prefer findings attributable to the executed slice. Mark pre-existing issues as observations or separate notes to keep signals clean and actionable.

5. Verifique candidatos antes de reportar

Elimine duplicatas que descrevam o mesmo defeito no mesmo local. Classifique cada candidato restante como:

• CONFIRMED — evidência e cenário de falha alcançável sustentam o defeito.
• REFUTED — código, tipo, invariante ou guard prova que o candidato é falso ou já está tratado.
• NEEDS_EVIDENCE — o cenário é relevante, mas a evidência disponível não estabelece o defeito.

Apenas CONFIRMED vira finding. Descarte REFUTED. Mova NEEDS_EVIDENCE para Perguntas Abertas ou Suposições, sem apresentá-lo como defeito. Nunca mantenha um candidato apenas por ser plausível.

Antes de renderizar a saída, materialize os findings confirmados como JSON e execute o gate canônico Node node scripts/classify_findings.mjs <findings.json>. Cada item deve conter id (formato F-NNN), severity, task_id, title, file, line, failure_mode, evidence, recommendation e fix_validation. Saída não-zero bloqueia o relatório até o payload ser corrigido; é proibido ignorar o gate ou substituir campos ausentes por texto vazio. Array vazio é válido quando não há findings confirmados.

Node é o único requisito runtime deste gate e funciona em Linux/macOS/Windows. scripts/classify_findings.py permanece por uma release somente como wrapper compatível que delega ao Node; não é fonte canônica nem torna Python obrigatório.

6. Recomende uma correção de causa raiz

Todo finding deve incluir exatamente uma recomendação principal de correção e uma validação que comprove a correção. A recomendação deve:

• atacar a causa raiz no componente proprietário do invariante violado;
• ser cirúrgica e permanecer no boundary revisado, salvo quando a evidência provar que o proprietário está fora dele;
• preservar contratos do plano, arquitetura e comportamento existente não implicado pelo finding;
• nomear concretamente componente, condição e comportamento esperado;
• ser a melhor correção sustentada pela evidência disponível, nunca uma alegação sem suporte de superioridade absoluta.

Não ofereça alternativas A/B. Não forneça patch completo nem altere código. Se a evidência for insuficiente para recomendar uma correção com segurança, classifique o candidato como NEEDS_EVIDENCE em vez de emitir finding.

7. Output Expectations

Return exactly this structure:

## Findings

### P0 - F-NNN - <short title>
- **Slice/Task:** T0N
- **Por que importa:** [impacto real]
- **Arquivo:** `relative/path.ext:line`
- **Modo de falha:** [o que quebra e como]
- **Evidência:** [o que suporta o finding]
- **Correção recomendada:** [uma correção cirúrgica na causa raiz]
- **Validação da correção:** [teste/check específico que comprova a resolução]

### P1 - <short title>
[same shape]

### P2 - <short title>
[same shape]

### P3 - <short title>
[same shape]

---

## Perguntas Abertas ou Suposições
[questões que precisam de confirmação antes de agir nos findings]

---

## Resumo da Slice
[breve — o que foi bem implementado, o que precisa atenção, se a slice pode ser considerada fechada]

**Veredito:** pass | pass_with_observations | fail

Do not add extra sections or narrative conclusions.

O Veredito é enum fechado e obrigatório: o orquestrador o ecoa em talos_lock_dispatch(action=complete, phase=slice_review, review_verdict=<veredito>) junto com os findings (review_findings, ids F-NNN). Sem ele o MCP recusa o complete da fase (review_verdict_ausente) — o gate slice_review é derivado desse veredito, nunca declarado pelo orquestrador. fail ou qualquer P0/P1 no packet abre a cadeia de repair (origin=slice_review) antes de qualquer fechamento de sprint.

Fase de verification (pós-repair)

Segundo modo desta skill: revisão pontual pós-repair. Não é uma segunda review completa — é o fechamento mecânico do delta do repair_evidence (D3/D4). A review completa (passos 1–7 acima) permanece a única revisão integral por sprint (D11): a verification NÃO repete os passos 1–4/6/7 dela; o recorte dela é o delta do repair + probes de vizinhança dos arquivos do delta. É proibido usar esta fase como segundo passe integral.

Disparo e entrada

• Disparo: despachada pelo orquestrador após o talos-findings-repair com origem slice_review (repair in-loop) ou após o sidecar talos-escalation-repair. Nunca se auto-dispara e nunca roda antes de existir um commit de repair com repair[] no state.
• Entrada: state_path da slice, os findings originais da review (packet F-NNN) e o repair_evidence do último commit de repair (talos_commit_state com repair[] — files e checks por finding).
• Escopo fechado no delta: apenas os arquivos e checks nomeados no repair_evidence. O revisor lê o diff real desses arquivos (e o state citado) — nunca a slice inteira, nunca arquivos fora do delta. Achado em arquivo fora do delta é "finding novo fora do delta" (regra própria abaixo), não motivo de expansão de escopo.

Âncora mecânica: executar os checks antes de julgar (D5/INV3)

A ordem é obrigatória e inverte qualquer atalho: checks executados ANTES do veredito; sem execução não há veredito.

1. Para cada item do repair_evidence, executar cada check declarado (fix_validation do finding + checks do repair[] correspondente) como comando real no repositório, com resultado observado (exit code), não por leitura de código. Check só conta se foi executado nesta fase.
2. Veredito binário por finding, no enum fechado que o MCP valida (resolved | not_resolved | regression):
   • resolved — todos os checks do finding executados com exit 0 e o defeito ausente no delta;
   • not_resolved — check falho, check não executável (comando quebra por ambiente) ou defeito persiste no delta; registrar a evidência do erro no finding. Nunca resolved por piedade;
   • regression — o delta quebrou comportamento vizinho verificado (probe de vizinhança dos arquivos do delta falhou).
3. resolved sem checks_executed[] não vazio (com resultado de sucesso declarado em check_results[]) é recusado pelo MCP (verification_invalida — AC-02.3.1/INV3); proibir o atalho aqui é obrigação do produtor: o payload só sai da fase com checks executados de verdade.

Saída: eco obrigatório do veredito (VC4/D21)

A fase termina entregando ao orquestrador um bloco verification estruturado, no formato exato que talos_lock_validator(action=repair_complete, data.verification) valida:

{
  "verification": {
    "findings": [
      {
        "finding_id": "F-NN",
        "verdict": "resolved|not_resolved|regression",
        "checks_executed": ["comando executado"],
        "check_results": [{ "check": "comando executado", "exit_code": 0 }]
      }
    ],
    "verified_at": "<timestamp ISO>"
  }
}

O eco é passo de fechamento obrigatório da fase, não sugestão: veredito que não chega ao repair_complete morre na conversa e a sprint não fecha. A review em modo verification não chama talos_lock_validator, talos_commit_state nem nenhuma tool de escrita do MCP — ela devolve o bloco ao orquestrador, que é quem o ecoa (regra dura D2: escrita e correção pertencem a outro agente).

Roteamento do residual por severidade declarada (D6/INV4)

O destino do residual é função da severidade declarada no campo do finding (classificada pelo gate canônico scripts/classify_findings.mjs), nunca da opinião do revisor. É proibido reclassificar severidade (ex.: "P2 grave vira sidecar").

Finding novo fora do delta (D11/R10/INV10)

Finding descoberto fora do delta é reportado no relatório da verification e roteado pela mesma regra de severidade (P0/P1 → sidecar; P2/P3 → PD). É proibido reabrir a review completa, reexecutar os passos 1–7 ou iniciar segundo passe de delta por causa dele — a iteração tem teto finito e o residual vai para sidecar/PD. Na fase de verification é proibido despachar talos-task-validator (task-validator ⟂ slice-review — INV2).

Regras duras da fase

• Read-only: não edita código, não chama talos_commit_state, não despacha subagente de correção — a correção é do talos-findings-repair/sidecar (INV1/D2).
• Não reabre nem reexecuta a review completa; não despacha talos-task-validator; sem segundo passe (INV2/INV10).
• violated no state ⇒ residual P0 mecânico (INV12).