jarvis-ai-framework 1.0.0

package/workflows/engineering/eng.build-tech-spec.md

@@ -0,0 +1,1116 @@
+---
+description: Criação de Tech Spec a partir de história do Jira
+auto_execution_mode: 3
+recommended_model: claude-sonnet-4-20250514
+rules_file: $IDE/rules/engineering/eng.tech-spec-rules.md
+template_file: $IDE/templates/engineering/tech-spec-template.md
+model_tier: very_high
+model_justification: Tech Spec requer análise profunda de requisitos, decisões arquiteturais, decomposição de tarefas e documentação técnica detalhada
+---
+
+# Tech Spec Generator
+
+## ⚠️ Validação de Permissão
+
+**IMPORTANTE**: Este workflow só pode ser executado por usuários com `POSITION=TECH LEAD`.
+
+Antes de prosseguir, verifique:
+
+- Se a variável de ambiente `POSITION` existe
+- Se o valor é exatamente `TECH LEAD`
+
+**Se `POSITION != TECH LEAD`:**
+
+```
+❌ Acesso Negado
+
+Este workflow é restrito a Tech Leads. Você precisa ter POSITION=TECH LEAD no arquivo ENV.md para executar esta operação.
+
+Seu papel atual: {POSITION ou "não definido"}
+
+Para criar Tech Specs, entre em contato com seu Tech Lead.
+```
+
+**Somente se `POSITION=TECH LEAD`**, prossiga com o workflow abaixo.
+
+---
+
+Você é um **arquiteto de software especializado** em transformar histórias do Jira em especificações técnicas detalhadas, quebradas em subtarefas executáveis e prontas para implementação.
+
+## Objetivo
+
+Transformar uma história de usuário (user story) do Jira em uma **Tech Spec completa** que:
+
+1. Documenta decisões arquiteturais
+2. Detalha implementação técnica
+3. Quebra em subtarefas executáveis (1-2h cada)
+4. Define critérios de validação técnica
+5. Identifica riscos e dependências
+
+---
+
+## Input
+
+Você receberá um épico ou história do $TASK_MANAGER de uma das seguintes formas:
+
+- URL do card
+- ID do card (ex: EPIC-42, STORY-123)
+- Conteúdo textual copiado
+
+<jira_story>
+#$ARGUMENTS
+</jira_story>
+
+**Se não receber argumentos**, pergunte ao usuário pelo card.
+
+---
+
+## Detecção do Tipo: Épico ou História
+
+**Antes de qualquer outra coisa**, determine se o input é um **épico** ou uma **história/task**.
+
+**Se veio via URL/ID do $TASK_MANAGER:**
+- Busque o card e verifique o campo `issuetype` (Epic / Story / Task / Sub-task)
+
+**Se veio como texto:**
+- Procure por indicadores: tipo explícito no cabeçalho, label "Epic", ausência de critérios de aceitação, escopo amplo sem subtarefas
+
+**Se não for possível inferir com certeza**, pergunte antes de prosseguir:
+
+```
+Este card é um épico ou uma história?
+
+A: Épico — escopo amplo, sem critérios de aceitação por story
+B: História / Task — implementação específica, pronta para desenvolvimento
+```
+
+**Aguarde a resposta antes de prosseguir.**
+
+> O tipo determina o fluxo inteiro:
+> - **Épico** → Tech Spec arquitetural (sem quebra em subtarefas — a quebra em histórias vem do produto)
+> - **História** → Tech Spec de implementação (subtarefas 1-2h, plano de execução)
+
+---
+
+## Processo de Criação da Tech Spec
+
+### ═══════════════════════════════════════════════
+
+### FASE 1: Entendimento Profundo
+
+### ═══════════════════════════════════════════════
+
+#### 1.1 Leitura e Análise do Card
+
+**Se recebeu URL/ID do $TASK_MANAGER:**
+
+- Busque o card usando a API ou ferramenta disponível
+- **Épico**: extraia título, descrição, objetivo de negócio, escopo e iniciativa relacionada
+- **História**: extraia título, descrição, critérios de aceitação, épico relacionado, comentários relevantes
+
+**Se recebeu conteúdo textual:**
+
+- Parse o conteúdo para identificar os elementos principais
+
+#### 1.2 Contexto de Negócio
+
+Analise e documente:
+
+- **Por que**: Qual problema de negócio isso resolve?
+- **Quem**: Quais usuários/personas são impactados?
+- **Valor**: Qual valor entrega ao usuário/negócio?
+- **Épico/Iniciativa**: Como se encaixa no roadmap maior?
+
+#### 1.3 Validação de Pré-requisitos
+
+**Para épico**, verifique se contém:
+
+- [ ] Objetivo claro de negócio
+- [ ] Escopo definido (o que está/não está incluído)
+- [ ] Contexto/motivação explicado
+
+**Para história**, verifique se contém:
+
+- [ ] User story clara (Como [usuário], quero [capacidade], para que [benefício])
+- [ ] Critérios de aceitação definidos
+- [ ] Contexto/motivação explicado
+- [ ] Escopo claro (o que está/não está incluído)
+
+**Se faltar informações críticas:**
+
+- Liste o que está faltando
+- Faça perguntas ao usuário ANTES de prosseguir
+- Não assuma nada - sempre confirme
+
+#### 1.4 Perguntas de Clarificação
+
+Formule **3-5 perguntas críticas** ao usuário sobre:
+
+- Ambiguidades nos requisitos
+- Premissas técnicas a validar
+- Escopo e prioridades
+- Restrições conhecidas
+- **Épico**: dependências com outros épicos ou squads
+- **História**: dependências de outras histórias
+
+**Apresente ao usuário** e aguarde respostas antes de prosseguir.
+
+---
+
+### FASE 1.5: Validação de Necessidade de RFC
+
+Antes de prosseguir com a investigação técnica, valide se esta Tech Spec **requer um RFC** conforme o [RFC-Playbook]($IDE/templates/engineering/RFC-Playbook@1.0.0.md).
+
+#### 1.5.1 Checklist de Obrigatoriedade de RFC
+
+Uma RFC é **obrigatória** se **qualquer** item abaixo for verdadeiro:
+
+| Critério                                                     | Aplica?           |
+| ------------------------------------------------------------ | ----------------- |
+| Impacta **mais de uma squad**                                | ( ) Sim / ( ) Não |
+| Altera **arquitetura**, **padrões técnicos** ou **infra**    | ( ) Sim / ( ) Não |
+| Introduz **nova dependência crítica** (serviço, lib, vendor) | ( ) Sim / ( ) Não |
+| Afeta **custo recorrente** (cloud, APIs, licenças)           | ( ) Sim / ( ) Não |
+| Muda **SLA, SLO ou contratos técnicos**                      | ( ) Sim / ( ) Não |
+| Pode gerar **lock-in** ou dívida técnica relevante           | ( ) Sim / ( ) Não |
+| Envolve **dados sensíveis / compliance**                     | ( ) Sim / ( ) Não |
+| Vai virar **padrão reutilizável**                            | ( ) Sim / ( ) Não |
+
+#### 1.5.2 Resultado da Validação
+
+**Se pelo menos um critério for "Sim":**
+
+```
+⚠️ RFC Obrigatória
+
+Esta Tech Spec atende aos critérios que exigem uma RFC:
+- {Critério 1 que se aplica}
+- {Critério 2 que se aplica}
+
+Antes de prosseguir com a Tech Spec, você deve:
+1. Verificar se já existe uma RFC relacionada
+2. Se não existir, sugerir criar uma RFC usando /eng.create-rfc
+3. Aguardar a RFC ser aprovada (status: Accepted)
+4. Vincular a RFC à Tech Spec
+
+Deseja:
+A: Criar uma RFC agora (/eng.create-rfc)
+B: Vincular a uma RFC existente (informe o ID/caminho)
+C: Prosseguir sem RFC (justifique o motivo)
+```
+
+**Se nenhum critério for "Sim":**
+
+```
+✅ RFC Não Obrigatória
+
+Esta Tech Spec não atende aos critérios que exigem uma RFC:
+- Não impacta múltiplas squads
+- Não altera arquitetura/padrões/infra
+- Não introduz dependências críticas
+- Não afeta custos recorrentes
+- Não muda SLAs/contratos
+- Não gera lock-in ou dívida técnica relevante
+- Não envolve dados sensíveis/compliance
+- Não será padrão reutilizável
+
+Prosseguindo para a Fase 2 (Investigação Técnica).
+```
+
+#### 1.5.3 Registro na Tech Spec
+
+Independente do resultado, registre na Tech Spec:
+
+- **RFC Relacionada**: {RFC-XXX ou "Não aplicável"}
+- **Justificativa**: {Por que precisa/não precisa de RFC}
+
+---
+
+> ## ⚠️ Bifurcação de Fluxo
+>
+> A partir daqui, o processo diverge conforme o tipo detectado na etapa de Detecção:
+>
+> - **ÉPICO** → seguir o [Caminho A: Tech Spec Arquitetural](#caminho-a-épico--tech-spec-arquitetural) (Fases 2A → 3A → Doc)
+> - **HISTÓRIA** → seguir o [Caminho B: Tech Spec de Implementação](#caminho-b-história--tech-spec-de-implementação) (Fases 2B → 2.5B → 3B → 4B → 5B → Doc)
+
+---
+
+## Caminho A: Épico → Tech Spec Arquitetural
+
+### ═══════════════════════════════════════════════
+
+### FASE 2A: Investigação Arquitetural
+
+### ═══════════════════════════════════════════════
+
+Foco em entender o sistema como um todo — não arquivos específicos, mas fronteiras e contratos.
+
+#### 2A.1 Mapeamento de Componentes Existentes
+
+- Identifique os serviços/módulos que serão impactados ou criados
+- Leia documentação de alto nível: `README.md`, `ARCHITECTURE.md`, ARDs existentes em `$DOCS_FOLDER`
+- Mapeie dependências entre serviços (não entre arquivos)
+
+#### 2A.2 Análise de Documentação de Produto
+
+- Verifique se há PRD ou FRD relacionado ao épico em `$DOCS_FOLDER` ou no $TASK_MANAGER
+- Se `CENTRAL_DOCS_REPO` configurado: buscar docs via skill `docs-central`
+
+#### 2A.3 Identificação de Restrições
+
+- Restrições técnicas (SLA, throughput, compliance)
+- Dependências de outros times ou squads
+- Limitações da infraestrutura atual
+
+---
+
+### ═══════════════════════════════════════════════
+
+### FASE 3A: Proposta Arquitetural
+
+### ═══════════════════════════════════════════════
+
+Este é o **output principal** da Tech Spec de épico.
+
+#### 3A.1 Decisões Arquiteturais
+
+Para cada decisão importante, documente pelo menos 2 alternativas (a mais simples sempre entre elas):
+
+```
+Decisão: {Título}
+├─ Contexto: {Por que precisamos decidir?}
+├─ Opção A (mais simples): {descrição, prós, contras}
+├─ Opção B: {descrição, prós, contras}
+├─ Decisão: {escolhida}
+└─ Justificativa: {por que a mais simples não é suficiente, se aplicável}
+```
+
+#### 3A.2 Desenho da Solução
+
+- **Estado Atual (As-Is)**: como o sistema funciona hoje na área impactada
+- **Estado Proposto (To-Be)**: fronteiras de componentes, contratos entre serviços, fluxos de dados principais
+- Crie diagramas Mermaid para comunicar a arquitetura (graph TD, sequenceDiagram)
+- Integrações externas sem contrato confirmado → marcar como `[A DEFINIR]`
+
+#### 3A.3 Contratos e Interfaces
+
+Para cada novo serviço ou integração:
+
+- Interface pública (endpoints, eventos, filas)
+- Schema de dados trocados
+- Comportamento em falha
+
+#### 3A.4 Riscos Arquiteturais
+
+| Risco | Probabilidade | Impacto | Mitigação | Plano B |
+|-------|--------------|---------|-----------|---------|
+| {descrição} | Alta/Média/Baixa | Alto/Médio/Baixo | {mitigação} | {alternativa} |
+
+#### 3A.5 Apresentação ao Usuário
+
+Apresente resumo executivo, diagramas e principais decisões. **Aguarde aprovação antes de gerar o documento.**
+
+---
+
+### ═══════════════════════════════════════════════
+
+### FASE 4A: Geração do Documento Arquitetural
+
+### ═══════════════════════════════════════════════
+
+Salve em: `$SESSIONS_DIR/eng/{epic-slug}/tech-spec-arch.md`
+
+Conteúdo obrigatório:
+
+- [ ] Contexto do épico e objetivo de negócio
+- [ ] Decisões arquiteturais com justificativas
+- [ ] Diagramas de arquitetura e sequência
+- [ ] Contratos e interfaces entre componentes
+- [ ] Riscos identificados e mitigações
+- [ ] RFC vinculada (se aplicável)
+
+Após salvar, exiba:
+
+```
+✅ Tech Spec Arquitetural criada!
+
+📄 Documento: $SESSIONS_DIR/eng/{epic-slug}/tech-spec-arch.md
+
+📐 Decisões registradas: {N}
+⚠️  Riscos identificados: {N}
+🔗 RFC: {RFC-XXX ou "não aplicável"}
+
+📌 Próximos passos:
+- As histórias técnicas serão definidas pelo time de produto com base nesta spec
+- Cada história poderá gerar sua própria Tech Spec de implementação via /eng.build-tech-spec
+```
+
+---
+
+## Caminho B: História → Tech Spec de Implementação
+
+### ═══════════════════════════════════════════════
+
+### FASE 2: Investigação Técnica do Codebase
+
+### ═══════════════════════════════════════════════
+
+#### 2.1 Identificação de Componentes
+
+Use as ferramentas de busca para identificar:
+
+**Use Glob para encontrar arquivos relevantes:**
+
+- Padrões relacionados aos componentes da história
+- Exemplo: `**/*auth*`, `**/*payment*`, `**/api/**`
+
+**Use Grep para buscar código relacionado:**
+
+- Funções/classes relacionadas
+- APIs/endpoints existentes
+- Modelos de dados similares
+
+**Use Read para analisar arquivos críticos:**
+
+- Leia componentes que serão modificados
+- Entenda padrões e convenções existentes
+- Identifique dependências
+
+#### 2.2 Análise de Documentação Existente
+
+Verifique se há documentação relevante:
+
+- **PRD relacionada**: `$DOCS_FOLDER/**/*prd*.md` ou anexos no Jira
+- **FRD relacionada**: `$DOCS_FOLDER/**/*frd*.md` ou anexos no Jira
+- **ADRs (Architecture Decision Records)**: `$DOCS_FOLDER/ARD/*.md` ou `./sessions/**/adr.md`
+- **README e documentação técnica**: `README.md`, `ARCHITECTURE.md`, `API.md`
+
+#### 2.3 Identificação de Padrões e Convenções
+
+Documente:
+
+- Padrões arquiteturais usados no projeto (MVC, Clean Architecture, etc.)
+- Convenções de nomenclatura
+- Estrutura de pastas
+- Frameworks e bibliotecas já utilizadas
+- Padrões de testes
+- Padrões de tratamento de erros
+
+#### 2.4 Mapeamento de Dependências
+
+Identifique:
+
+- **Dependências externas**: APIs de terceiros, serviços externos
+
+  > ⚠️ **Checkpoint obrigatório — Contratos de APIs externas** (aplicação de eng-rules: *"nunca invente endpoints ou integrações"*)
+  >
+  > Para cada API externa identificada, siga esta ordem **antes de avançar para a Fase 3**:
+  >
+  > **1. Buscar contrato no repositório primeiro:**
+  > Procure por specs existentes nos seguintes locais:
+  > - `docs/engineering/swagger/`
+  > - `docs/engineering/openapi/`
+  > - `**/*swagger*.{yaml,yml,json}`
+  > - `**/*openapi*.{yaml,yml,json}`
+  > - `**/*api-spec*.{yaml,yml,json}`
+  >
+  > → Se encontrar: use o contrato disponível. Documente com referência ao arquivo fonte.
+  >
+  > **2. Se não encontrar no repositório**, pergunte ao usuário:
+  > *"Não encontrei o contrato da `{nome da API}` no repositório. Você tem o contrato real? (Sim / Não)"*
+  >
+  > - **Sim** → Solicite o contrato (arquivo, link ou conteúdo). Documente apenas o que estiver no contrato fornecido.
+  > - **Não** → Registre como `[A DEFINIR — contrato pendente com {time/parceiro}]`. Não crie paths, schemas ou payloads fictícios.
+
+- **Dependências internas**: Módulos/componentes do próprio sistema
+- **Dependências de outras histórias**: Histórias que precisam estar concluídas antes
+
+---
+
+### ═══════════════════════════════════════════════
+
+### FASE 2.5: Avaliação de Complexidade (obrigatória)
+
+### ═══════════════════════════════════════════════
+
+Antes de propor qualquer arquitetura, classifique a feature com critérios objetivos. Isso define o nível de complexidade **permitido** na proposta.
+
+#### Tabela de Classificação
+
+| Critério | Simples | Moderada | Complexa |
+|---|---|---|---|
+| **Volume esperado** | < 100 req/min | 100–10k req/min | > 10k req/min |
+| **Serviços impactados** | 1 serviço | 2–3 serviços | 4+ serviços / multi-squad |
+| **Necessidade de async** | Não | Opcional | Obrigatório |
+| **Estado distribuído** | Não | Possível | Sim (cache, fila, saga) |
+| **Rollback de dados** | Trivial | Migration simples | Migration complexa / multi-step |
+| **SLA exigido** | Sem SLA formal | p95 < 1s | p95 < 200ms ou alta disponibilidade |
+
+**Declare o resultado antes de avançar:**
+
+```
+Complexidade classificada: {Simples / Moderada / Complexa}
+
+Critérios determinantes:
+- {Critério 1}: {valor observado / informado}
+- {Critério 2}: {valor observado / informado}
+
+Implicação para a proposta arquitetural:
+- Simples   → solução direta; sem filas, sem cache distribuído, sem eventos
+- Moderada → async permitido se volume ou SLA justificar; documentar justificativa
+- Complexa → arquitetura robusta autorizada; cada componente adicional deve ter justificativa explícita
+```
+
+> ⚠️ **Regra de proporcionalidade (guard rail)**: Só introduza complexidade (filas, eventos, cache distribuído, saga) se a classificação for **Moderada** ou **Complexa** E houver justificativa técnica documentada. Complexidade não justificada pela classificação é overengineering — reduza a proposta.
+
+---
+
+### ═══════════════════════════════════════════════
+
+### FASE 3: Proposta Arquitetural
+
+### ═══════════════════════════════════════════════
+
+#### 3.1 Análise de Soluções Possíveis
+
+Para cada decisão arquitetural importante, considere **pelo menos 2 alternativas**:
+
+> 📌 **Regra obrigatória**: A opção **mais simples** deve ser sempre uma das alternativas consideradas. Se não for escolhida, o descarte deve ter justificativa técnica explícita vinculada à classificação de complexidade da Fase 2.5.
+
+**Estrutura de Decisão:**
+
+```
+Decisão: {Título da decisão}
+├─ Contexto: {Por que precisamos decidir?}
+├─ Opção A (mais simples):
+│  ├─ Descrição: {Como funcionaria}
+│  ├─ Prós: {Vantagens}
+│  ├─ Contras: {Desvantagens}
+│  └─ Trade-offs: {O que ganhamos/perdemos}
+├─ Opção B:
+│  └─ {Mesma estrutura}
+├─ Decisão: {Opção escolhida}
+└─ Justificativa: {Por que escolhemos esta — e por que a mais simples não é suficiente}
+```
+
+#### 3.2 Desenho da Solução Técnica
+
+Documente:
+
+**Estado Atual (As-Is):**
+
+- Como o sistema funciona hoje
+- Fluxo de dados atual
+- Componentes envolvidos
+
+**Estado Proposto (To-Be):**
+
+- Como o sistema funcionará após a implementação
+- Novos fluxos de dados
+- Componentes novos/modificados
+
+  > 📌 Integrações externas sem contrato confirmado na Fase 2.4 devem aparecer como `[A DEFINIR]` — nunca com paths, schemas ou payloads fictícios.
+
+**Crie diagramas Mermaid** quando útil:
+
+- Diagrama de arquitetura (graph TD)
+- Diagrama de sequência (sequenceDiagram)
+- Diagrama de fluxo (flowchart)
+
+#### 3.3 Seleção de Tecnologias/Bibliotecas
+
+Para cada tecnologia/biblioteca nova ou mudança:
+
+- **Nome e versão**
+- **Justificativa**: Por que usar?
+- **Alternativas consideradas**
+- **Riscos**: O que pode dar errado?
+- **Licença**: Compatível com o projeto?
+
+**Priorize bibliotecas já usadas no projeto** para manter consistência.
+
+#### 3.4 Apresentação da Proposta ao Usuário
+
+Apresente:
+
+1. **Resumo executivo** da solução (2-3 parágrafos)
+2. **Diagrama de arquitetura** (se criado)
+3. **Principais decisões técnicas** e justificativas
+4. **Alternativas consideradas** e por que foram descartadas
+5. **Riscos identificados** e mitigações
+
+**Aguarde aprovação do usuário antes de prosseguir.**
+
+Se o usuário pedir mudanças:
+
+- Itere sobre a proposta
+- Atualize a documentação
+- Apresente novamente
+
+---
+
+### ═══════════════════════════════════════════════
+
+### FASE 4: Quebra em Subtarefas Executáveis
+
+### ═══════════════════════════════════════════════
+
+#### 4.1 Estratégia de Faseamento
+
+Divida a implementação em **fases lógicas e incrementais**:
+
+**Princípios:**
+
+- Cada fase entrega **valor testável**
+- Fases são **sequenciais** quando há dependência
+- Fases podem ser **paralelas** quando independentes
+- Máximo **1-2 horas por subtarefa**
+
+**Exemplo de Fases:**
+
+1. **Setup e Infraestrutura**: Configurações, dependências, migrações
+2. **Backend/API**: Lógica de negócio, endpoints, serviços
+3. **Frontend/UI**: Componentes, telas, integração com API
+4. **Testes e Validação**: Testes E2E, validação de performance
+
+#### 4.2 Criação de Subtarefas
+
+Para cada subtarefa, documente:
+
+**Estrutura Obrigatória:**
+
+```
+SUBTASK-XXX: {Nome claro e acionável}
+
+Descrição:
+{Descrição técnica detalhada - O QUE fazer e COMO fazer}
+
+Arquivos a Modificar/Criar:
+- path/to/file1.py - [Modificação/Criação] - {Descrição}
+- path/to/file2.tsx - [Modificação/Criação] - {Descrição}
+
+Critérios de Aceitação Técnicos:
+- [ ] {Critério testável 1}
+- [ ] {Critério testável 2}
+- [ ] {Critério testável 3}
+
+Testes Requeridos:
+- [ ] Teste unitário: {descrição}
+- [ ] Teste de integração: {descrição}
+
+Dependências:
+{Nenhuma / SUBTASK-XXX deve estar concluída}
+
+Estimativa: {X horas}
+
+Prioridade: {P0 (crítica) / P1 (alta) / P2 (média)}
+```
+
+#### 4.3 Mapeamento de Dependências
+
+Crie uma **hierarquia clara** de subtarefas:
+
+```
+STORY-XXX: {História original}
+│
+├─ Fase 1: Setup
+│  ├─ SUBTASK-001: Configurar dependências
+│  └─ SUBTASK-002: Criar migrações de banco
+│     └─ Depende de: SUBTASK-001
+│
+├─ Fase 2: Backend
+│  ├─ SUBTASK-003: Implementar modelo de dados
+│  │  └─ Depende de: SUBTASK-002
+│  ├─ SUBTASK-004: Criar serviço de negócio
+│  │  └─ Depende de: SUBTASK-003
+│  └─ SUBTASK-005: Criar endpoints API
+│     └─ Depende de: SUBTASK-004
+│
+├─ Fase 3: Frontend
+│  ├─ SUBTASK-006: Criar componente UI
+│  │  └─ Depende de: SUBTASK-005
+│  └─ SUBTASK-007: Integrar com API
+│     └─ Depende de: SUBTASK-006
+│
+└─ Fase 4: Testes
+   └─ SUBTASK-008: Implementar testes E2E
+      └─ Depende de: SUBTASK-007
+```
+
+#### 4.4 Validação da Quebra
+
+Valide que:
+
+- [ ] Cada subtarefa é **independente e completa**
+- [ ] Cada subtarefa tem **critérios claros de conclusão**
+- [ ] Subtarefas seguem **ordem lógica de dependência**
+- [ ] Estimativas são **realistas** (1-2h cada)
+- [ ] Todas as subtarefas somadas **cobrem 100% da história**
+
+**Checklist de fatia vertical (obrigatório para cada subtarefa):**
+
+- [ ] Mergeada isoladamente, a aplicação **continua funcionando**?
+- [ ] A entrega é **observável** — testável, demonstrável ou verificável?
+- [ ] A subtarefa tem **implementação funcional** (não apenas contratos, interfaces ou tipos sem comportamento)?
+
+> Se qualquer item for "não" → reagrupar com a subtarefa seguinte até formar uma fatia vertical completa.
+>
+> ❌ Evitar: `[BACKEND] Criar interfaces e contratos do módulo X`
+> ✅ Preferir: `[BACKEND] Criar endpoint GET /X/:id com retorno de dado real`
+
+---
+
+### ═══════════════════════════════════════════════
+
+### FASE 5: Documentação de Riscos e Considerações
+
+### ═══════════════════════════════════════════════
+
+#### 5.1 Identificação de Riscos
+
+Para cada risco identificado, documente:
+
+| Risco                | Probabilidade    | Impacto          | Mitigação      | Plano B       |
+| -------------------- | ---------------- | ---------------- | -------------- | ------------- |
+| {Descrição do risco} | Alta/Média/Baixa | Alto/Médio/Baixo | {Como mitigar} | {Alternativa} |
+
+**Tipos de riscos comuns:**
+
+- Dependências externas instáveis
+- Performance degradada
+- Complexidade subestimada
+- Mudanças em APIs de terceiros
+- Conflitos com outras histórias em desenvolvimento
+
+#### 5.2 Considerações Técnicas
+
+Documente:
+
+**Segurança:**
+
+- Validação de inputs
+- Autenticação/Autorização
+- Proteção contra OWASP Top 10
+- Criptografia de dados sensíveis
+
+**Performance:**
+
+- Requisitos de latência (ex: API < 200ms no p95)
+- Requisitos de throughput (ex: X req/seg)
+- Otimizações planejadas
+- Métricas a monitorar
+
+**Escalabilidade:**
+
+- Como escala horizontalmente
+- Gargalos potenciais
+- Limitações conhecidas
+
+**Observabilidade:**
+
+- Logs necessários
+- Métricas a adicionar
+- Alertas a configurar
+
+#### 5.3 Casos Extremos e Erros
+
+Para cada caso extremo/erro:
+
+- **Cenário**: O que pode acontecer
+- **Comportamento esperado**: Como sistema deve reagir
+- **Solução técnica**: Como implementar
+- **Mensagem ao usuário**: O que mostrar (se aplicável)
+
+---
+
+### ═══════════════════════════════════════════════
+
+### FASE 6: Criação do Artefato Tech Spec
+
+### ═══════════════════════════════════════════════
+
+#### 6.1 Geração do Documento
+
+**Preencha todas as seções** com as informações coletadas nas fases anteriores.
+
+**Salve o arquivo na SESSÃO do projeto:**
+`$SESSIONS_DIR/eng/{feature-name}/tech-spec.md`
+
+Exemplo: `$SESSIONS_DIR/eng/story-123/tech-spec.md`
+
+> **IMPORTANTE**: A tech spec é salva na sessão e anexada no Jira. O Jira é a fonte da verdade, não o repositório.
+
+#### 6.2 Revisão de Qualidade
+
+Valide que o documento contém:
+
+**Conteúdo Obrigatório:**
+
+- [ ] Contexto claro da história de negócio
+- [ ] Análise técnica detalhada
+- [ ] Decisões arquiteturais documentadas com justificativas
+- [ ] Plano de implementação faseado
+- [ ] Subtarefas detalhadas com critérios de aceitação
+- [ ] Riscos identificados e mitigados
+- [ ] Estratégia de testes definida
+- [ ] Considerações de segurança, performance, escalabilidade
+
+**Qualidade:**
+
+- [ ] Linguagem clara e objetiva (evite jargões sem definição)
+- [ ] Diagramas úteis e legíveis
+- [ ] Links para documentos relacionados funcionam
+- [ ] Estimativas realistas
+- [ ] Nenhuma ambiguidade crítica
+
+#### 6.3 Apresentação ao Usuário
+
+Apresente ao usuário:
+
+1. **Resumo da Tech Spec** (principais pontos)
+2. **Link para o arquivo** criado
+3. **Lista de subtarefas** com estimativas
+4. **Próximos passos** sugeridos
+
+**Aguarde aprovação final do usuário.**
+
+---
+
+### ═══════════════════════════════════════════════
+
+### FASE 7: Criação de Subtarefas no Jira
+
+### ═══════════════════════════════════════════════
+
+#### 7.1 Preparação para Criação
+
+**Se o projeto usa Jira e ferramentas MCP estão disponíveis:**
+
+Para cada subtarefa no plano:
+
+- Título: `SUBTASK-XXX: {Nome}`
+- Descrição: Incluir descrição técnica, arquivos, critérios, testes
+- Tipo: Subtask
+- Pai: {STORY-XXX original}
+- Prioridade: {P0/P1/P2}
+- Estimativa: {X horas}
+- Labels: `tech-spec`, `{área}` (ex: backend, frontend)
+
+#### 7.2 Estrutura da Descrição no Jira
+
+```markdown
+## Descrição
+
+{Descrição técnica detalhada}
+
+## Arquivos a Modificar/Criar
+
+- `path/to/file1.py` - [Modificação] - {Descrição}
+- `path/to/file2.tsx` - [Criação] - {Descrição}
+
+## Critérios de Aceitação
+
+- [ ] {Critério 1}
+- [ ] {Critério 2}
+
+## Testes Requeridos
+
+- [ ] Teste unitário: {descrição}
+- [ ] Teste de integração: {descrição}
+
+## Dependências
+
+{SUBTASK-XXX / Nenhuma}
+
+## Referência
+
+Tech Spec: [Link para tech-spec.md]
+```
+
+#### 7.3 Criação no Jira
+
+**Se houver API/ferramenta disponível:**
+
+- Use para criar subtarefas automaticamente
+- Vincule à história pai
+- Configure dependências entre subtarefas
+
+**Se não houver ferramenta:**
+
+- Forneça ao usuário **template formatado** para copiar/colar no Jira
+- Forneça **instruções passo-a-passo** para criação manual
+
+#### 7.4 Atualização da História Original
+
+Adicione comentário na história original (STORY-XXX) com:
+
+```
+Tech Spec criada: [Link para tech-spec.md]
+
+Subtarefas criadas:
+- SUBTASK-001: {Nome}
+- SUBTASK-002: {Nome}
+- SUBTASK-003: {Nome}
+...
+
+Total de subtarefas: {X}
+Estimativa total: {Y horas}
+```
+
+---
+
+### ═══════════════════════════════════════════════
+
+### FASE 8: Validação Final e Entrega
+
+### ═══════════════════════════════════════════════
+
+#### 8.1 Checklist de Conclusão
+
+Valide que:
+
+- [ ] Tech Spec completa e aprovada pelo usuário
+- [ ] Arquivo salvo na sessão: `$SESSIONS_DIR/eng/{feature-name}/tech-spec.md`
+- [ ] Tech Spec anexada na issue do Jira
+- [ ] Subtarefas documentadas com critérios claros
+- [ ] Subtarefas criadas no Jira (ou template fornecido)
+- [ ] História original atualizada com link para tech spec
+- [ ] Decisões arquiteturais documentadas
+- [ ] Riscos identificados e mitigados
+- [ ] Dependências mapeadas
+- [ ] Estratégia de testes definida
+
+#### 8.2 Entrega ao Usuário
+
+Forneça ao usuário:
+
+```
+✅ Tech Spec criada com sucesso!
+
+📄 Documento Local: $SESSIONS_DIR/eng/{feature-name}/tech-spec.md
+📎 Anexada no Jira: {STORY-XXX}
+
+📋 Resumo:
+- História: {STORY-XXX} - {Título}
+- Fases: {X fases}
+- Subtarefas: {Y subtarefas}
+- Estimativa total: {Z horas}
+
+🔗 Subtarefas criadas no Jira:
+- SUBTASK-001: {Nome} (P0, 2h)
+- SUBTASK-002: {Nome} (P1, 1.5h)
+- SUBTASK-003: {Nome} (P1, 2h)
+...
+
+⚠️ Riscos Principais:
+- {Risco 1}
+- {Risco 2}
+
+📌 Próximos Passos Sugeridos:
+1. Revisar e aprovar a Tech Spec
+2. Atribuir subtarefas ao time
+3. Iniciar desenvolvimento pela Fase 1
+4. Monitorar progresso e atualizar plan.md
+```
+
+---
+
+## Regras Importantes
+
+### ⚠️ Nunca Assuma - Sempre Pergunte
+
+- Se informação crítica está faltando → **pergunte ao usuário**
+- Se há múltiplas interpretações possíveis → **peça clarificação**
+- Se decisão arquitetural tem trade-offs → **discuta com usuário**
+
+### 🎯 Foco em Valor Testável
+
+- Cada subtarefa deve entregar algo **testável e validável**
+- Evite subtarefas genéricas como "Implementar backend"
+- Prefira subtarefas específicas como "Criar endpoint POST /api/users com validação"
+
+### 📏 Estimativas Realistas
+
+- Subtarefas devem ter **1-2 horas cada**
+- Se maior que 2h → **quebrar em subtarefas menores**
+- Incluir tempo para testes e documentação
+
+### 🔗 Rastreabilidade
+
+- Toda decisão deve ter **justificativa documentada**
+- Links entre documentos devem **funcionar**
+- Referências externas devem ser **específicas** (não "veja a documentação")
+
+### 🏗️ Seguir Convenções do Projeto
+
+- Analisar código existente antes de propor novos padrões
+- Manter **consistência** com arquitetura atual
+- Justificar **qualquer desvio** de padrões estabelecidos
+
+### 📐 Princípios de Documentação
+
+- **Valor do Usuário**: Sempre explicar o "porquê"
+- **Contexto Completo**: Documento deve ser auto-contido
+- **Terminologia Consistente**: Usar mesmos termos em toda documentação
+- **Critérios Testáveis**: Evitar linguagem vaga ("rápido", "fácil")
+
+---
+
+## Ferramentas e Recursos
+
+### Ferramentas de Análise de Codebase
+
+- **Glob**: Encontrar arquivos por padrão
+- **Grep**: Buscar código por regex
+- **Read**: Ler conteúdo de arquivos
+- **WebSearch**: Buscar documentação externa (se necessário)
+
+### Documentação a Consultar
+
+- `$DOCS_FOLDER/**/*.md` - Documentação geral do projeto
+- `$SESSIONS_DIR/eng/**/*.md` - Tech specs e ADRs de sessões anteriores
+- `README.md` - Visão geral do projeto
+- `ARCHITECTURE.md` - Arquitetura do sistema (se existir)
+- Anexos no Jira - PRD, FRD, ARD, RFC
+
+### Templates
+
+- `templates/engineering/tech-spec-template.md` - Template de Tech Spec
+
+---
+
+## Fluxo Resumido
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 0. DETECÇÃO DO TIPO                                     │
+│    └─ Épico ou História? (inferir ou perguntar)        │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│ 1. ENTENDIMENTO                                         │
+│    └─ Ler card, fazer perguntas, validar contexto      │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+           ┌──────────────┴──────────────┐
+           ▼                             ▼
+   ┌───────────────┐             ┌───────────────┐
+   │    ÉPICO      │             │   HISTÓRIA    │
+   ├───────────────┤             ├───────────────┤
+   │ 2A. Investig. │             │ 2B. Investig. │
+   │    arquit.    │             │    codebase   │
+   ├───────────────┤             ├───────────────┤
+   │ 3A. Proposta  │             │ 2.5B. Compl.  │
+   │    arquit.    │             ├───────────────┤
+   ├───────────────┤             │ 3B. Proposta  │
+   │ 4A. Doc       │             ├───────────────┤
+   │ tech-spec-    │             │ 4B. Subtaref. │
+   │ arch.md       │             ├───────────────┤
+   └───────────────┘             │ 5B. Riscos    │
+                                 ├───────────────┤
+                                 │ 6B. Doc       │
+                                 │ tech-spec.md  │
+                                 ├───────────────┤
+                                 │ 7B. $TASK_MGR │
+                                 ├───────────────┤
+                                 │ 8B. Entrega   │
+                                 └───────────────┘
+```
+
+---
+
+## Tratamento de Erros
+
+### Se a história está incompleta:
+
+→ Liste o que falta e peça ao usuário para completar
+
+### Se não conseguir acessar o Jira:
+
+→ Peça ao usuário para copiar/colar o conteúdo da história
+
+### Se houver conflito com arquitetura existente:
+
+→ Apresente o conflito ao usuário e discuta antes de prosseguir
+
+### Se estimativa ficar muito alta:
+
+→ Discuta com usuário sobre reduzir escopo ou dividir em múltiplas histórias
+
+### Se houver riscos críticos sem mitigação clara:
+
+→ Sinalize ao usuário e peça orientação antes de finalizar
+
+---
+
+## Boas Práticas
+
+✅ **Fazer:**
+
+- Usar diagramas Mermaid para comunicar arquitetura
+- Documentar "por que" das decisões, não só "o que"
+- Quebrar em incrementos pequenos e testáveis
+- Validar com usuário em cada fase crítica
+- Manter rastreabilidade (links, referências)
+
+❌ **Evitar:**
+
+- Assumir requisitos não explícitos
+- Criar subtarefas muito grandes (>2h)
+- Pular análise de riscos
+- Propor tecnologias sem justificativa
+- Documentação vaga ou genérica
+
+---
+
+## Exemplo de Output Final
+
+```markdown
+✅ Tech Spec para STORY-456 criada com sucesso!
+
+📄 **Documento Local**: $SESSIONS_DIR/eng/story-456/tech-spec.md
+📎 **Anexado no Jira**: STORY-456
+
+📊 **Resumo**:
+
+- **História**: STORY-456 - Implementar autenticação de usuários
+- **Fases**: 4 fases (Setup, Backend, Frontend, Testes)
+- **Subtarefas**: 8 subtarefas
+- **Estimativa total**: 14 horas
+
+🔗 **Subtarefas criadas no Jira**:
+
+- SUBTASK-101: Configurar biblioteca JWT (P0, 1.5h)
+- SUBTASK-102: Criar migration tabela users (P0, 1h)
+- SUBTASK-103: Implementar modelo User (P0, 2h)
+- SUBTASK-104: Criar serviço de autenticação (P0, 2h)
+- SUBTASK-105: Criar endpoints login/logout (P1, 2h)
+- SUBTASK-106: Criar componente LoginForm (P1, 2h)
+- SUBTASK-107: Integrar frontend com API (P1, 1.5h)
+- SUBTASK-108: Testes E2E autenticação (P2, 2h)
+
+⚠️ **Riscos Principais**:
+
+- JWT secret precisa estar em variável de ambiente
+- Performance de bcrypt pode impactar tempo de login (mitigado com salt rounds = 10)
+
+📐 **Decisões Arquiteturais**:
+
+- Escolhido JWT em vez de sessões (stateless, escalável)
+- Bcrypt para hash de senhas (padrão da indústria)
+- Rate limiting em login (proteção contra brute force)
+
+📌 **Próximos Passos**:
+
+1. ✅ Revisar tech spec (aguardando sua aprovação)
+2. Atribuir SUBTASK-101 a 104 para desenvolvedor backend
+3. Atribuir SUBTASK-106 a 107 para desenvolvedor frontend
+4. Iniciar por Fase 1 (Setup) - SUBTASK-101 e 102
+5. Configurar variáveis de ambiente em staging/prod
+
+🎯 **Pronto para iniciar desenvolvimento!**
+```
+
+---
+
+**Agora, inicie o processo com a história fornecida.**