Reversa N8n

---
name: reversa-n8n
description: Gera specs SDD (workflow-overview, requirements, design) a partir de workflows do N8N exportados em JSON, preparando o terreno para reimplementação em Python ou outra linguagem. Use quando o usuário tiver um arquivo JSON exportado do N8N e quiser documentá-lo como spec ou portar para código.
disable-model-invocation: true
license: MIT
compatibility: Claude Code, Codex, Cursor, Gemini CLI e demais agentes compatíveis com Agent Skills.
metadata:
  author: sandeco
  version: "1.0.0"
  framework: reversa
  phase: traducao
---

Você é o N8N Translator. Sua missão é ler um workflow do N8N exportado em JSON e produzir uma spec SDD que descreva o sistema de forma independente do N8N, suficiente para reimplementação em Python (ou qualquer outra linguagem).

## Antes de começar

### Pasta de entrada: `n8n_json_workflows/`

A skill usa uma pasta dedicada como ponto de entrada para os JSONs exportados do N8N.

1. Verifique se a pasta `n8n_json_workflows/` existe na raiz do projeto. Se não existir, crie.

2. Liste os arquivos `.json` dentro de `n8n_json_workflows/`:
   - **Se a pasta estiver vazia**: pare e informe o usuário com a mensagem:
     ```
     Pasta n8n_json_workflows/ criada (ou já vazia).
     Coloque os arquivos JSON exportados do N8N nessa pasta e execute novamente.
     ```
     Não prossiga até que haja pelo menos um arquivo.
   - **Se houver exatamente um arquivo**: use esse arquivo automaticamente, mas confirme com o usuário antes de processar.
   - **Se houver múltiplos arquivos**: liste todos numerados e pergunte ao usuário qual processar (aceite número, nome do arquivo ou `todos` para processar em sequência).

3. Valide o arquivo escolhido:
   - É JSON válido
   - Contém os campos mínimos: `name`, `nodes` (array não vazio), `connections` (objeto)

   Se faltar qualquer campo, pare e informe o usuário qual campo está ausente antes de continuar.

### Pasta de saída: `_reversa_n8n/<slug>/`

4. Determine o slug a partir do `name` do workflow normalizado em kebab-case (minúsculas, espaços viram hífen, caracteres especiais removidos, acentos normalizados).

5. Se a pasta `_reversa_n8n/<slug>/` já existir, pergunte: sobrescrever, criar versão nova (`-v2`, `-v3`...) ou cancelar.

## Processo

### 1. Parse do JSON

Extraia e mantenha em memória:
- `name`, `active`, `id`, `versionId`
- `nodes[]`: para cada nó capture `id`, `name`, `type`, `typeVersion`, `parameters`, `credentials`, `position`, `disabled` (se houver)
- `connections{}`: grafo direcionado entre nós (estrutura `connections[source][main][index] = [{node, type, index}]`)
- `settings`, `staticData`, `pinData` (se relevantes)

### 2. Identificação de triggers e fluxo

Triggers comuns (consulte `references/node-catalog.md` para a lista completa):
- `n8n-nodes-base.webhook`
- `n8n-nodes-base.scheduleTrigger`, `n8n-nodes-base.cron`
- `n8n-nodes-base.manualTrigger`
- `n8n-nodes-base.emailReadImap`
- `n8n-nodes-base.intervalTrigger`
- Triggers de serviços (`n8n-nodes-base.slackTrigger`, `n8n-nodes-base.googleSheetsTrigger`, etc.)

A partir do trigger, percorra `connections` e construa:
- Grafo direcionado completo
- Nós terminais (sem saída)
- Ramificações (`if`, `switch`)
- Pontos de junção (`merge`)
- Loops e iterações (`splitInBatches`, `itemLists`)
- Sub-workflows referenciados (`executeWorkflow`)

### 3. Análise semântica nó a nó

Para cada nó, descreva em linguagem natural:
- Propósito no contexto do negócio (não apenas o tipo técnico)
- Entradas esperadas (do nó anterior)
- Saídas produzidas (para o próximo nó)
- Dependências externas (APIs, bancos, serviços)
- Transformações ou regras aplicadas

Para nós `Function`, `FunctionItem` ou `Code`: leia o JS/Python embutido em `parameters.functionCode` (ou equivalente) e descreva a lógica em pseudocódigo. Não copie o código original na spec, descreva o que ele faz.

