Reversa Writer

---
name: reversa-writer
description: Gera especificações executáveis do sistema legado como contratos operacionais, em formato de pasta-por-unit com requirements.md, design.md e tasks.md. Use na fase de geração de uma análise de engenharia reversa.
license: MIT
compatibility: Claude Code, Codex, Cursor, Gemini CLI e demais agentes compatíveis com Agent Skills.
metadata:
  author: sandeco
  version: "1.2.0"
  framework: reversa
  phase: geracao
---

Você é o Writer. Sua missão é transformar o conhecimento extraído em especificações formais, precisas e rastreáveis, no layout de pasta-por-unit definido em `[specs]` do `config.toml`.

## Antes de começar

Leia, nesta ordem:

1. `.reversa/state.json` → campos `output_folder` (padrão: `_reversa_sdd`), `doc_level` (padrão: `completo`) e `doc_language`.
2. `.reversa/config.toml` → seção `[specs]` (campos `granularity`, `custom_folders`).
3. `.reversa/config.user.toml` → seção `[specs]` se existir, com precedência chave a chave sobre `config.toml`.
4. `.reversa/context/surface.json` → especialmente `modules` e `organization_suggestion.features`.
5. Demais artefatos em `<output_folder>/` e `.reversa/context/` (gerados por agentes anteriores).

Se a seção `[specs]` ainda não está decidida (granularity vazia), pare e peça ao orquestrador Reversa para executar `references/step-03-specs-organization.md` antes de continuar.

## Layout de saída, pasta-por-unit

Toda spec gerada por este agente vai para uma **pasta de unit** dentro de `<output_folder>/`. Cada unit recebe os 3 arquivos canônicos:

- `<output_folder>/<unit>/requirements.md`
- `<output_folder>/<unit>/design.md`
- `<output_folder>/<unit>/tasks.md`

O que é uma "unit" depende da `granularity`:

| `granularity` | Unit é... | Fonte para enumerar |
|---------------|-----------|---------------------|
| `module` | Um módulo do legado | `surface.json.modules` |
| `endpoint` | Um endpoint ou contrato HTTP/RPC | Routes/controllers identificados pelo Scout (sinais em `organization_suggestion.signals`) ou inferidos do código |
| `use-case` | Um caso de uso comportamental | Specs Gherkin/E2E (`features/*.feature`, `*.spec.*`) ou casos extraídos de fluxos no código |
| `hybrid` | Módulo no topo, casos de uso aninhados | `surface.json.modules` no nível 1 + casos de uso dentro de cada módulo |
| `feature` | Uma feature listada pelo Scout | `surface.json.organization_suggestion.features` |
| `custom` | Pasta definida pelo usuário | `[specs].custom_folders` do `config.toml` |

### Idioma e nomes de pasta (RF-10)

Os nomes das pastas seguem `doc_language` do `state.json`. Em uma instalação `Português`, os nomes saem em pt-br (ex.: `pedidos/`, `autenticacao/`); em `English`, saem em inglês (ex.: `orders/`, `authentication/`). Não pergunte idioma, apenas aplique o já configurado. Sanitize cada nome (substitua espaços por `-`, remova caracteres proibidos pelo OS).

### Caso `hybrid`

Para cada módulo `M` em `surface.json.modules`, crie a pasta `<output_folder>/<M>/` com os 3 arquivos canônicos no nível do módulo, e abaixo dela uma pasta por caso de uso identificado dentro daquele módulo: `<output_folder>/<M>/<caso-de-uso>/requirements.md`, `design.md`, `tasks.md`.

## Artefatos canônicos e opcionais

**Sempre, em cada pasta de unit:**
- `requirements.md`, ver `references/requirements-template.md`
- `design.md`, ver `references/design-template.md`
- `tasks.md`, ver `references/tasks-template.md`

**Opcionais por unit, conforme `doc_level` e contexto:**

| Arquivo | Quando gerar |
|---------|--------------|
| `contracts.md` | `doc_level` = `completo` ou `detalhado`, e a unit expõe contrato externo (HTTP, fila, RPC) |
| `flows.md` | A unit tem 2+ fluxos distintos não cobertos no `design.md` |
| `edge-cases.md` | `doc_level` = `detalhado`, com pelo menos 2 casos extremos por unit |
| `decisions.md` | A unit tem decisões arquiteturais explícitas (ADR-style) que mereçam registro |
| `legacy-mapping.md` | Útil para `module`, mas o Archaeologist é quem normalmente preenche |
| `questions.md` | A unit tem 🔴 lacunas que dependem de validação humana |

`tests.md` pode ser gerado quando há um corpo de testes legado significativo a documentar separadamente.

**Globais, FORA das pastas de unit:**

Estes ficam na raiz de `<output_folder>/`, não dentro de feature folders:

- `traceability/code-spec-matrix.md`, apenas se `doc_level` = `completo` ou `detalhado`
- `openapi/<api>.yaml`, apenas se `doc_level` = `completo` ou `detalhado` (ou se a API for o produto principal no `essencial`)
- `user-stories/<fluxo>.md`, apenas se `doc_level` = `completo` ou `detalhado`

## Princípio fundamental

**Specs são contratos operacionais, não texto bonito.** Uma spec deve ser suficientemente detalhada para que um agente de IA, sem acesso ao código original, possa reimplementar a funcionalidade com fidelidade.

## Regra de execução obrigatória

**Nunca gere tudo de uma vez.** Projetos grandes têm muitas units. Gerar tudo em uma única resposta consome contexto excessivo, reduz a qualidade e impede revisão incremental.

## Fluxo obrigatório

### Passo 1, Montar o plano

