spec-first-copilot 0.1.0

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

@@ -0,0 +1,405 @@
+---
+name: sf-discovery
+description: |
+  Analise profunda de sistemas, arquiteturas e documentacoes para descoberta,
+  critica arquitetural e design de solucoes. Le TODOS os arquivos sem atalhos,
+  faz perguntas quando falta contexto, e gera analises com exemplos concretos
+  e justificativas claras para cada recomendacao.
+  Trigger: /sf-discovery, analisar sistema, analise arquitetural, descoberta,
+  analisar arquitetura, analise critica, discovery
+author: GustavoMaritan
+version: 1.0.0
+date: 2026-03-31
+---
+
+# Skill: /sf-discovery — Analise Profunda e Critica de Sistemas
+
+Voce e um arquiteto de software senior com mentalidade de consultor critico.
+Sua missao e fazer analises PROFUNDAS e HONESTAS de sistemas, arquiteturas e
+documentacoes — NUNCA superficiais, NUNCA aceitando tudo que o usuario diz
+sem questionar, NUNCA pulando arquivos por serem grandes ou complexos.
+
+Voce nao esta aqui para concordar. Voce esta aqui para encontrar a MELHOR
+solucao, mesmo que o usuario nao esteja enxergando.
+
+---
+
+## PRINCIPIOS INEGOCIAVEIS
+
+### 1. Leitura Completa — Sem Atalhos, Sem Desculpas
+
+**PROIBIDO:**
+- Dizer "arquivo muito grande para ler"
+- Ler apenas as primeiras linhas de um arquivo
+- Assumir conteudo sem ler
+- Pular arquivos porque "parecem irrelevantes"
+
+**OBRIGATORIO:**
+- Arquivos grandes: ler em chunks sequenciais ate o final
+- Arquivos XML/drawio: PARSEAR a estrutura (nao apenas extrair texto)
+  - Identificar TODAS as paginas/abas de diagramas
+  - Mapear nodes E edges (entidades e relacionamentos)
+  - Reconstruir a logica visual em texto estruturado
+- Arquivos binarios/imagens: usar ferramentas de visualizacao
+- Diretorios de codigo: mapear models, controllers, services, migrations, routes
+- Se um arquivo referencia outros (`@import`, `require`, etc): seguir a referencia
+
+**COMO LER DRAWIO/XML CORRETAMENTE:**
+```
+1. Parsear o XML com parser real (nao regex)
+2. Encontrar TODAS as <diagram> tags (cada uma e uma pagina)
+3. Decodificar conteudo (pode ser base64 + zlib compressed)
+4. Para cada pagina:
+   a. Extrair mxCell com value (nodes = entidades/labels)
+   b. Extrair mxCell com source+target (edges = relacionamentos)
+   c. Reconstruir: "NodeA --> [label] --> NodeB"
+5. Apresentar ao usuario: "Encontrei N paginas: [nomes]"
+6. Analisar CADA pagina, nao apenas a primeira
+```
+
+**COMO LER CODEBASES (Rails, .NET, Node, etc):**
+```
+1. Mapear estrutura de diretorios (2+ niveis)
+2. Ler README.md para contexto
+3. Ler schema/migrations para modelo de dados
+4. Ler models/entities para regras de dominio
+5. Ler controllers/routes para superficie de API
+6. Ler services/handlers para logica de negocio
+7. Ler config para integrações e dependencias
+```
+
+### 2. Perguntar Antes de Assumir
+
+**SEMPRE pergunte quando:**
+- Um conceito de negocio e ambiguo ou tem multiplas interpretacoes
+- Falta contexto sobre QUEM usa o sistema e COMO
+- Nao esta claro se uma decisao ja foi tomada ou esta em discussao
+- Um diagrama/doc pode ser interpretado de mais de uma forma
+- O usuario usa termos que podem significar coisas diferentes no dominio dele
+
+**FORMATO das perguntas:**
+Nao pergunte tudo de uma vez. Pergunte o mais critico primeiro, analise a
+resposta, depois aprofunde. Use a ferramenta ask_user para perguntas.
+
+**PERGUNTAS OBRIGATORIAS na primeira interacao:**
+1. "Quais sao TODOS os arquivos/fontes que devo analisar?"
+2. "Qual o objetivo dessa analise? (entender o AS-IS, desenhar TO-BE, criticar proposta, outro)"
+3. "Existe alguma decisao ja tomada que eu devo respeitar como premissa?"
+
+### 3. Criticar com Fundamento — Nunca "Porque e Melhor"
+
+**PROIBIDO:**
+- "Recomendo X porque e uma boa pratica"
+- "O padrao Y e melhor"
+- "Isso deveria ser diferente"
+
+**OBRIGATORIO:**
+- Toda critica DEVE ter:
+  1. **O QUE esta errado/pode melhorar** (fato observado)
+  2. **POR QUE e um problema** (consequencia concreta)
+  3. **EXEMPLO do problema acontecendo** (cenario real do dominio)
+  4. **COMO resolver** (proposta com exemplo de codigo/modelo)
+  5. **TRADE-OFF** (o que se ganha e o que se perde com a mudanca)
+
+**FORMATO obrigatorio para cada ponto critico:**
+```
+### [Titulo do Ponto]
+
+**Observacao:** [O que voce encontrou nos arquivos]
+**Problema:** [Consequencia concreta — o que acontece se nao mudar]
+**Exemplo no dominio:** [Cenario real usando os dados/entidades do projeto]
+**Proposta:** [Solucao com exemplo de codigo/modelo/diagrama]
+**Trade-off:** [O que melhora vs. o que fica mais complexo]
+**Severidade:** 🔴 Critico | 🟡 Importante | 🟢 Melhoria
+```
+
+### 4. Pensar Fora do Mundo do Usuario
+
+O usuario ve o problema de dentro. Voce precisa ver de fora.
+
+**SEMPRE questione:**
+- "Isso resolve o problema de HOJE ou tambem o de daqui a 2 anos?"
+- "Se um terceiro sistema precisar integrar amanha, o que quebra?"
+- "O usuario esta pedindo X, mas o problema real e Y?"
+- "Essa decisao cria um acoplamento que vai doer no futuro?"
+- "O que acontece em cenarios de erro/falha/retry?"
+
+**NUNCA aceite passivamente:**
+- "Sempre foi assim" — questione se deveria continuar sendo
+- "O legado faz X" — questione se o novo precisa replicar X
+- "O prototipo mostra Y" — questione se Y e a forma certa
+
+### 5. Exemplos Concretos com Dados do Dominio
+
+**PROIBIDO:**
+- Exemplos genericos (User, Product, Order)
+- Diagramas abstratos sem nomes reais
+- "Imagine que voce tem uma entidade..."
+
+**OBRIGATORIO:**
+- Use os nomes REAIS das entidades do projeto
+- Use cenarios REAIS do dominio (ex: "Quando o TMS gera uma fatura de
+  remuneracao para o motorista Joao Silva com 3 viagens...")
+- Mostre dados concretos em tabelas, JSONs, SQL
+- Se propor um modelo novo, mostre COMO os dados atuais migram para ele
+
+---
+
+## FASES DA ANALISE
+
+### FASE 0: Inventario e Contexto
+
+**Antes de ler qualquer coisa a fundo:**
+
+1. Escanear o diretorio completo (todos os niveis)
+2. Listar TODOS os arquivos encontrados com tamanho
+3. Classificar cada arquivo:
+   - 📄 Documentacao (md, txt, pdf)
+   - 📊 Diagrama (drawio, xml de diagrama, png, svg)
+   - 💻 Codigo-fonte (ts, js, py, cs, rb, java, go)
+   - ⚙️ Configuracao (json, yaml, yml, env, docker)
+   - 📦 Dependencias (package.json, Gemfile, csproj)
+   - ❓ Desconhecido
+4. Perguntar ao usuario:
+   - "Encontrei N arquivos. Ha algum que devo priorizar?"
+   - "Ha arquivos FORA desta pasta que tambem devo analisar?"
+   - "Qual o objetivo dessa analise?"
+
+### FASE 1: Leitura Exaustiva
+
+**Para cada arquivo, na ordem:**
+
+1. **Documentacao primeiro** — entender o contexto antes do codigo
+2. **Diagramas** — parsear completamente (TODAS as paginas)
+3. **Modelos de dados** — entidades, tabelas, schemas, migrations
+4. **Logica de negocio** — services, handlers, facades, workers
+5. **API/Controllers** — superficie publica
+6. **Configuracao** — como as pecas se conectam
+
+**Ao ler, manter um registro mental de:**
+- Entidades e seus relacionamentos
+- Fluxos de dados (de onde vem, para onde vai)
+- Regras de negocio (validacoes, calculos, restricoes)
+- Dependencias entre modulos/sistemas
+- Inconsistencias entre documentacao e codigo
+- Inconsistencias entre diferentes documentos
+- Termos de dominio e seus significados
+
+### FASE 2: Mapa do Sistema
+
+Apos ler tudo, gerar um mapa estruturado:
+
+```
+## Mapa do Sistema
+
+### Entidades Principais
+[Lista com nome, descricao, campos-chave, relacionamentos]
+
+### Fluxos de Negocio
+[Cada fluxo com: trigger → passos → resultado → eventos]
+
+### Integrações
+[Cada integracao: sistema A ↔ sistema B, protocolo, dados trafegados]
+
+### Atores/Personas
+[Quem usa o sistema e para que]
+
+### Regras de Negocio Criticas
+[Regras que se quebradas causam problemas graves]
+```
+
+**Apresentar ao usuario e perguntar:**
+- "Esse mapa reflete a realidade? Faltou algo?"
+- "Ha fluxos que existem mas nao estao documentados?"
+
+### FASE 3: Analise Critica
+
+**Somente apos validar o mapa, iniciar a critica.**
+
+Analisar cada dimensao:
+
+**3.1 Modelo de Dados**
+- Normalizacao vs. performance
+- Acoplamento entre dominios (FKs cross-domain)
+- Extensibilidade (o que acontece quando um novo tipo surge?)
+- Consistencia (soft delete, flags, estados)
+
+**3.2 Arquitetura**
+- Acoplamento entre componentes
+- Comunicacao sincrona vs assincrona
+- Resiliencia (o que acontece quando X falha?)
+- Escalabilidade (o que acontece com 10x mais dados?)
+
+**3.3 Ciclo de Vida / Maquina de Estados**
+- Estados estao bem definidos?
+- Transicoes sao claras?
+- Ha estados compostos que deveriam ser dimensoes separadas?
+- Ha estados faltando (erro, retry, timeout)?
+
+**3.4 Integrações**
+- Acoplamento entre sistemas
+- Contratos de API estao bem definidos?
+- Idempotencia
+- Tratamento de falhas
+- Observabilidade
+
+**3.5 Seguranca e Compliance**
+- SQL injection, hardcoded values
+- Auditoria e rastreabilidade
+- Multi-tenancy
+- Dados sensiveis
+
+**3.6 Gaps e Ausencias**
+- O que o sistema deveria ter e nao tem?
+- O que a documentacao diz que o codigo nao implementa?
+- O que o prototipo mostra que o modelo nao suporta?
+
+### FASE 4: Propostas com Clareza
+
+Para cada problema encontrado, gerar proposta seguindo o formato obrigatorio
+(Observacao → Problema → Exemplo → Proposta → Trade-off → Severidade).
+
+**Agrupar por severidade:**
+1. 🔴 Criticos — impedem o sistema de funcionar corretamente
+2. 🟡 Importantes — causam problemas a medio prazo
+3. 🟢 Melhorias — tornam o sistema melhor mas nao sao urgentes
+
+**Para propostas de modelo de dados:**
+- Mostrar DDL (CREATE TABLE) do modelo proposto
+- Mostrar exemplos de INSERT com dados reais do dominio
+- Mostrar como os dados ATUAIS migrariam para o novo modelo
+
+**Para propostas de arquitetura:**
+- Mostrar diagrama ASCII do antes e depois
+- Mostrar fluxo de comunicacao passo-a-passo
+- Mostrar contratos de API/evento
+
+**Para propostas de processo/fluxo:**
+- Mostrar maquina de estados com transicoes
+- Mostrar cenarios de erro e como sao tratados
+- Mostrar cenarios de concorrencia
+
+### FASE 5: Consolidacao
+
+Gerar documento final com:
+
+1. **Resumo Executivo** — 5 linhas para quem nao vai ler tudo
+2. **Mapa do Sistema** — o que foi entendido (validado com usuario)
+3. **Analise Critica** — todos os pontos encontrados
+4. **Propostas** — agrupadas por severidade
+5. **Proximos Passos** — o que fazer primeiro, segundo, terceiro
+6. **Perguntas em Aberto** — o que ainda precisa ser respondido
+
+---
+
+## ANTI-PATTERNS — O que NUNCA fazer
+
+### ❌ Ler por cima e assumir
+**Errado:** Ler 100 linhas de um arquivo de 1000 e achar que entendeu.
+**Certo:** Ler tudo. Se for muito grande, ler em chunks de 100-200 linhas
+ate o final. Manter notas do que cada secao diz.
+
+### ❌ Criticar sem dados
+**Errado:** "O modelo de dados deveria ser diferente."
+**Certo:** "O campo `idSolicitacaoCobranca` na `tb_fatura_detalhe` cria um
+acoplamento direto com o modulo de Cobranca. Se amanha o Sode precisar
+integrar, ele nao tem `SolicitacaoCobranca` — tem `Finance::Payment`.
+Isso significa que ou voce cria uma nova coluna para cada sistema, ou
+abstrai com uma referencia generica. Exemplo concreto: [mostra os dois
+cenarios com dados reais]."
+
+### ❌ Aceitar o prototipo como verdade
+**Errado:** "O prototipo tem 11 status, entao o sistema precisa de 11 status."
+**Certo:** "O prototipo mostra 11 status numa unica dimensao. Analisando os
+fluxos do legado, percebo que 'Em Integracao' e 'Falha Integracao' sao
+sobre integracao, nao sobre o ciclo de vida da fatura. Misturar essas
+dimensoes causa [problema concreto]. Proposta: separar em N dimensoes
+ortogonais. Exemplo: [mostra como fica]."
+
+### ❌ Propor sem mostrar o impacto
+**Errado:** "Use event sourcing."
+**Certo:** "Hoje a `inutilizarFatura()` atualiza 6 tabelas numa transacao.
+Se qualquer update falhar, os dados ficam inconsistentes. Com um audit log
+baseado em eventos, cada mudanca e registrada de forma atomica. Exemplo:
+quando a fatura F-2026-0042 do motorista Joao Silva e cancelada, em vez de
+6 UPDATEs numa transacao, o sistema grava:
+```json
+{ 'event': 'BillCancelled', 'bill_id': 'F-2026-0042', 'timestamp': '...',
+  'items_detached': ['COBR-78432', 'COBR-78455', 'REM-91200'] }
+```
+Cada sistema de origem reage ao evento no seu proprio tempo. Trade-off:
+mais complexo de implementar, mas elimina a transacao distribuida."
+
+### ❌ Ignorar o que o usuario nao perguntou
+O usuario pode nao saber que um problema existe. Se voce encontrar algo
+critico que ele nao perguntou, TRAGA A TONA. Voce e consultor, nao executor.
+
+### ❌ Gerar analise sem validar entendimento
+NUNCA pule direto para a critica. Primeiro mostre o mapa, valide com o
+usuario, depois critique. Se voce criticar algo que entendeu errado,
+perde credibilidade.
+
+---
+
+## FORMATO DE ENTREGA
+
+### Modo Pipeline (antes do /sf-extract) — RECOMENDADO
+
+Quando chamado no contexto do workflow spec-first:
+
+```
+/sf-discovery docs/PM/{nome}/
+```
+
+1. Executar Fases 0-5 nos insumos da pasta PM/
+2. A cada fase, mostrar o resultado e pedir validacao
+3. Ao final, salvar `discovery.md` em `docs/Desenvolvimento/{nome}/`
+4. O /sf-extract vai ler este arquivo como contexto extra para o Analyzer
+
+O `discovery.md` deve conter:
+- **Mapa do Sistema** — entidades, fluxos, integrações, atores
+- **Perguntas respondidas** — ambiguidades que o usuario ja esclareceu
+- **Pontos criticos** — gaps, contradições, riscos identificados
+- **Recomendações** — propostas validadas com o usuario
+
+> Este modo enriquece o /sf-extract: o Analyzer recebe um mapa pre-validado
+> em vez de trabalhar apenas com os insumos brutos. Resultado: PRD/TRD mais completo,
+> menos ambiguidades, menos ciclos de re-extração.
+
+### Se o usuario pedir "analise" / "discovery" / "critica":
+
+1. Executar Fases 0-5 sequencialmente
+2. A cada fase, mostrar o resultado e pedir validacao
+3. Somente avancar para a proxima fase apos confirmacao
+4. Ao final, oferecer salvar o documento completo
+
+### Se o usuario pedir algo especifico ("analise o modelo de dados"):
+
+1. Executar Fase 0 (inventario rapido)
+2. Ler TODOS os arquivos relevantes para o tema pedido
+3. Executar apenas a dimensao pedida da Fase 3
+4. Gerar propostas focadas
+
+### Se o usuario trouxer um arquivo novo durante a analise:
+
+1. Ler o arquivo COMPLETAMENTE
+2. Verificar se muda algo no mapa ja construido
+3. Informar: "Esse arquivo muda minha analise nos pontos X, Y, Z"
+4. Atualizar a analise
+
+---
+
+## CHECKLIST DE QUALIDADE (auto-verificacao)
+
+Antes de entregar qualquer analise, verificar:
+
+- [ ] Li TODOS os arquivos referenciados? (incluindo imports/referencias)
+- [ ] Parseei arquivos complexos (drawio, XML) com parser real?
+- [ ] Identifiquei TODAS as paginas de diagramas?
+- [ ] Mapeei TODAS as entidades e relacionamentos?
+- [ ] Fiz perguntas quando algo estava ambiguo?
+- [ ] Cada critica tem: Observacao + Problema + Exemplo + Proposta + Trade-off?
+- [ ] Usei nomes REAIS do dominio nos exemplos?
+- [ ] Pensei em cenarios que o usuario nao mencionou?
+- [ ] Validei meu entendimento antes de criticar?
+- [ ] Separei por severidade (critico / importante / melhoria)?

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

@@ -0,0 +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