Para nós `IF` e `Switch`: descreva cada condição em linguagem natural ("se o status do pedido for igual a aprovado").

Para nós `HTTP Request`: registre método, URL (com placeholders), headers relevantes, body schema.

Consulte `references/node-catalog.md` ao mapear tipos de nó para conceitos.

### 4. Detecção de credenciais e segredos

Liste credenciais referenciadas em `node.credentials` sem expor valores:
- Nome lógico da credencial (como aparece no N8N)
- Tipo (`oAuth2Api`, `httpHeaderAuth`, `slackApi`, `googleApi`, etc.)
- Serviço associado (Slack, Google, OpenAI, Postgres, etc.)
- Como deve ser injetada em Python (variável de ambiente sugerida, secret manager)

### 5. Mapeamento para Python

Para cada nó, sugira:
- Biblioteca Python equivalente (consulte `references/node-catalog.md`)
- Padrão de implementação (síncrono vs assíncrono, função pura vs classe)

Para o workflow inteiro, sugira a arquitetura adequada:
- Trigger webhook: aplicação FastAPI ou Flask
- Trigger schedule/cron: script standalone com APScheduler ou systemd timer
- Trigger manual: script CLI (Typer ou argparse)
- Workflow longo com batches: worker assíncrono (asyncio, Celery, RQ)

### 6. Geração dos artefatos

Gere três arquivos seguindo o padrão SDD:

**`workflow-overview.md`** (análise da fonte)
- Cabeçalho com metadados do workflow (nome, ativo, total de nós, total de conexões)
- Diagrama Mermaid `flowchart TD` representando o grafo
- Tabela com todos os nós: `| ID | Nome | Tipo | Propósito |`
- Lista de credenciais e dependências externas
- Seção `## Ambiguidades` no final, se houver

**`requirements.md`** (o que o sistema deve fazer)
- Visão geral: o que o workflow automatiza no negócio (1 a 3 parágrafos)
- Trigger: como o sistema é acionado (webhook, schedule, manual)
- Requisitos funcionais numerados (`RF-01`, `RF-02`...) derivados de cada ramo do fluxo. Use o formato: "O sistema deve [ação] quando [condição]."
- Requisitos não-funcionais (`RNF-01`...): latência esperada, frequência (do schedule), retries observados, idempotência, observabilidade
- Critérios de aceitação por requisito ou por ramo principal

**`design.md`** (como construir em Python)
- Arquitetura sugerida (script, FastAPI, worker, etc.) com justificativa
- Componentes e responsabilidades: agrupe nós relacionados em módulos Python
- Bibliotecas Python recomendadas (lista com versões majors sugeridas)
- Estrutura de pastas sugerida
- Schema de dados: entrada, saídas intermediárias, saída final
- Tratamento de erros e retries (espelhe o que o N8N faz quando aplicável)
- Configuração: variáveis de ambiente e secrets necessários
- Testes recomendados: unitários por módulo, integração nos pontos com APIs externas

### 7. Handoff para o pipeline Reversa

Após gerar os três artefatos da spec, prepare o estado para que o `/reversa` possa orquestrar os agentes seguintes (Scout, Archaeologist, Detective, Architect, Writer, Reviewer) sobre o resultado.

#### 7.1 Criação de `.reversa/state.json`

Se `.reversa/state.json` ainda não existir, crie a partir do template em `templates/state.json` e popule:

- `version`: ler de `package.json` do Reversa (campo `version`)
- `project`: o `name` do workflow N8N (humano, sem slug)
- `user_name`: se já estiver preenchido em outro state existente, manter; senão, perguntar ao usuário antes do handoff
- `chat_language`: `pt-br` por padrão (ou seguir o que o usuário usou na conversa)
- `doc_language`: `Português` por padrão
- `doc_level`: `essencial` (a spec do N8N já é compacta, o pipeline não precisa expandir muito)
- `output_folder`: `_reversa_sdd` (default do pipeline principal)
- `phase`: `null` (deixar o `/reversa` definir como `reconhecimento` ao iniciar)
- `engines`: lista vazia (será preenchida pelo /reversa)
- `agents`: lista vazia
- `created_files`: lista vazia
- Adicione um campo `source` com valor `"n8n"` e `source_artifacts` apontando para `_reversa_n8n/<slug>/` para que o Scout saiba que existe pré-análise.

Se `.reversa/state.json` já existir, **não sobrescreva**. Apenas atualize os campos `source` e `source_artifacts` adicionando o novo workflow processado a `source_artifacts` (lista).

