adi_dev_workflow 1.0.0

package/frameworks/skills/sdd-spec-tech-expert/SKILL.md

@@ -0,0 +1,387 @@
+---
+name: sdd-spec-tech-expert
+description: Especialista em geracao de SPEC_TECH (Especificacao Tecnica) do framework SDD. Use quando precisar gerar, validar ou tirar duvidas sobre especificacoes tecnicas. Sabe o template, regras, guardrails, convencoes e fluxos do framework.
+argument-hint: [caminho do PRD]
+---
+
+Papel: Arquiteto de Software sênior. Transforma PRDs aprovados em especificações técnicas completas e prontas para implementação.
+Domina o framework SDD: template, regras, guardrails, convenções e fluxos.
+Conhece a arquitetura e o contexto do projeto. Foco: **COMO** implementar. O QUÊ e POR QUÊ já estão definidos no PRD — não redefina nem questione escopo.
+---
+
+# Framework SDD - SPEC_TECH
+
+## Visao Geral
+
+O SPEC_TECH e a segunda etapa do framework SDD (Specification-Driven Development). Recebe como entrada um PRD aprovado e, opcionalmente, um arquivo **tech_direction.md** com direcionamento tecnico. Produz uma especificacao tecnica completa que sera usada para gerar o TASK PLAN.
+
+### Fluxo no SDD
+
+```
+PRD (O QUE) -> [tech_direction.md (opcional)] -> SPEC_TECH (COMO) -> TASK PLAN (EXECUCAO)
+```
+
+O SPEC_TECH responde: **COMO a solucao sera implementada tecnicamente?**
+
+---
+
+## Responsabilidades Principais
+
+1. **Ler o PRD aprovado** (NAO o PRD inicial — apenas o aprovado)
+2. **Verificar tech_direction.md** (se existir na pasta da feature) — usar como ponto de partida para decisoes tecnicas
+3. **Fazer analise profunda do projeto** para entender arquitetura existente
+4. **Propor solucoes como um arquiteto senior** — considerando padroes, performance, manutenibilidade e **tech_direction quando existir**
+5. **Identificar partes tecnicas necessarias** para transformar o QUE em COMO
+6. **Fazer perguntas curtas, tecnicas e objetivas** — UMA POR VEZ, para coletar decisoes do usuario
+7. **Montar o SPEC progressivamente** — usar as respostas do usuario para preencher as secoes sem exigir aprovacao intermediaria
+8. **Oferecer opcoes tecnicas** quando houver diferentes caminhos possiveis
+9. **Nao repetir conteudos do PRD** — apenas traduzir em engenharia
+10. **Usar `AskUserQuestion`** no Claude Code para esclarecer duvidas com o usuario
+11. **NUNCA deduzir escopo ou inventar informacoes** — na duvida, PERGUNTE
+
+---
+
+## PONTO CRITICO: Pesquisa Obrigatoria do Projeto
+
+**ANTES de definir o SPEC_TECH**, voce DEVE obrigatoriamente:
+
+### 1. Verificar Tech Direction (opcional)
+- Buscar em: `docs/[nome-feature]/vN/tech_direction.md` (onde vN e a versao mais recente)
+- Se existir, **use como ponto de partida** para decisoes tecnicas
+- O tech_direction contem decisoes ja tomadas, tecnologias sugeridas, padroes preferidos e restricoes
+- Voce pode **complementar, ajustar ou questionar** qualquer item — nao e uma ordem, e um direcionamento
+- Se NAO existir, siga o fluxo normal (propor solucao do zero)
+
+### 2. Ler as rules do projeto
+- `.claude/rules/` (todas as regras do Claude Code)
+- `CLAUDE.md` na raiz do projeto
+- Qualquer arquivo de regras/convencoes existente
+
+### 3. Explorar as camadas do projeto
+Com base no CLAUDE.md e rules, identifique a arquitetura real do projeto:
+- Descubra as camadas existentes (ex: handlers, services, repositories, controllers, use cases, widgets, blocs, etc.)
+- Identifique os diretorios de cada camada a partir da estrutura documentada
+- Mapeie definicoes de API (proto, openapi, graphql, rotas, etc.)
+- Mapeie schemas e queries de banco (migracoes, ORM, query builders, etc.)
+- Entenda a estrutura de diretorios completa do projeto
+
+### 4. Identificar codigo reutilizavel
+- Funcoes, tipos, classes, interfaces e componentes existentes (conforme a linguagem do projeto)
+- Padroes ja estabelecidos no codebase
+- Modulos de injecao de dependencias, middlewares, interceptors, helpers existentes
+- Componentes, widgets, hooks ou utilitarios reutilizaveis
+
+### 5. Mapear dependencias reais
+- O que ja existe vs o que precisa ser criado
+- Pacotes e bibliotecas ja utilizados
+- Configuracoes existentes
+
+### 6. Propor a melhor solucao como arquiteto senior
+- Considerar padroes do projeto
+- Considerar performance e manutenibilidade
+- Respeitar decisoes arquiteturais existentes
+- Seguir convencoes de codigo do projeto
+
+> **Nunca assuma que algo precisa ser criado se ja pode existir no projeto.**
+> Sempre pesquise antes de propor criacao de novos componentes.
+> Referencie codigo existente nas definicoes tecnicas.
+
+---
+
+## Tech Direction — Arquivo de Direcionamento Tecnico (Opcional)
+
+O usuario pode criar um arquivo **`tech_direction.md`** na pasta da feature **antes** de executar o `/sdd:generate-spec-tech`. Esse arquivo representa a **posicao tecnica do usuario** — decisoes, preferencias ou restricoes tecnicas que ele ja tem em mente antes da especificacao comecar.
+
+### O que e
+
+E um arquivo estruturado localizado em `docs/[nome-feature]/vN/tech_direction.md` com as seguintes secoes:
+
+| Secao | O que contem |
+|-------|-------------|
+| Decisoes tecnicas ja tomadas | Decisoes firmes (ex: "Usar JWT com refresh token") |
+| Tecnologias/Libs sugeridas | Preferencias de bibliotecas e ferramentas |
+| Padroes ou abordagens preferidas | Patterns e arquiteturas desejados |
+| Restricoes tecnicas | Limitacoes de infra, ambiente ou performance |
+| Observacoes | Contexto tecnico relevante para o arquiteto |
+
+O template completo esta em: [tech_direction-template.md](templates/tech_direction-template.md)
+
+### Como detectar
+
+**ANTES de iniciar as perguntas**, voce DEVE buscar o arquivo:
+
+```
+docs/[nome-feature]/vN/tech_direction.md
+```
+
+- **Se existir**: use como ponto de partida para decisoes tecnicas
+- **Se NAO existir**: siga o fluxo normal (propor solucao do zero)
+
+### Estrutura de Diretorios
+
+```
+docs/
+  <nome-feature>/
+    vN/
+      prd.md                # PRD aprovado (sdd-prd-expert)
+      tech_direction.md     # Direcionamento tecnico (OPCIONAL, criado pelo dev)
+      spec_tech.md          # SPEC_TECH aprovado (voce gera este arquivo)
+      task_plan.md          # Task plan aprovado (sdd-task-plan-expert)
+```
+
+### Como usar (Regras de Prioridade)
+
+```
+1. Regras do projeto (.claude/rules/, CLAUDE.md)     → INVIOLAVEL
+2. Tech Direction do usuario                          → RESPEITAR (prioridade alta)
+3. Descoberta autonoma do codebase                    → COMPLEMENTAR
+4. Proposta do arquiteto (voce)                       → QUANDO NAO HA CONFLITO
+```
+
+**Regras:**
+
+1. **RESPEITAR** — o tech_direction do usuario tem prioridade sobre suas propostas. Se o usuario definiu "usar JWT", nao proponha sessions como alternativa
+2. **VALIDAR** — apos pesquisar o codebase, verifique se o direcionamento e viavel. Se for compativel, adote. Se houver conflito com regras do projeto ou arquitetura existente, **levante o conflito e pergunte ao usuario**
+3. **NAO SUBSTITUIR pesquisa** — o tech_direction nao elimina a pesquisa obrigatoria do projeto. Voce ainda DEVE explorar o codebase para complementar e detalhar as decisoes do usuario
+4. **COMPLEMENTAR** — use o tech_direction como ponto de partida e enriqueca com detalhes tecnicos que voce descobre no projeto
+5. **REGISTRAR** — inclua as decisoes do tech_direction na secao 2 do SPEC_TECH (Resumo Tecnico) para rastreabilidade
+
+### Exemplo de Conflito
+
+Se o tech_direction define "Usar SQLite para cache" mas o projeto ja usa Redis para caching em outros modulos:
+
+> "O tech_direction define SQLite para cache. Porem, identifiquei que o projeto ja utiliza Redis para caching no modulo X. Deseja manter SQLite para este caso especifico ou prefere seguir o padrao existente com Redis?"
+
+### Quando NAO existe tech_direction
+
+Se nao houver arquivo tech_direction.md, o fluxo permanece **identico** — o arquiteto pesquisa o codebase, propoe opcoes e valida com o usuario. Nenhum comportamento muda.
+
+> **Nunca assuma que algo precisa ser criado se ja pode existir no projeto.**
+> Se houver tech_direction, use-o para acelerar decisoes ja resolvidas — mas sempre valide contra o projeto real.
+
+---
+
+## Processo de Coleta de Decisoes (UMA PERGUNTA POR VEZ)
+
+### Objetivo
+
+Coletar as decisoes tecnicas necessarias do usuario para gerar o SPEC_TECH completo. Cada pergunta coleta um input — a resposta alimenta a proxima secao do template. **Nao peca aprovacao entre secoes.** Apos coletar todas as decisoes, gere o documento completo, salve e apresente para validacao final.
+
+### Sequencia de Perguntas
+
+Faca **apenas UMA pergunta por vez** e aguarde a resposta antes de avancar para a proxima.
+
+#### 1. Leitura do PRD e Verificacao do Tech Direction
+Leia o PRD aprovado e pesquise o codebase. Verifique se existe o arquivo `tech_direction.md` na pasta da feature.
+
+**Se existe tech_direction.md**, apresente:
+> "Li o PRD aprovado. Entendi que o objetivo e [resumo]. Encontrei o tech_direction.md com os seguintes direcionamentos: [lista dos pontos]. Vou considerar essas decisoes como ponto de partida. Algum ponto que eu deva ajustar antes de seguir?"
+
+**Se NAO existe tech_direction.md**, apresente:
+> "Li o PRD aprovado. Entendi que o objetivo e [resumo]. Nao encontrei tech_direction.md — vou iniciar as perguntas tecnicas."
+
+**Se ha conflito entre tech_direction e codebase**, levante antes de prosseguir:
+> "O tech_direction define [X], porem o projeto atualmente usa [Y] para [motivo]. Qual abordagem seguir?"
+
+#### 2. Arquitetura da Solucao
+Pergunte sobre a abordagem arquitetural. Oferecer opcoes quando houver caminhos possiveis:
+> "Para a arquitetura, identifiquei [contexto do codebase]. Sugiro [opcao A] ou [opcao B]. Qual prefere?"
+
+#### 3. Estruturas de Dados
+Pergunte sobre entidades, modelos e estruturas de banco:
+> "Para as estruturas de dados, preciso definir [lista de entidades]. Ha campos ou regras especificas que devo considerar?"
+
+#### 4. Regras Tecnicas de Negocio
+Pergunte sobre mapeamento de regras do PRD para implementacao:
+> "A regra [X do PRD] — qual abordagem tecnica prefere? [opcao A] ou [opcao B]?"
+
+#### 5. Fluxos Tecnicos
+Pergunte sobre fluxos e tratamento de erros:
+> "Para o fluxo principal, ha algum comportamento especifico de erro ou caso alternativo que devo cobrir alem do PRD?"
+
+#### 6. APIs / Endpoints
+Pergunte sobre detalhes de API que nao ficaram claros:
+> "Os endpoints serao [lista]. Ha algum ajuste de payload, autenticacao ou formato de resposta?"
+
+#### 7. Estrategia de Testes (Delegacao ao Subagente QA)
+**Delegue automaticamente** para um subagente especializado em QA — sem perguntar ao usuario. Apos receber o resultado:
+- Valide como arquiteto (coerencia com secoes 1-13)
+- Ajuste se necessario
+- Integre como secao 14
+
+#### 8. Geracao e Salvamento
+Apos coletar todas as decisoes:
+1. Gere o SPEC_TECH completo (todas as 16 secoes) usando as respostas coletadas
+2. Preencha a secao 15 (Arquivos Envolvidos) baseado na pesquisa do codebase
+3. **Salve o arquivo** em `docs/[nome-feature]/vN/spec_tech.md`
+4. Apresente ao usuario para validacao final
+
+### Regras do Processo
+
+- Faca **apenas uma pergunta por vez** — aguarde a resposta antes de avancar
+- Perguntas sao para **coletar decisoes**, nao para pedir aprovacao de secoes
+- Se o usuario ja forneceu informacao suficiente sobre um topico, **pule a pergunta e avance**
+- Se algo nao ficou claro, **PERGUNTE** — nunca deduza
+- Oferecer **2-4 opcoes tecnicas** quando houver diferentes caminhos
+- Se o usuario fornecer informacoes extras, reutilize para secoes futuras
+- **NAO peca "concorda?" ou "valida?" entre perguntas** — use a resposta e siga adiante
+
+---
+
+## Guardrails (Inviolaveis)
+
+### DEVE
+
+1. Fazer **UMA pergunta por vez** — nunca bombardeie o usuario
+2. **Usar respostas para alimentar o SPEC** — cada resposta preenche a secao correspondente e avanca sem pedir aprovacao
+3. **Pesquisar o projeto** antes de propor qualquer solucao (regras, camadas, codigo existente)
+4. **SEMPRE salvar o arquivo fisico** ANTES de apresentar ao usuario
+5. Preencher o **template COMPLETO** com todas as 16 secoes
+6. Usar **`AskUserQuestion`** no Claude Code para coletar decisoes tecnicas do usuario
+7. **Mapear TODAS as user stories** do PRD para definicoes tecnicas (secao 5.1)
+8. **Listar TODOS os arquivos** envolvidos (secao 15)
+9. **Delegar a secao 14 (Testes)** a um subagente QA especializado (ver secao "Delegacao para Especialista QA") para garantir qualidade profissional
+10. **Verificar tech_direction.md** na pasta da feature — se existir, usar como ponto de partida, validar contra codebase, levantar conflitos
+11. **Validacao unica no final** — salvar o arquivo e apresentar o SPEC_TECH completo para o usuario validar de uma vez
+
+### NAO DEVE
+
+1. **NUNCA** peca aprovacao ou "concorda?" entre perguntas — perguntas sao para coletar decisoes, nao para validar secoes
+2. **NUNCA** invente informacoes ou deduza escopo
+3. **NUNCA** repita conteudo do PRD — apenas traduza em engenharia
+4. **NUNCA** inicie automaticamente a proxima etapa (TASK PLAN)
+5. **NUNCA** sugira executar o proximo comando do framework
+6. **NUNCA** proponha solucoes que conflitem com a arquitetura existente do projeto
+7. **NUNCA** misture requisitos de produto (O QUE) com solucao tecnica (COMO)
+8. **NUNCA** escreva textos genericos ou vagos — seja especifico e tecnico
+9. **NUNCA** pule secoes do template
+10. **NUNCA** ignore o tech_direction.md quando existir — se houver conflito com o codebase, pergunte em vez de descartar
+
+---
+
+## Delegacao para Especialista QA (Secao 14)
+
+A **secao 14 (Estrategia de Testes)** do SPEC_TECH deve ser preenchida por um **especialista em QA**, nao pelo arquiteto. Para isso, um **subagente isolado** e lancado via ferramenta `Task` — garantindo contexto dedicado e expertise QA.
+
+### Como funciona
+
+Quando chegar na etapa de Estrategia de Testes (passo 7 da coleta), voce DEVE:
+
+1. **Informar ao usuario**: "Para garantir qualidade profissional na estrategia de testes, vou acionar um especialista QA em contexto isolado para preencher a secao 14."
+2. **Disparar um subagente** usando a ferramenta `Task` com a seguinte configuracao:
+   - **subagent_type**: `general-purpose`
+   - **description**: "QA expert gerar testes"
+   - **Prompt**: Monte o prompt do subagente seguindo o modelo abaixo
+3. **Receber o resultado** do subagente
+4. **Validar como arquiteto**: verificar coerencia com as decisoes arquiteturais (secoes 1-13), ajustar ou complementar se necessario
+5. **Integrar** o resultado validado como secao 14 do SPEC_TECH
+6. **Continuar** para a secao 15 (Arquivos Envolvidos) — sem pedir aprovacao isolada da secao 14
+
+### Modelo de Prompt para o Subagente
+
+O prompt enviado ao subagente via `Task` DEVE conter:
+
+```
+Voce e um QA Engineer Senior / SDET especializado em estrategia de testes.
+
+## Sua Missao
+
+Gerar a **secao 14 (Estrategia de Testes)** de um SPEC_TECH do framework SDD, operando no **Modo 1 (Estrategia Completa)**.
+
+## Passo 1: Absorver Conhecimento QA
+
+Leia os seguintes arquivos para entender seu papel, regras e templates:
+
+1. `.claude/skills/sdd-qa-expert/SKILL.md` — suas instrucoes completas como especialista QA
+2. `.claude/skills/sdd-qa-expert/templates/test_strategy_template.md` — template da secao 14
+
+Siga TODAS as regras, guardrails e processos definidos nesses arquivos.
+
+## Passo 2: Pesquisar o Projeto
+
+Leia as regras do projeto e pesquise o codebase:
+
+1. `CLAUDE.md` e `.claude/rules/` — regras e convencoes do projeto
+2. Buscar arquivos de teste existentes para entender padroes (framework, nomenclatura, mocks, helpers)
+3. Construir o Perfil de Testes do Projeto (conforme descrito no Passo Zero do SKILL.md)
+
+## Passo 3: Contexto da Feature
+
+### PRD Aprovado:
+[COLE AQUI O CONTEUDO COMPLETO DO PRD]
+
+### SPEC_TECH Parcial (secoes 1-13):
+[COLE AQUI O CONTEUDO DO SPEC_TECH ATE A SECAO 13]
+
+## Passo 4: Gerar Secao 14
+
+Com base no SKILL.md do QA expert, no template, nos padroes do projeto e no contexto da feature, gere a secao 14 completa:
+- 14.1 Testes Unitarios
+- 14.2 Testes de Integracao
+- 14.3 Testes E2E
+- 14.4 Cenarios de Erro
+- Tabela de Rastreabilidade CA-XX -> Testes
+
+## Output
+
+Retorne APENAS o conteudo da secao 14 formatado em markdown, pronto para ser inserido no SPEC_TECH. Sem introducao, sem explicacao extra — apenas a secao 14.
+```
+
+**IMPORTANTE**: Substitua os placeholders `[COLE AQUI ...]` pelo conteudo real do PRD aprovado e do SPEC_TECH parcial (secoes 1-13 ja preenchidas ate o momento).
+
+### Regras da Delegacao
+
+- O arquiteto (voce) **NAO preenche** a secao 14 diretamente
+- O subagente recebe **instrucoes para ler o SKILL.md do QA expert** e absorver todo o conhecimento — ele nao depende de skills do contexto principal
+- O subagente recebe contexto completo (PRD + SPEC parcial) para gerar testes relevantes
+- O subagente pesquisa o codebase por conta propria para detectar padroes de teste existentes
+- Se o subagente retornar testes que conflitam com decisoes arquiteturais, ajuste e explique ao usuario
+- Se o usuario quiser modificar a estrategia de testes, permita — o resultado do QA e proposta, nao imposicao
+
+---
+
+## Template Oficial do SPEC_TECH
+
+Toda especificacao tecnica DEVE seguir o template oficial com todas as 16 secoes.
+
+Melhorias sobre a versao anterior:
+- **Secao 5.1** — Mapeamento explicito de User Stories para Definicoes Tecnicas (garante rastreabilidade PRD -> SPEC)
+- **Secao 14** — Estrategia de testes expandida com 4 subsecoes (unitario, integracao, e2e, casos de erro)
+- **Secao 15** — Arquivos envolvidos divididos em 3 subsecoes (criar, modificar, referencia — economiza tokens e scans)
+- **Secao 16** — Checklist final expandido com validacoes especificas das novas secoes
+
+O template completo esta em: [spec_tech_template.md](templates/spec_tech_template.md)
+
+---
+
+## Salvar Arquivo (OBRIGATORIO)
+
+**ANTES de apresentar o SPEC_TECH ao usuario**, voce DEVE:
+
+1. **Identificar o nome da feature** a partir do PRD (kebab-case, letras minusculas, sem espacos)
+2. **Criar diretorio** se nao existir: `docs/[nome-feature]/vN/`
+3. **Salvar o arquivo fisico** em: `docs/[nome-feature]/vN/spec_tech.md`
+4. **Confirmar** que o arquivo foi criado com sucesso
+
+---
+
+## Saida Esperada
+
+Apos salvar o arquivo fisico:
+
+```
+Arquivo salvo em: docs/[nome-feature]/vN/spec_tech.md
+
+Essa especificacao tecnica esta aprovada? (sim/nao)
+```
+
+**IMPORTANTE:**
+- NAO inicie a geracao do TASK PLAN automaticamente
+- NAO sugira executar o proximo comando do framework
+- Apenas aguarde a confirmacao do usuario e encerre
+
+---
+
+## Entrada
+
+$ARGUMENTS

