spec-first-copilot 0.2.0 → 0.4.0

package/templates/.github/skills/sf-extract/SKILL.md

@@ -1,284 +1,284 @@
----
-name: sf-extract
-description: |
-  Extração de insumos. Lê docs/PM/ e gera PRD ou TRD estruturado.
-  Trigger: /sf-extract
-author: GustavoMaritan
-version: 1.0.0
-date: 2026-04-08
----
-
-# Skill: /sf-extract
-
-> Skill atômica de extração. Lê insumos brutos do PM/ e gera PRD ou TRD.
-> Chamada via orquestrador (/feature, /sf-setup-projeto) ou diretamente para re-extração.
-
-## Tipo
-Atômica — Multi-agent
-
-## Uso
-```
-/sf-extract <nome>
-```
-Exemplo: `/sf-extract feat_cadastro_cliente`
-
----
-
-## Agentes
-
-| Agente | Papel | Modelo | Input | Output |
-|--------|-------|--------|-------|--------|
-| **Reader** | Lê e cataloga 1 arquivo de insumo | Sonnet | 1 arquivo bruto + formato esperado | Resumo estruturado por seção do template |
-| **Analyzer** | Cruza fontes, detecta gaps, gera documento final | Opus | Outputs de todos os Readers + template + contexto do projeto | PRD/TRD completo + extract-log |
-
-### Orquestração
-```
-1. Ler .context.md e .extract-log.md (se existir)
-2. Ler discovery.md (se existir) — análise profunda prévia dos insumos
-3. Inventariar arquivos em docs/PM/{nome}/ → filtrar NOVOS e MODIFICADOS
-4. Spawn 1 Reader por arquivo NOVO/MODIFICADO (paralelo)
-5. Aguardar todos os Readers
-6. Spawn Analyzer com:
-   - Outputs concatenados dos Readers
-   - discovery.md (se existir) — mapa do sistema pré-validado
-   - PRD/TRD existente (se re-extração)
-   - Template (PRD.template.md ou TRD.template.md)
-   - docs/Estrutura/ (contexto do projeto)
-7. Analyzer gera documento final + extract-log
-8. Atualizar .context.md → status: extract_done
-```
-
-> **Se discovery.md existir**: O Analyzer usa o mapa do sistema, perguntas já respondidas
-> e pontos críticos como contexto enriquecido. Resultado: menos ambiguidades, melhor estruturação.
-> **Se não existir**: O Analyzer trabalha normalmente com os outputs dos Readers.
-
-### Agent: Reader (Sonnet)
-
-**Papel**: Especialista em leitura e catalogação de um único arquivo de insumo.
-
-**Comportamento**:
-- Lê 1 arquivo por vez
-- Extrai informações seguindo as categorias do template alvo
-- Não interpreta, não infere — apenas cataloga o que encontra
-- Marca cada informação com a seção do template onde se encaixa
-
-**Formatos e o que extrair:**
-
-| Formato | Extensões | O que extrair |
-|---------|-----------|---------------|
-| Texto/Requisitos | `.md`, `.txt` | Requisitos, regras de negócio, contexto, restrições |
-| Banco de dados | `.sql` | Entidades, campos, tipos, constraints, índices, relações |
-| Protótipos | `.html` | Telas, campos (`data-field`), ações (`data-action`), validações (`data-validation`), rotas (`data-route`), permissões (`data-permission`), estados (`data-state`) |
-| Diagramas | `.xml` (drawio), `.json` | Fluxos, decisões, atores, sequências |
-| Planilhas | `.csv` | Dados tabulares, mapeamentos, configurações |
-| Imagens | `.png`, `.jpg`, `.pdf` | Wireframes, mockups, fluxogramas (análise visual) |
-| Outros | qualquer | Extrair o que for relevante — nunca ignorar um arquivo |
-
-**Output do Reader** (por arquivo):
-```markdown
-## Reader Output: {nome_arquivo}
-- Hash: {sha256_8chars}
-- Formato: {tipo}
-- Status: extraído | parcial | não identificado
-
-### Seções alimentadas:
-- §1 Contexto: ...
-- §3 Entidades: ...
-- §5 Regras: RN-XXX: "descrição"
-- §13 Ambiguidades: "campo X definido mas sem tipo especificado"
-```
-
-**Quando o Reader NÃO consegue extrair conteúdo:**
-- Status: `não identificado` — arquivo binário desconhecido, corrompido, ou sem conteúdo relevante
-- Status: `parcial` — conseguiu extrair algo mas o formato limita (ex: imagem sem OCR, PDF escaneado)
-- O Reader NUNCA ignora o arquivo — sempre registra no output com o status
-- O Analyzer inclui arquivo não identificado no extract-log com classificação `NÃO IDENTIFICADO`
-- O Analyzer gera ambiguidade: "Arquivo {nome} não pôde ser processado — verifique conteúdo e formato"
-
-### Agent: Analyzer (Opus)
-
-**Papel**: Especialista em análise cruzada, detecção de gaps e geração de documento estruturado.
-
-**Comportamento**:
-- Nunca assume — se não está explícito nos insumos, vira pergunta bloqueante
-- Busca contradições ativamente entre fontes diferentes
-- Rastreia tudo — cada informação aponta para o arquivo fonte
-- Prefere estrutura a narrativa — tabelas e listas, nunca texto livre
-- Pessimista construtivo — melhor uma ambiguidade a mais do que uma regra inventada
-
-**Responsabilidades**:
-1. Consolidar outputs dos Readers em visão unificada
-2. Detectar contradições entre fontes → gerar ambiguidade com os dois arquivos citados
-3. Detectar gaps — seções do template sem informação → gerar ambiguidade
-4. **Validar Checklist de Temas Críticos** (ver abaixo) — temas ausentes viram ambiguidades obrigatórias
-5. Nunca inferir regra de negócio — se não está explícito, é ambiguidade
-6. Manter IDs estáveis (RN-001 nunca renumera, novos continuam sequência)
-7. Gerar rastreabilidade completa (§14 PRD / §10 TRD)
-8. Na re-extração: merge ADITIVO com documento existente, marcar seções atualizadas
-
-### Checklist de Temas Críticos (Analyzer)
-
-Após consolidar os Readers, o Analyzer DEVE verificar se os insumos cobrem os temas abaixo.
-Se um tema **não foi mencionado em nenhum insumo**, gera **ambiguidade obrigatória** pedindo ao usuário.
-
-#### Para TRD (setup):
-
-| # | Tema | O que verificar | Se ausente |
-|---|------|-----------------|------------|
-| 1 | **Autenticação** | Qual mecanismo? JWT, OAuth, API Key, Session? | Ambiguidade: "Nenhum mecanismo de autenticação definido nos insumos" |
-| 2 | **Autorização / Roles** | Quais perfis? RBAC, ABAC? Quem acessa o quê? | Ambiguidade: "Perfis de acesso e regras de autorização não definidos" |
-| 3 | **Separação de serviços** | É monolito, microserviços, modular? API e Worker são separados? | Ambiguidade: "Arquitetura de serviços não definida (monolito vs separados)" |
-| 4 | **Ambientes** | Dev, staging, prod? Docker? CI/CD? | Ambiguidade: "Estratégia de ambientes e deploy não definida" |
-| 5 | **Dados sensíveis** | PII, LGPD, criptografia, masking? | Ambiguidade: "Tratamento de dados sensíveis / LGPD não mencionado" |
-
-#### Para PRD (feature):
-
-| # | Tema | O que verificar | Se ausente |
-|---|------|-----------------|------------|
-| 1 | **Autenticação requerida** | Feature exige login? Quais endpoints são públicos vs autenticados? | Ambiguidade: "Não definido quais operações exigem autenticação" |
-| 2 | **Permissões / Roles** | Quais perfis podem executar cada ação? | Ambiguidade: "Não definido quais perfis têm acesso a cada operação" |
-| 3 | **Validações de entrada** | Regras de validação dos campos? Limites? Formatos? | Ambiguidade: "Validações de entrada não detalhadas" |
-| 4 | **Tratamento de erros** | O que acontece quando dá errado? Mensagens ao usuário? | Ambiguidade: "Cenários de erro e mensagens ao usuário não definidos" |
-| 5 | **Impacto em dados existentes** | A feature altera dados existentes? Migração necessária? | Ambiguidade: "Impacto em dados existentes não avaliado" |
-
-> **Regra**: O Analyzer NÃO inventa respostas para esses temas. Se não está nos insumos, PERGUNTA.
-> Esses temas são os mais comuns de serem esquecidos pelo usuário e os mais caros de corrigir depois.
-
----
-
-## Pré-condições
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | Argumento `nome` foi informado | Parar → "Informe o nome. Ex: /sf-extract feat_cadastro_cliente" |
-| 2 | `docs/PM/{nome}/` existe e contém pelo menos 1 arquivo (ignorar .gitkeep) | Parar → "Pasta de insumos vazia ou inexistente" |
-| 3 | `docs/Desenvolvimento/{nome}/.context.md` existe | Parar → "Execute /sf-feature {nome} ou /sf-setup-projeto primeiro" |
-| 4 | Status em `.context.md` é `not_started` ou `extract_done` | Se `approved` ou posterior → "Extração já aprovada. Para re-extrair, o status será revertido para extract_done" |
-
-## Passos detalhados
-
-### 1. Ler contexto
-- Ler `.context.md` → identificar `tipo` (feature ou setup) e `documento` (PRD ou TRD)
-- Ler `docs/Estrutura/` se existir (contexto para extração coerente)
-- Selecionar template: `tipo=feature` → `PRD.template.md` | `tipo=setup` → `TRD.template.md`
-
-### 2. Inventariar e classificar insumos
-Ler todos os arquivos em `docs/PM/{nome}/`. Para cada arquivo, calcular hash (SHA-256 truncado 8 chars).
-
-Se `.extract-log.md` existir, classificar:
-
-| Classificação | Critério | Ação |
-|---------------|----------|------|
-| **NOVO** | Arquivo não existe no log | Processar |
-| **MODIFICADO** | Hash diferente do log | Reprocessar |
-| **INALTERADO** | Hash igual ao log | Pular |
-
-Se `.extract-log.md` não existir: todos são NOVOS.
-
-### 3. Spawn Readers (paralelo)
-Para cada arquivo NOVO ou MODIFICADO, disparar 1 Reader (Sonnet):
-- Input: arquivo bruto + seções do template alvo
-- Output: resumo estruturado por seção
-
-Arquivos INALTERADOS: pular — informação já está no PRD/TRD existente.
-
-### 4. Spawn Analyzer (sequencial)
-Após todos Readers concluírem, disparar Analyzer (Opus) com:
-- Todos os outputs dos Readers
-- PRD/TRD existente (se re-extração — para merge aditivo)
-- Template correspondente
-- `docs/Estrutura/` como contexto
-
-### 5. Gerar/atualizar documento
-
-**Primeira extração:**
-- Analyzer gera PRD.md ou TRD.md completo a partir do template
-
-**Re-extração:**
-- Merge ADITIVO com o documento existente (nunca remove info de arquivos inalterados)
-- Seções afetadas recebem marcador:
-  ```
-  <!-- ATUALIZADO: re-extração {{ISO_DATE}} — arquivos: {lista} -->
-  ```
-- Novas regras de negócio continuam sequência de IDs existentes
-
-### 6. Gerar roadmap de produto faseado (APENAS no setup)
-Quando tipo=setup, o Analyzer encontra informações que não são infraestrutura
-(regras de negócio, jornadas, telas, fluxos). Em vez de descartar, organizar em
-`backlog_extraido.md` como **roadmap faseado** com entregáveis incrementais:
-
-O Analyzer deve:
-1. Identificar funcionalidades, entidades, regras de negócio, jornadas, telas
-2. Mapear dependências entre elas (ex: agendamento depende de cadastro de clientes)
-3. Agrupar em **fases de entrega** por dependência + complexidade
-4. Para cada fase: definir entregável + critério de done
-5. Sugerir **1 feature única** com nome descritivo (ex: `feat_mvp`)
-6. Usar template `backlog-extraido.template.md`
-
-**Princípio**: Entregáveis contínuos — cada fase entrega valor e pode ir pra produção.
-Máximo 4-5 fases. Fase 1 sempre = fundação/cadastros base.
-
-Este arquivo:
-- É gerado APENAS no setup (não em features)
-- Serve como roadmap quando o usuário for criar `/feature`
-- O /sf-extract da feature usa as fases como referência para o PRD
-
-### 7. Gerar/atualizar `.extract-log.md`
-
-```markdown
-# Extract Log — {nome}
-
-## Extração 1 — {{ISO_DATETIME}}
-| Arquivo | Hash | Classificação | Seções alimentadas |
-|---------|------|---------------|-------------------|
-| requisitos.txt | a1b2c3d4 | NOVO | §1, §5, §9 |
-| modelagem.sql | e5f6g7h8 | NOVO | §3, §6 |
-
-## Extração 2 — {{ISO_DATETIME}}
-| Arquivo | Hash | Classificação | Seções alimentadas |
-|---------|------|---------------|-------------------|
-| novas_regras.md | m3n4o5p6 | NOVO | §5, §9 |
-| modelagem.sql | q7r8s9t0 | MODIFICADO | §3 |
-| requisitos.txt | a1b2c3d4 | INALTERADO | — |
-```
-
-### 7. Atualizar `.context.md`
-```yaml
-status: "extract_done"
-ultima_skill: "/sf-extract"
-atualizado_em: "{{ISO_DATETIME}}"
-```
-
----
-
-## Saídas
-
-| Arquivo | Descrição |
-|---------|-----------|
-| `PRD.md` ou `TRD.md` | Documento de extração com todas as seções preenchidas |
-| `.extract-log.md` | Registro de arquivos processados com hashes e classificação |
-| `.context.md` | Atualizado com status `extract_done` |
-
-## Pós-condições
-- Documento gerado com rastreabilidade completa
-- Ambiguidades listadas na seção correspondente — bloqueiam avanço no `/design`
-- Usuário deve revisar antes de chamar `/design`
-
-## Erros
-
-| Erro | Ação |
-|------|------|
-| PM/{nome}/ vazio | Parar, listar formatos aceitos |
-| .context.md não existe | Parar, sugerir /sf-feature ou /sf-setup-projeto |
-| Nenhum arquivo novo/modificado | Informar "Nenhuma alteração detectada desde a última extração" |
-| Formato não reconhecido | Processar mesmo assim, extrair o que for possível, avisar no log |
-| Conteúdo não identificado | Registrar como NÃO IDENTIFICADO no extract-log, gerar ambiguidade pedindo ao usuário verificar o arquivo |
-| Extração parcial | Registrar como PARCIAL no extract-log, extrair o que for possível, avisar quais seções ficaram incompletas |
-| Contradição entre arquivos | Analyzer gera ambiguidade citando os dois arquivos e a contradição |
-
-## Notas
-- O `/extract` é a ÚNICA skill que lê `docs/PM/` — nenhuma outra skill acessa insumos brutos
-- Na re-extração, o merge é ADITIVO — nunca remove informação de arquivos inalterados
-- Para recomeçar do zero: apagar PRD/TRD e .extract-log.md manualmente
-- Readers são stateless — não conhecem outros arquivos, apenas o seu
-- Analyzer é quem tem visão global e detecta contradições cross-arquivo
+---
+name: sf-extract
+description: |
+  Extração de insumos. Lê docs/PM/ e gera PRD ou TRD estruturado.
+  Trigger: /sf-extract
+author: GustavoMaritan
+version: 1.0.0
+date: 2026-04-08
+---
+
+# Skill: /sf-extract
+
+> Skill atômica de extração. Lê insumos brutos do PM/ e gera PRD ou TRD.
+> Chamada via orquestrador (/feature, /sf-setup-projeto) ou diretamente para re-extração.
+
+## Tipo
+Atômica — Multi-agent
+
+## Uso
+```
+/sf-extract <nome>
+```
+Exemplo: `/sf-extract feat_cadastro_cliente`
+
+---
+
+## Agentes
+
+| Agente | Papel | Modelo | Input | Output |
+|--------|-------|--------|-------|--------|
+| **Reader** | Lê e cataloga 1 arquivo de insumo | Sonnet | 1 arquivo bruto + formato esperado | Resumo estruturado por seção do template |
+| **Analyzer** | Cruza fontes, detecta gaps, gera documento final | Opus | Outputs de todos os Readers + template + contexto do projeto | PRD/TRD completo + extract-log |
+
+### Orquestração
+```
+1. Ler .context.md e .extract-log.md (se existir)
+2. Ler discovery.md (se existir) — análise profunda prévia dos insumos
+3. Inventariar arquivos em docs/PM/{nome}/ → filtrar NOVOS e MODIFICADOS
+4. Spawn 1 Reader por arquivo NOVO/MODIFICADO (paralelo)
+5. Aguardar todos os Readers
+6. Spawn Analyzer com:
+   - Outputs concatenados dos Readers
+   - discovery.md (se existir) — mapa do sistema pré-validado
+   - PRD/TRD existente (se re-extração)
+   - Template (PRD.template.md ou TRD.template.md)
+   - docs/Estrutura/ (contexto do projeto)
+7. Analyzer gera documento final + extract-log
+8. Atualizar .context.md → status: extract_done
+```
+
+> **Se discovery.md existir**: O Analyzer usa o mapa do sistema, perguntas já respondidas
+> e pontos críticos como contexto enriquecido. Resultado: menos ambiguidades, melhor estruturação.
+> **Se não existir**: O Analyzer trabalha normalmente com os outputs dos Readers.
+
+### Agent: Reader (Sonnet)
+
+**Papel**: Especialista em leitura e catalogação de um único arquivo de insumo.
+
+**Comportamento**:
+- Lê 1 arquivo por vez
+- Extrai informações seguindo as categorias do template alvo
+- Não interpreta, não infere — apenas cataloga o que encontra
+- Marca cada informação com a seção do template onde se encaixa
+
+**Formatos e o que extrair:**
+
+| Formato | Extensões | O que extrair |
+|---------|-----------|---------------|
+| Texto/Requisitos | `.md`, `.txt` | Requisitos, regras de negócio, contexto, restrições |
+| Banco de dados | `.sql` | Entidades, campos, tipos, constraints, índices, relações |
+| Protótipos | `.html` | Telas, campos (`data-field`), ações (`data-action`), validações (`data-validation`), rotas (`data-route`), permissões (`data-permission`), estados (`data-state`) |
+| Diagramas | `.xml` (drawio), `.json` | Fluxos, decisões, atores, sequências |
+| Planilhas | `.csv` | Dados tabulares, mapeamentos, configurações |
+| Imagens | `.png`, `.jpg`, `.pdf` | Wireframes, mockups, fluxogramas (análise visual) |
+| Outros | qualquer | Extrair o que for relevante — nunca ignorar um arquivo |
+
+**Output do Reader** (por arquivo):
+```markdown
+## Reader Output: {nome_arquivo}
+- Hash: {sha256_8chars}
+- Formato: {tipo}
+- Status: extraído | parcial | não identificado
+
+### Seções alimentadas:
+- §1 Contexto: ...
+- §3 Entidades: ...
+- §5 Regras: RN-XXX: "descrição"
+- §13 Ambiguidades: "campo X definido mas sem tipo especificado"
+```
+
+**Quando o Reader NÃO consegue extrair conteúdo:**
+- Status: `não identificado` — arquivo binário desconhecido, corrompido, ou sem conteúdo relevante
+- Status: `parcial` — conseguiu extrair algo mas o formato limita (ex: imagem sem OCR, PDF escaneado)
+- O Reader NUNCA ignora o arquivo — sempre registra no output com o status
+- O Analyzer inclui arquivo não identificado no extract-log com classificação `NÃO IDENTIFICADO`
+- O Analyzer gera ambiguidade: "Arquivo {nome} não pôde ser processado — verifique conteúdo e formato"
+
+### Agent: Analyzer (Opus)
+
+**Papel**: Especialista em análise cruzada, detecção de gaps e geração de documento estruturado.
+
+**Comportamento**:
+- Nunca assume — se não está explícito nos insumos, vira pergunta bloqueante
+- Busca contradições ativamente entre fontes diferentes
+- Rastreia tudo — cada informação aponta para o arquivo fonte
+- Prefere estrutura a narrativa — tabelas e listas, nunca texto livre
+- Pessimista construtivo — melhor uma ambiguidade a mais do que uma regra inventada
+
+**Responsabilidades**:
+1. Consolidar outputs dos Readers em visão unificada
+2. Detectar contradições entre fontes → gerar ambiguidade com os dois arquivos citados
+3. Detectar gaps — seções do template sem informação → gerar ambiguidade
+4. **Validar Checklist de Temas Críticos** (ver abaixo) — temas ausentes viram ambiguidades obrigatórias
+5. Nunca inferir regra de negócio — se não está explícito, é ambiguidade
+6. Manter IDs estáveis (RN-001 nunca renumera, novos continuam sequência)
+7. Gerar rastreabilidade completa (§14 PRD / §10 TRD)
+8. Na re-extração: merge ADITIVO com documento existente, marcar seções atualizadas
+
+### Checklist de Temas Críticos (Analyzer)
+
+Após consolidar os Readers, o Analyzer DEVE verificar se os insumos cobrem os temas abaixo.
+Se um tema **não foi mencionado em nenhum insumo**, gera **ambiguidade obrigatória** pedindo ao usuário.
+
+#### Para TRD (setup):
+
+| # | Tema | O que verificar | Se ausente |
+|---|------|-----------------|------------|
+| 1 | **Autenticação** | Qual mecanismo? JWT, OAuth, API Key, Session? | Ambiguidade: "Nenhum mecanismo de autenticação definido nos insumos" |
+| 2 | **Autorização / Roles** | Quais perfis? RBAC, ABAC? Quem acessa o quê? | Ambiguidade: "Perfis de acesso e regras de autorização não definidos" |
+| 3 | **Separação de serviços** | É monolito, microserviços, modular? API e Worker são separados? | Ambiguidade: "Arquitetura de serviços não definida (monolito vs separados)" |
+| 4 | **Ambientes** | Dev, staging, prod? Docker? CI/CD? | Ambiguidade: "Estratégia de ambientes e deploy não definida" |
+| 5 | **Dados sensíveis** | PII, LGPD, criptografia, masking? | Ambiguidade: "Tratamento de dados sensíveis / LGPD não mencionado" |
+
+#### Para PRD (feature):
+
+| # | Tema | O que verificar | Se ausente |
+|---|------|-----------------|------------|
+| 1 | **Autenticação requerida** | Feature exige login? Quais endpoints são públicos vs autenticados? | Ambiguidade: "Não definido quais operações exigem autenticação" |
+| 2 | **Permissões / Roles** | Quais perfis podem executar cada ação? | Ambiguidade: "Não definido quais perfis têm acesso a cada operação" |
+| 3 | **Validações de entrada** | Regras de validação dos campos? Limites? Formatos? | Ambiguidade: "Validações de entrada não detalhadas" |
+| 4 | **Tratamento de erros** | O que acontece quando dá errado? Mensagens ao usuário? | Ambiguidade: "Cenários de erro e mensagens ao usuário não definidos" |
+| 5 | **Impacto em dados existentes** | A feature altera dados existentes? Migração necessária? | Ambiguidade: "Impacto em dados existentes não avaliado" |
+
+> **Regra**: O Analyzer NÃO inventa respostas para esses temas. Se não está nos insumos, PERGUNTA.
+> Esses temas são os mais comuns de serem esquecidos pelo usuário e os mais caros de corrigir depois.
+
+---
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | Argumento `nome` foi informado | Parar → "Informe o nome. Ex: /sf-extract feat_cadastro_cliente" |
+| 2 | `docs/PM/{nome}/` existe e contém pelo menos 1 arquivo (ignorar .gitkeep) | Parar → "Pasta de insumos vazia ou inexistente" |
+| 3 | `docs/Desenvolvimento/{nome}/.context.md` existe | Parar → "Execute /sf-feature {nome} ou /sf-setup-projeto primeiro" |
+| 4 | Status em `.context.md` é `not_started` ou `extract_done` | Se `approved` ou posterior → "Extração já aprovada. Para re-extrair, o status será revertido para extract_done" |
+
+## Passos detalhados
+
+### 1. Ler contexto
+- Ler `.context.md` → identificar `tipo` (feature ou setup) e `documento` (PRD ou TRD)
+- Ler `docs/Estrutura/` se existir (contexto para extração coerente)
+- Selecionar template: `tipo=feature` → `PRD.template.md` | `tipo=setup` → `TRD.template.md`
+
+### 2. Inventariar e classificar insumos
+Ler todos os arquivos em `docs/PM/{nome}/`. Para cada arquivo, calcular hash (SHA-256 truncado 8 chars).
+
+Se `.extract-log.md` existir, classificar:
+
+| Classificação | Critério | Ação |
+|---------------|----------|------|
+| **NOVO** | Arquivo não existe no log | Processar |
+| **MODIFICADO** | Hash diferente do log | Reprocessar |
+| **INALTERADO** | Hash igual ao log | Pular |
+
+Se `.extract-log.md` não existir: todos são NOVOS.
+
+### 3. Spawn Readers (paralelo)
+Para cada arquivo NOVO ou MODIFICADO, disparar 1 Reader (Sonnet):
+- Input: arquivo bruto + seções do template alvo
+- Output: resumo estruturado por seção
+
+Arquivos INALTERADOS: pular — informação já está no PRD/TRD existente.
+
+### 4. Spawn Analyzer (sequencial)
+Após todos Readers concluírem, disparar Analyzer (Opus) com:
+- Todos os outputs dos Readers
+- PRD/TRD existente (se re-extração — para merge aditivo)
+- Template correspondente
+- `docs/Estrutura/` como contexto
+
+### 5. Gerar/atualizar documento
+
+**Primeira extração:**
+- Analyzer gera PRD.md ou TRD.md completo a partir do template
+
+**Re-extração:**
+- Merge ADITIVO com o documento existente (nunca remove info de arquivos inalterados)
+- Seções afetadas recebem marcador:
+  ```
+  <!-- ATUALIZADO: re-extração {{ISO_DATE}} — arquivos: {lista} -->
+  ```
+- Novas regras de negócio continuam sequência de IDs existentes
+
+### 6. Gerar roadmap de produto faseado (APENAS no setup)
+Quando tipo=setup, o Analyzer encontra informações que não são infraestrutura
+(regras de negócio, jornadas, telas, fluxos). Em vez de descartar, organizar em
+`backlog_extraido.md` como **roadmap faseado** com entregáveis incrementais:
+
+O Analyzer deve:
+1. Identificar funcionalidades, entidades, regras de negócio, jornadas, telas
+2. Mapear dependências entre elas (ex: agendamento depende de cadastro de clientes)
+3. Agrupar em **fases de entrega** por dependência + complexidade
+4. Para cada fase: definir entregável + critério de done
+5. Sugerir **1 feature única** com nome descritivo (ex: `feat_mvp`)
+6. Usar template `backlog-extraido.template.md`
+
+**Princípio**: Entregáveis contínuos — cada fase entrega valor e pode ir pra produção.
+Máximo 4-5 fases. Fase 1 sempre = fundação/cadastros base.
+
+Este arquivo:
+- É gerado APENAS no setup (não em features)
+- Serve como roadmap quando o usuário for criar `/feature`
+- O /sf-extract da feature usa as fases como referência para o PRD
+
+### 7. Gerar/atualizar `.extract-log.md`
+
+```markdown
+# Extract Log — {nome}
+
+## Extração 1 — {{ISO_DATETIME}}
+| Arquivo | Hash | Classificação | Seções alimentadas |
+|---------|------|---------------|-------------------|
+| requisitos.txt | a1b2c3d4 | NOVO | §1, §5, §9 |
+| modelagem.sql | e5f6g7h8 | NOVO | §3, §6 |
+
+## Extração 2 — {{ISO_DATETIME}}
+| Arquivo | Hash | Classificação | Seções alimentadas |
+|---------|------|---------------|-------------------|
+| novas_regras.md | m3n4o5p6 | NOVO | §5, §9 |
+| modelagem.sql | q7r8s9t0 | MODIFICADO | §3 |
+| requisitos.txt | a1b2c3d4 | INALTERADO | — |
+```
+
+### 7. Atualizar `.context.md`
+```yaml
+status: "extract_done"
+ultima_skill: "/sf-extract"
+atualizado_em: "{{ISO_DATETIME}}"
+```
+
+---
+
+## Saídas
+
+| Arquivo | Descrição |
+|---------|-----------|
+| `PRD.md` ou `TRD.md` | Documento de extração com todas as seções preenchidas |
+| `.extract-log.md` | Registro de arquivos processados com hashes e classificação |
+| `.context.md` | Atualizado com status `extract_done` |
+
+## Pós-condições
+- Documento gerado com rastreabilidade completa
+- Ambiguidades listadas na seção correspondente — bloqueiam avanço no `/design`
+- Usuário deve revisar antes de chamar `/design`
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| PM/{nome}/ vazio | Parar, listar formatos aceitos |
+| .context.md não existe | Parar, sugerir /sf-feature ou /sf-setup-projeto |
+| Nenhum arquivo novo/modificado | Informar "Nenhuma alteração detectada desde a última extração" |
+| Formato não reconhecido | Processar mesmo assim, extrair o que for possível, avisar no log |
+| Conteúdo não identificado | Registrar como NÃO IDENTIFICADO no extract-log, gerar ambiguidade pedindo ao usuário verificar o arquivo |
+| Extração parcial | Registrar como PARCIAL no extract-log, extrair o que for possível, avisar quais seções ficaram incompletas |
+| Contradição entre arquivos | Analyzer gera ambiguidade citando os dois arquivos e a contradição |
+
+## Notas
+- O `/extract` é a ÚNICA skill que lê `docs/PM/` — nenhuma outra skill acessa insumos brutos
+- Na re-extração, o merge é ADITIVO — nunca remove informação de arquivos inalterados
+- Para recomeçar do zero: apagar PRD/TRD e .extract-log.md manualmente
+- Readers são stateless — não conhecem outros arquivos, apenas o seu
+- Analyzer é quem tem visão global e detecta contradições cross-arquivo