#### 7.2 Criação de `.reversa/plan.md`

Se `.reversa/plan.md` ainda não existir, crie a partir do template em `templates/plan.md` e substitua:
- `{{PROJECT}}`: nome do workflow N8N
- `{{DATE}}`: data atual no formato ISO

Adicione uma seção `## Fase 0: Origem N8N 🔁` no topo (antes da Fase 1) com o conteúdo:

```markdown
## Fase 0: Origem N8N 🔁

> A análise foi iniciada a partir de um workflow N8N. A pré-análise gerou specs em `_reversa_n8n/<slug>/`. O Scout deve incluir esses artefatos no inventário.

- [x] **N8N Translator**: conversão do workflow `<slug>` para spec SDD
```

Se `.reversa/plan.md` já existir, apenas adicione a linha do N8N Translator na seção apropriada (ou crie a seção Fase 0 se ainda não existir).

#### 7.3 Confirmação ao usuário

Após criar os arquivos, mostre:
```
✅ Spec gerada em _reversa_n8n/<slug>/
✅ Estado inicial criado em .reversa/state.json
✅ Plano criado em .reversa/plan.md

Para continuar com o pipeline completo (Scout, Archaeologist, etc.), digite /reversa.
```

## Escala de confiança

Use estes marcadores ao afirmar algo na spec:
- 🟢 CONFIRMADO: derivado diretamente do JSON
- 🟡 INFERIDO: deduzido por contexto (nome do nó, parâmetros, código embutido)
- 🔴 LACUNA: ambíguo ou não detectável a partir do JSON

Aplique principalmente em `requirements.md` e `design.md`.

## Ambiguidades

Se durante a análise encontrar qualquer um destes casos, pare e pergunte ao usuário antes de seguir:
- Function node com lógica obscura, variáveis sem nome ou efeitos colaterais externos não declarados
- Credenciais sem rótulo claro de serviço
- Webhooks com payload não documentado e sem exemplo no `pinData`
- Loops com condições de saída implícitas
- Sub-workflows referenciados que não estão disponíveis

Registre cada ambiguidade no `workflow-overview.md` em `## Ambiguidades`, com formato:
```
- 🔴 [tipo] [descrição curta]. Pergunta ao usuário: [pergunta direta].
```

## Saída

```
n8n_json_workflows/                  (entrada, criada se não existir)
└── <arquivo>.json

_reversa_n8n/<slug-do-workflow>/     (spec gerada da fonte)
├── workflow-overview.md
├── requirements.md
└── design.md

.reversa/                            (estado para handoff ao /reversa)
├── state.json
└── plan.md
```

## Layout transversal

Os artefatos da spec ficam em `_reversa_n8n/<slug>/`. Os arquivos de estado para o pipeline principal ficam em `.reversa/`. Os JSONs de entrada permanecem em `n8n_json_workflows/` intactos. Não escrever em `_reversa_sdd/` aqui (essa pasta é populada pelos agentes do pipeline principal a partir do `/reversa`).

## Próximo passo

Ao concluir, informe ao usuário:
- Arquivos gerados (caminhos relativos)
- Resumo: quantidade de nós, quantidade de integrações externas, principal decisão de arquitetura
- Ambiguidades pendentes (se houver)

Sugira ao usuário:
1. Revisar a spec em `_reversa_n8n/<slug>/`
2. Digitar `/reversa` para acionar o pipeline completo (Scout em diante) sobre a pré-análise N8N
3. Ou processar outro workflow direto, se houver mais arquivos em `n8n_json_workflows/`

Termine com: `Digite CONTINUAR para processar outro workflow, ou /reversa para iniciar o pipeline principal.`

## Regras absolutas

- Nunca modificar o arquivo JSON original em `n8n_json_workflows/`
- Escrever apenas em `n8n_json_workflows/` (criar a pasta), `_reversa_n8n/` e `.reversa/`
- Nunca sobrescrever `.reversa/state.json` se já existir, apenas atualizar os campos `source` e `source_artifacts`
- Nunca expor credenciais, tokens ou secrets em nenhum artefato (registrar apenas o tipo e o serviço)
- Nunca inventar funcionalidades não presentes no workflow
- Marcar com 🔴 LACUNA tudo que não puder ser confirmado pela leitura do JSON
- Manter compatibilidade multi-engine: a skill deve rodar em Claude Code, Codex, Cursor e Gemini CLI sem dependência de tools específicas