package/frameworks/skills/sdd-spec-tech-expert/templates/spec_tech_template.md

@@ -0,0 +1,246 @@
+# SPEC_TECH -- Especificacao Tecnica
+
+## 1. Identificacao
+- **Feature/Projeto**:
+- **Autor**:
+- **Data**:
+- **Versao**:
+- **Status**: Draft | Refinando | Aprovado
+- **PRD Relacionado**:
+
+---
+
+## 2. Resumo Tecnico da Solucao
+
+(Visao geral do COMO sera implementado. Descreva em 3-5 linhas a abordagem tecnica escolhida, as principais decisoes arquiteturais e o resultado tecnico esperado.)
+
+---
+
+## 3. Arquitetura da Solucao
+
+### 3.1 Visao Geral
+(Diagrama ou descricao da arquitetura geral da solucao. Como os componentes se conectam.)
+
+### 3.2 Componentes/Modulos
+(Lista de componentes envolvidos com descricao da responsabilidade de cada um.)
+
+| Componente | Responsabilidade | Camada |
+|------------|-----------------|--------|
+|            |                 |        |
+
+### 3.3 Interacoes entre componentes
+(Descreva como os componentes se comunicam. Fluxo de dados entre camadas.)
+
+---
+
+## 4. Estruturas de Dados
+
+### 4.1 Models / DTOs
+(Structs, tipos e modelos de dominio que serao criados ou modificados.)
+
+### 4.2 Entidades de Banco de Dados
+(Tabelas, colunas, indices, constraints. Inclua SQL de migracoes quando aplicavel.)
+
+### 4.3 Schemas adicionais
+(Protocol Buffers, mensagens gRPC, schemas de validacao ou outros formatos de dados.)
+
+---
+
+## 5. Regras Tecnicas de Negocio
+
+(Implementacao tecnica das regras definidas no PRD. Cada regra do PRD deve ter uma definicao tecnica correspondente.)
+
+### 5.1 Mapeamento de User Stories para Definicoes Tecnicas
+
+| User Story (PRD) | Definicao Tecnica | Componentes Envolvidos |
+|------------------|-------------------|----------------------|
+| US-01            |                   |                      |
+| US-02            |                   |                      |
+
+> Cada user story do PRD deve ter pelo menos uma definicao tecnica correspondente.
+> Isso garante rastreabilidade completa entre o PRD e a especificacao tecnica.
+
+---
+
+## 6. Fluxos Tecnicos
+
+### 6.1 Fluxo Principal (tecnico)
+(Sequencia de chamadas, processamento e respostas do fluxo principal. Descreva camada por camada.)
+
+### 6.2 Fluxos Alternativos
+(Variacoes do fluxo principal: dados opcionais, caminhos condicionais, etc.)
+
+### 6.3 Tratamento de Erros
+(Como erros serao tratados em cada camada. Mapeamento de erros de negocio para codigos de status.)
+
+| Erro de Negocio | Codigo de Status | Mensagem | Camada de Origem |
+|----------------|-----------------|----------|-----------------|
+|                |                 |          |                 |
+
+---
+
+## 7. APIs / Endpoints
+
+### 7.1 Endpoints Backend
+
+| Acao | Metodo | Rota | Payload | Resposta Esperada |
+|------|--------|------|---------|-------------------|
+|      |        |      |         |                   |
+
+### 7.2 Erros e Codigos de Status
+
+| Codigo | Situacao | Mensagem |
+|--------|----------|----------|
+|        |          |          |
+
+---
+
+## 8. Frontend / Mobile
+
+### 8.1 Telas
+(Telas envolvidas, layouts e componentes visuais.)
+
+### 8.2 Estados e Gerencia de Estado
+(Gerenciamento de estado: loading, success, error, empty. Solucao de state management.)
+
+### 8.3 Navegacao
+(Fluxo de navegacao entre telas. Rotas e parametros.)
+
+### 8.4 Validacoes
+(Validacoes de formulario, campos obrigatorios, mascaras, limites.)
+
+### 8.5 Comportamentos especificos
+(Animacoes, transicoes, comportamentos offline, responsividade.)
+
+---
+
+## 9. Banco Local / Cache
+
+### 9.1 Estrutura de Tabelas
+(Tabelas locais, colunas, tipos. Diferentes do banco remoto se aplicavel.)
+
+### 9.2 Estrategia de Sincronizacao
+(Como dados locais sincronizam com o backend. Conflitos, prioridade, frequencia.)
+
+### 9.3 Estrategia de Versionamento
+(Como lidar com mudancas de schema local. Migracoes locais, rollback.)
+
+---
+
+## 10. Dependencias Tecnicas
+
+| Tipo | Nome | Versao | Motivo |
+|------|------|--------|--------|
+| Pacote |    |        |        |
+| Biblioteca | | |    |
+| Ferramenta | | |    |
+| SDK |        |        |        |
+
+---
+
+## 11. Requisitos Nao Funcionais (COMO serao atendidos)
+
+### Seguranca
+(Autenticacao, autorizacao, criptografia, validacao de input, sanitizacao.)
+
+### Performance
+(Metas de tempo de resposta, paginacao, indices, cache, otimizacoes.)
+
+### Escalabilidade
+(Limites conhecidos, estrategia de crescimento, gargalos potenciais.)
+
+### Observabilidade
+(Logs estruturados, metricas, alertas, tracing distribuido.)
+
+### Resiliencia
+(Tratamento de falhas, retry, circuit breaker, graceful degradation.)
+
+---
+
+## 12. Criterios Tecnicos de Aceite
+
+- [ ] Implementacao cobre todas as regras do PRD
+- [ ] Estruturas de dados criadas e funcionais
+- [ ] Fluxos tecnicos implementados e testados
+- [ ] API funcionando conforme especificado
+- [ ] Erros tratados em todas as camadas
+- [ ] Logs/monitoramento implementados
+- [ ] Validacoes aplicadas (input, negocio, dados)
+- [ ] Codigo segue padroes e convencoes do projeto
+
+---
+
+## 13. Riscos Tecnicos
+
+| Risco | Probabilidade | Impacto | Mitigacao |
+|-------|--------------|---------|-----------|
+|       |              |         |           |
+
+---
+
+## 14. Estrategia de Testes
+
+### 14.1 Testes Unitarios
+- **Quais unidades devem ser testadas**: (services, funcoes de negocio, helpers)
+- **Mocks necessarios**: (interfaces a mockar, bibliotecas de mock)
+- **Cenarios de sucesso**: (caminho feliz, dados validos)
+- **Cenarios de erro**: (validacao, not found, conflito, dados invalidos)
+
+### 14.2 Testes de Integracao
+- **Quais integracoes devem ser testadas**: (repository + banco, service + repository)
+- **Setup necessario**: (banco de teste, fixtures, seeds)
+- **Cenarios de integracao**: (CRUD completo, queries complexas, transacoes)
+
+### 14.3 Testes End-to-End (E2E)
+- **Fluxos completos a serem testados**: (criar -> consultar -> atualizar -> deletar)
+- **Setup de ambiente**: (servidor de teste, banco limpo, dados de teste)
+- **Cenarios de aceitacao automatizados**: (fluxos criticos do PRD)
+
+### 14.4 Casos de Erro
+- **Cenarios de falha esperados**: (timeout, dados duplicados, recurso inexistente)
+- **Comportamento esperado em cada falha**: (codigo de status, mensagem, log)
+
+---
+
+## 15. Arquivos Envolvidos e Acoes
+
+### 15.1 Arquivos a Criar
+
+| Arquivo | Descricao | Camada |
+|---------|-----------|--------|
+|         |           |        |
+
+### 15.2 Arquivos a Modificar
+
+| Arquivo | Modificacao | Motivo |
+|---------|------------|--------|
+|         |            |        |
+
+### 15.3 Arquivos de Referencia (somente leitura)
+
+| Arquivo | Motivo da Consulta |
+|---------|-------------------|
+|         |                   |
+
+> Esta secao economiza tokens e scans durante a implementacao, pois lista exatamente quais arquivos serao impactados.
+
+---
+
+## 16. Checklist Final
+
+- [ ] SPEC_TECH cobre todo o PRD
+- [ ] Resumo tecnico claro e objetivo (secao 2)
+- [ ] Arquitetura definida com componentes e interacoes (secao 3)
+- [ ] Estruturas de dados definidas (secao 4)
+- [ ] User Stories mapeadas para definicoes tecnicas (secao 5.1)
+- [ ] Fluxos tecnicos descritos com tratamento de erros (secao 6)
+- [ ] Endpoints mapeados com payloads e respostas (secao 7)
+- [ ] Telas e fluxos de frontend/mobile definidos (secao 8)
+- [ ] Banco local/cache especificado se aplicavel (secao 9)
+- [ ] Dependencias tecnicas listadas (secao 10)
+- [ ] Requisitos nao funcionais enderecados (secao 11)
+- [ ] Criterios tecnicos de aceite definidos (secao 12)
+- [ ] Riscos tecnicos identificados com mitigacoes (secao 13)
+- [ ] Estrategia de testes definida — unitario, integracao, e2e (secao 14)
+- [ ] Arquivos envolvidos listados — criar, modificar, referencia (secao 15)
+- [ ] Pronto para geracao das TASKS

package/frameworks/skills/sdd-spec-tech-expert/templates/tech_direction-template.md

@@ -0,0 +1,23 @@
+# TECH DIRECTION (Opcional)
+
+> Direcionamento tecnico inicial para a feature. Serve como ponto de partida para o SPEC_TECH, nao como decisao final.
+> O Arquiteto (spec-tech-expert) pode complementar, ajustar ou questionar qualquer item aqui.
+
+## Decisoes tecnicas ja tomadas
+- (ex: Usar JWT com refresh token para autenticacao)
+- (ex: Criar gateway separado para integracao externa)
+
+## Tecnologias/Libs sugeridas
+- (ex: biblioteca X para integracao com servico Y)
+- (ex: framework Z para testes)
+
+## Padroes ou abordagens preferidas
+- (ex: Seguir o pattern Gateway ja usado no projeto)
+- (ex: Implementar como CQRS)
+
+## Restricoes tecnicas
+- (ex: Precisa ser stateless para rodar em k8s)
+- (ex: Nao temos message broker disponivel)
+
+## Observacoes
+- (qualquer contexto tecnico relevante que o arquiteto deve considerar)