---
title: Erros comuns e recuperação
description: Como diagnosticar falhas frequentes sem perder rastreabilidade.
context: Troubleshooting operacional do site e do fluxo SDD.
---

# Erros comuns e recuperação

Falhas no SDD devem virar evidência, não improviso. Use esta página para recuperar o fluxo preservando artifact store, estado local e alterações de outros agentes.

## `next` não encontrado

Sintoma:

```bash
sh: next: command not found
```

Recuperação:

```bash
cd docs-site
npm ci
npm run build
```

Registre no handoff se o build não foi executado por dependências ausentes. Não declare a documentação saudável sem rodar o build.

## Artifact store ausente

Sintoma:

```text
docs/<slug>/traceability-map.yaml não encontrado
```

Recuperação:

```bash
sdd init "nome da orquestracao"
sdd artifact status "nome da orquestracao"
```

Depois salve o artefato correto com `sdd artifact save`.

## Checkpoint pendente

Sintoma: o fluxo para após PRD, Tech Spec, Refinement ou Review.

Recuperação:

- Leia o artefato apontado pelo gate.
- Aprove, rejeite ou ajuste explicitamente.
- Não marque `approved` sem decisão humana, exceto no modo auditável `--unattended`, que registra `channel: automation`.

## Context Pack obsoleto

Sintoma: execução ou review reclama de contexto crítico stale.

Recuperação:

```bash
sdd context build --name "nome da orquestracao" --stage execution --write
sdd quality report --name "nome da orquestracao" --json
```

Se o relatório continuar crítico, volte para Tech Spec ou Tasks antes de executar código.

## Doctors falhando

Sintoma: `clients doctor`, `skills doctor`, `providers doctor` ou `capabilities doctor` reporta drift.

Recuperação:

```bash
sdd clients doctor --strict
sdd skills doctor --strict
sdd capabilities doctor --targets all
sdd providers doctor --json
```

Corrija primeiro a fonte canônica em `templates/`, `.agents/`, `clients/` ou `sdd.config.yaml`; depois sincronize as superfícies derivadas.
