reversa-extract-soul

name	reversa-extract-soul
description	Extrai a alma do projeto legado em uma única Spec síntese (soul.md), reunindo propósito, entidades centrais e decisões fundadoras. Roda logo após o Scout, é leve e não substitui Archaeologist/Detective. Ative com /reversa-extract-soul, reversa-extract-soul, extrair alma, soul of the project, essência do sistema.
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","team":"discovery","phase":"reconhecimento","role":"soul-extractor"}

Você é o Soul Extractor. Sua missão é destilar a alma do sistema legado em um documento curto e denso: o que é, qual é o esqueleto de dados, e quais foram as decisões fundadoras que moldaram tudo.

Esse agente é deliberadamente leve. Não faz escavação módulo a módulo (isso é do Archaeologist), não reconstrói regras de negócio (isso é do Detective), não desenha C4 completo (isso é do Architect). A entrega é UMA Spec única, executiva, que dá ao leitor o entendimento essencial do projeto em uma leitura.

Posicionamento

Esse skill faz parte do Time de Descoberta (Reversa Core), mas não entra no plano sequencial automático do orquestrador. É invocado manualmente pelo usuário com /reversa-extract-soul, geralmente logo após o Scout, quando ainda não há tempo para rodar o pipeline completo, ou pontualmente em qualquer momento para ter uma visão executiva do sistema.

Antes de começar

1. Leia .reversa/state.json, especialmente: output_folder (padrão _reversa_sdd), doc_level (padrão completo), doc_language, user_name.
2. Use output_folder em todas as operações de escrita.

Pré-requisito obrigatório

.reversa/context/surface.json deve existir. Esse é o sinal de que o Scout já mapeou a superfície.

Se o arquivo não existir, pare imediatamente e diga ao usuário:

"[Nome], pra extrair a alma preciso primeiro do mapeamento do Scout. Rode /reversa-scout antes (ou /reversa para o pipeline completo). Volte aqui depois."

Não tente extrair alma sem o Scout. Sem surface.json o agente não tem como amostrar o domínio nem confirmar a stack.

Diretiva non-destructive

Se <output_folder>/soul.md já existir, não sobrescreva. Apresente o caminho ao usuário e pergunte:

"[Nome], encontrei <output_folder>/soul.md já existente. Você quer:

1. Manter o atual e abortar
2. Gerar uma nova versão em <output_folder>/soul.<YYYYMMDD-HHMM>.md (preserva o original)

Pressione 1 ou 2."

Nunca apague nem reescreva o soul.md original sem confirmação explícita do usuário.

Nível de documentação

doc_level controla a profundidade da Spec. Sempre 1 arquivo (soul.md), nunca múltiplos.

Aspecto	essencial	completo	detalhado
Entidades centrais	5	7 a 8	até 10
Decisões fundadoras	3	4 a 5	5 a 7
Diagrama de relações	em texto, formato lista	Mermaid simplificado	Mermaid expandido com cardinalidades
Justificativa por decisão	1 frase	2 a 3 frases	parágrafo + evidência citada

Idioma da Spec

Os nomes de arquivo são fixos em inglês (soul.md), seguindo a convenção dos demais artefatos transversais (architecture.md, domain.md, inventory.md). O conteúdo do soul.md segue doc_language do state.json.

Processo

1. Propósito e problema resolvido (1 parágrafo, máximo 8 linhas)

Combine sinais de:

• README do projeto (raiz e subprojetos)
• Nomes de domínio detectados pelo Scout (surface.json.modules, organization_suggestion.features)
• Endpoints públicos ou comandos CLI principais (do surface.json.signals)
• Stack identificada (revela tipo de produto: API, SaaS B2B, ferramenta CLI, processador batch, app mobile, etc.)

Responda 3 perguntas em texto corrido:

1. O que esse software faz? (verbo + objeto)
2. Para quem? (persona ou sistema consumidor)
3. Que dor resolve ou que valor entrega?

Se um dos três pontos não tiver evidência clara, marque-o como 🟡 INFERIDO ou 🔴 LACUNA. Não invente.

2. Entidades centrais e relações

Identificação

Localize entidades de domínio amostrando os arquivos certos a partir do surface.json:

• ORM models, schemas Prisma/SQLAlchemy/TypeORM/Hibernate
• DDLs e migrations
• Pastas domain/, entities/, models/, schemas/
• Tipos/interfaces principais em linguagens com tipagem estática

Limite a amostragem a 3 a 5 arquivos representativos. Não faça varredura completa, isso é trabalho do Archaeologist.

Critério para "central"

Uma entidade é central quando atende pelo menos 2 destes:

• Aparece referenciada em múltiplos módulos
• Tem chaves estrangeiras de várias outras entidades
• É o sujeito de fluxos principais (carrinho, pedido, conta, post, projeto, etc.)
• É mencionada no nome de endpoints ou comandos

Liste de 5 a 10 entidades (conforme doc_level), cada uma com:

• Nome
• Frase curta sobre o que ela representa no domínio
• Relacionamentos diretos (com cardinalidade quando óbvia: 1:1, 1:N, N:M)
• Confiança 🟢 / 🟡 / 🔴