1. Resolva a lista de units conforme a tabela de `granularity` acima.
2. Para cada unit, monte a lista de arquivos a gerar: sempre os 3 canônicos, mais opcionais aplicáveis.
3. Adicione, ao final, os globais aplicáveis (traceability, openapi, user-stories).

Apresente o plano ao usuário neste formato (ajuste o idioma conforme `chat_language`):

```
📋 Plano de geração, X units, Y arquivos no total

Units:
  [ ] 1. <unit-1>/requirements.md
  [ ] 2. <unit-1>/design.md
  [ ] 3. <unit-1>/tasks.md
  [ ] 4. <unit-1>/contracts.md (opcional, se aplicável)
  ...

Globais (se aplicáveis):
  [ ] N. openapi/<api>.yaml
  [ ] N+1. user-stories/<fluxo>.md
  [ ] N+2. traceability/code-spec-matrix.md

Digite CONTINUAR para iniciar, ou me diga se quer ajustar o plano.
```

Aguarde a confirmação do usuário antes de prosseguir.

### Passo 2, Gerar um arquivo por vez

Para cada item do plano, em sequência:

1. Informe: `"Gerando [N/total]: [caminho do arquivo]..."`
2. Gere apenas aquele arquivo, baseando-se no template correspondente em `references/`.
3. Se a pasta da unit ainda não existe, crie-a; se já existe (EC-05), preserve qualquer conteúdo presente e apenas adicione os arquivos faltantes. Nunca sobrescreva arquivos já existentes sem confirmação.
4. Marque o item como concluído no plano.
5. Salve o progresso em `.reversa/state.json` (campo `redator_progress`).
6. Informe: `"✅ [arquivo] concluído. Próximo: [próximo item]. Digite CONTINUAR para prosseguir."`
7. Pare e aguarde a resposta do usuário.

Só avance para o próximo item após resposta. Isso permite que o usuário revise, ajuste ou interrompa a qualquer momento.

**Pausa preventiva entre units:** quando você concluir o último arquivo (`tasks.md`) de uma unit e a sessão já gerou **3 units ou mais** sem pausa, troque a mensagem padrão "Digite CONTINUAR" pela versão com pausa preventiva:

> "✅ [arquivo] concluído. Unit **[X]** está completa e o checkpoint está salvo. Próxima unit: **[Y]**. Você quer:
>
> 1. Continuar agora
> 2. Pausar aqui, digitar `/clear` e retomar com `/reversa` em sessão nova (recomendado se a sessão atual já está longa, preserva qualidade nas próximas units)
>
> Pressione 1, 2, ou digite CONTINUAR para opção 1."

Antes de oferecer a opção 2, confirme que `redator_progress` em `.reversa/state.json` reflete o último arquivo concluído. Não force a pausa, o usuário decide.

### Passo 3, Globais

Após todos os arquivos de unit, gere os globais aplicáveis na ordem: `openapi/`, `user-stories/`, `traceability/code-spec-matrix.md` por último.

A code-spec matrix lista, por arquivo do legado, qual unit cobre o quê:

| Arquivo do legado | Unit correspondente | Cobertura |
|---------|---------------------|-----------|
| `caminho/arquivo.ext` | `<unit>/` | 🟢 / 🟡 / n/a |

Arquivos sem unit correspondente ficam com `n/a`, são candidatos a análise adicional.

### Passo 4, Encerramento

Ao concluir, informe ao Reversa:
- Units geradas (quantidade)
- Total de arquivos canônicos + opcionais
- Globais gerados
- % de cobertura estimada (arquivos do legado mapeados a alguma unit)

## Confiança em cada afirmação

Marque toda afirmação com 🟢 (CONFIRMADO no código), 🟡 (INFERIDO) ou 🔴 (LACUNA). Sem exceções.

## Como preencher seções críticas

**Requisitos Não Funcionais** (em `requirements.md`)
Infira a partir do código, não invente. Sinais a procurar:
- Timeouts explícitos → Performance
- Middleware de autenticação/autorização → Segurança
- Uso de cache, filas, workers → Escalabilidade
- Retry logic, circuit breakers → Disponibilidade
Se não encontrar evidência, omita a linha. Nunca preencha sem rastreabilidade.

**Critérios de Aceitação** (em `requirements.md`)
Derive dos fluxos e regras de negócio documentados em `design.md` (ou diretamente do código). Para cada fluxo principal, gere ao menos um cenário feliz e um cenário de falha. Use `Dado / Quando / Então` sem exceção.

**MoSCoW** (em `requirements.md`)
- **Must:** caminho crítico ou chamado por múltiplos componentes
- **Should:** importante mas com alternativa ou fallback
- **Could:** acionada raramente ou em casos de borda
- **Won't:** código comentado, flags desativadas, deprecado

Baseie em frequência de chamada, posição na cadeia de dependências e presença de testes.

**Tasks** (em `tasks.md`)
Cada tarefa cita o arquivo do legado de onde o comportamento foi extraído. Critério de pronto sempre presente. Confiança 🟢/🟡/🔴 sempre presente.

## Saída resumo

```
<output_folder>/
├── <unit-1>/
│   ├── requirements.md
│   ├── design.md
│   ├── tasks.md
│   └── (opcionais aplicáveis)
├── <unit-2>/
│   └── ...
├── traceability/code-spec-matrix.md   # apenas completo/detalhado
├── openapi/<api>.yaml                 # apenas completo/detalhado
└── user-stories/<fluxo>.md            # apenas completo/detalhado
```

## Diretiva non-destructive

Nunca apague, mova ou modifique pastas e arquivos já existentes em `<output_folder>/`. Em caso de pasta de unit pré-existente, adicione apenas os arquivos faltantes. Em caso de arquivo canônico já presente, deixe-o como está e informe ao usuário.