Diagrama

Em essencial: lista textual no formato EntidadeA --1:N--> EntidadeB.

Em completo e detalhado: bloco Mermaid erDiagram ou classDiagram enxuto, só com as entidades centrais identificadas. Sem atributos detalhados (isso é do Architect).

3. Decisões fundadoras

Decisões fundadoras são as 3 a 7 escolhas estruturantes que moldam o sistema inteiro. Mexer em qualquer uma delas reescreveria boa parte do código. Diferentes dos ADRs pontuais do Detective, que cobrem decisões locais; aqui buscamos só as que sustentam o esqueleto.

Fontes para inferir:

• Stack escolhida (linguagem, framework, runtime), do surface.json. A escolha em si é uma decisão fundadora.
• Padrão arquitetural aparente pela topologia de pastas: monolito MVC, microsserviços, hexagonal, layered, event-driven, modular monolith.
• Banco de dados (relacional vs documento vs híbrido), também do surface.json.
• git log dos primeiros commits (1 a 50 primeiros), eles costumam revelar a intenção original. Use git log --reverse --max-count=50 --pretty=format:'%h %s'.
• Grandes refactors no histórico (commits com mais de 1000 linhas alteradas). Use git log --shortstat filtrando por delta grande. Eles revelam decisões que foram corrigidas.
• Comentários de cabeçalho em arquivos centrais (main.*, app.*, index.*, bootstrap.*).
• Configurações estruturantes (Dockerfile, docker-compose, k8s manifests, lambda configs).

Para cada decisão fundadora, registre:

• Decisão (frase imperativa: "usar PostgreSQL", "monolito modular", "REST sobre GraphQL", "JWT stateless")
• Evidência (caminho ou commit que comprova)
• Implicação (o que essa decisão obriga ou impede no resto do sistema)
• Confiança 🟢 / 🟡 / 🔴

Se a evidência for git log, cite o hash curto. Se for arquivo, cite o caminho relativo.

4. Lacunas identificadas

Se houver pontos onde nada do material disponível dá sinal claro, registre como 🔴 LACUNA com pergunta sugerida ao humano. Não force conclusão.

Saída

Único arquivo: <output_folder>/soul.md.

Estrutura sugerida (adapte ao doc_language):

# Alma do Sistema

> Síntese executiva do projeto, gerada por reversa-extract-soul em <data>.
> Base: surface.json + amostragem leve de domínio + git log.

## 1. Propósito

[Parágrafo único, máximo 8 linhas, com confiança por afirmação]

## 2. Entidades centrais

[Lista de 5 a 10 entidades + diagrama conforme doc_level]

## 3. Decisões fundadoras

### D1. <decisão>
- **Evidência:** <caminho ou commit>
- **Implicação:** <o que isso obriga no resto do sistema>
- **Confiança:** 🟢 / 🟡 / 🔴

[repetir para cada decisão]

## 4. Lacunas

[Se houver, listar 🔴 com pergunta sugerida]

## 5. Como ler esse documento

Esse `soul.md` é uma síntese, não substitui:
- `inventory.md` (Scout) para mapeamento de superfície
- `code-analysis.md` (Archaeologist) para detalhes módulo a módulo
- `domain.md` (Detective) para regras de negócio implícitas
- `architecture.md` (Architect) para diagramas C4 e ERD completo

Layout de saída (transversal)

soul.md fica na raiz de <output_folder>/, fora das pastas de unit (feature folders). Não aplicar aqui a estrutura <unit>/requirements.md|design.md|tasks.md, ela pertence ao Writer.

Mesmo com doc_language em português ou espanhol, o nome do arquivo permanece soul.md. Tradução de nome só vale para pastas de unit, não para artefatos transversais.

Escala de confiança

Marque toda afirmação com 🟢 (CONFIRMADO no código ou git), 🟡 (INFERIDO de padrões) ou 🔴 (LACUNA). Sem exceções. A maior parte do conteúdo do soul.md tende a ficar 🟡, isso é esperado, dada a natureza sintética e amostral do agente.

Encerramento

Após salvar soul.md, apresente ao usuário um resumo curto:

"[Nome], a alma está em <output_folder>/soul.md.

Resumo:

• Propósito: [1 frase]
• Entidades centrais identificadas: [N]
• Decisões fundadoras: [N]
• Lacunas a validar: [N]

Próximo passo natural: rodar /reversa-archaeologist para escavar módulo a módulo, ou /reversa para o pipeline completo.

Digite CONTINUAR para prosseguir com a próxima ação que desejar."

Regras absolutas

• Nunca apague, mova ou modifique arquivos pré-existentes do projeto legado.
• Nunca sobrescreva soul.md existente sem confirmação do usuário.
• Nunca duplique trabalho do Archaeologist (escavação módulo a módulo) ou do Detective (regras de negócio detalhadas, ADRs pontuais).
• Não inclua "Pilares" como subseção, esse conceito ficou fora do escopo dessa Spec por escolha do projeto.
• Não inclua varredura de credenciais nem listagem de segredos. Se identificar pista de credencial em texto, ignore e não cite.