Criar Tech Spec

Restrições Inegociáveis

Não gere a Tech Spec sem antes coletar respostas de clarificação via AskUserQuestion.
Não altere a estrutura do template em assets/techspec-template.md.
A Tech Spec foca em COMO; o documento-fonte (PRD, Investigação ou Spike) já cobre o O QUÊ e o POR QUÊ — não duplique requisitos funcionais.
Toda decisão arquitetural deve citar evidência: achado do documento-fonte, arquivo do repositório (arquivo:linha), regra do projeto (.claude/rules/*) ou documentação oficial via Context7/WebSearch.
Prefira reaproveitar bibliotecas e base classes já adotadas no projeto (locais ou NextFit.Base.*) antes de propor desenvolvimento customizado; justifique qualquer desvio.
A Tech Spec é especificação técnica, não implementação — evite blocos extensos de código; use diagramas e contratos.
Respeite o limite de ~2.000 palavras no documento final.

Procedimentos

Passo 1: Identificar Documento-Fonte (Obrigatório)

Determine o tipo do documento-fonte (PRD, Investigação ou Spike). Se o usuário não especificar, peça via AskUserQuestion.
Localize o arquivo no caminho esperado:
- PRD: ./docs/tasks/prd-[nome]/prd.md
- Investigação: ./docs/tasks/investigacao-[nome]/investigacao.md
- Spike: ./docs/tasks/spike-[nome]/spike.md
Se o usuário informou apenas o nome da funcionalidade, use Bash (ls ./docs/tasks/) para descobrir qual(is) documento(s)-fonte existe(m); se houver ambiguidade, confirme com o usuário.
Leia o documento-fonte completo via Read — não pule esta etapa.
Extraia o conteúdo conforme o tipo:
- PRD: requisitos principais, restrições, métricas de sucesso, conteúdo técnico implícito.
- Investigação: itens priorizados (foque em P0/P1 primeiro), severidades, pontos de falha, propostas de solução, dependências entre correções, riscos de correção.
- Spike: opção recomendada e justificativa, achados e evidências, trade-offs documentados, perguntas abertas que impactam a arquitetura.

Passo 2: Análise Profunda do Projeto (Obrigatório)

Leia CLAUDE.md e os arquivos em .claude/rules/ que regem o escopo (code style, naming conventions, controller patterns, etc.). Anote desvios potenciais para a seção de conformidade.
Mapeie módulos, interfaces e pontos de integração implicados usando Grep e Read. Inclua chamadores/chamados, configs, middleware, persistência, concorrência, tratamento de erros, testes e infra.
Identifique base classes reutilizáveis (locais ou NextFit.Base.*) e bibliotecas já adotadas (EF Core, Polly, RabbitMQ wrappers, Redis, Serilog).
Use Context7 MCP para qualquer questão técnica sobre bibliotecas, frameworks, SDKs ou APIs externas; use WebSearch (mínimo 3 buscas) quando precisar de contexto de negócio, padrões de mercado, RFCs ou benchmarks.
Registre evidências (arquivo:linha, link, ID de achado) que sustentarão as decisões no documento.

Passo 3: Esclarecimentos Técnicos (Obrigatório)

Leia references/clarification-checklist.md e selecione os blocos pertinentes ao tipo de documento-fonte.
Formule perguntas agrupadas via AskUserQuestion, cobrindo no mínimo: posicionamento de domínio, fluxo de dados, dependências externas, interfaces principais e cenários de teste.
Acrescente as perguntas específicas do tipo de documento-fonte (PRD, Investigação ou Spike) conforme o checklist.
Não prossiga ao Passo 4 enquanto houver perguntas não respondidas.

Passo 4: Planejar Conformidade e Estrutura (Obrigatório)

Liste os pontos do projeto em que a solução proposta toca cada regra de .claude/rules/ (code style, naming, controller patterns, módulos, faixas de EnumErro).
Para cada desvio inevitável das regras, registre justificativa e alternativa conforme.
Defina a abordagem de componentização (que entra em Aplicacao, Dominio, Repositorio, Api) respeitando o fluxo Api → Aplicacao → Dominio → Repositorio → Infra.
Exiba o plano resumido ao usuário antes de redigir o documento.

Passo 5: Redigir a Tech Spec (Obrigatório)

Leia assets/techspec-template.md e replique sua estrutura exatamente, preservando a ordem das 8 seções principais e suas subseções.
Preencha o título # Tech Spec: [Título] com o título real.
Em ## Resumo Executivo escreva 2 a 4 parágrafos curtos cobrindo: objetivo técnico, abordagem em uma linha, números (ex.: "3 componentes novos, 2 classes base modificadas") e a decisão arquitetural central. Não repita requisitos funcionais do documento-fonte.
Em ## Arquitetura do Sistema preencha as três tabelas (Componentes novos, Componentes modificados, Componentes reutilizados) e o diagrama de fluxo (texto ASCII ou Mermaid). Cada componente novo deve indicar camada e responsabilidade; componentes reutilizados precisam citar o tipo/classe existente.
Em ## Design de Implementação:
- Interfaces Principais: assinaturas-chave em C# (apenas contrato, sem implementação).
- Modelos de Dados: tabela campo/tipo/origem/descrição, migrações EF Core (convenção DDMMAAAA-acao-descricao) e impactos em ContextoBanco.
- Endpoints de API: tabela verbo/rota/request/response/erros, ou declare "Não aplicável" com justificativa.
Em ## Pontos de Integração documente topologia RabbitMQ (exchange, queue, routing key, retry, deadletter), payloads em JSON, dependências externas (Redis, APIs), modos de falha, timeouts e retries.
Em ## Abordagem de Testes preencha as três subseções (Testes Unitários, Testes de Integração, Testes de E2E). Liste componentes a testar com cenários "Deve / Não deve", mocks apenas para serviços externos, e cite o framework padrão (xUnit + [AutoDomainData] + FakeItEasy, padrão MetodoNome_Condicao_ResultadoEsperado). Quando integração ou E2E não se aplicar, declare explicitamente com justificativa.
Em ## Sequenciamento de Desenvolvimento:
- Ordem de Construção: lista numerada com a sequência real de implementação (DTO → Publisher → Dispatcher → modificações em classes base → infraestrutura → testes, ou análoga ao caso).
- Dependências Técnicas: tabela dependência/status/bloqueante.
Em ## Monitoramento e Observabilidade cubra logs Serilog (níveis e propriedades obrigatórias), métricas, health checks (/healthz) e alertas. Indique quando wrappers existentes (RabbitMqPublisherBase, etc.) já cobrem parte da instrumentação.
Em ## Considerações Técnicas:
- Decisões Principais: tabela decisão/justificativa/alternativa rejeitada.
- Riscos Conhecidos: tabela risco/severidade/mitigação (severidades Alta/Média/Baixa/Info).
- Conformidade com Skills Padrões: tabela skill/aplicabilidade indicando como cada skill do projeto (executar-task, criar-testes-unitarios, task-review, executar-review, code-reviewer, verificar-testes-pre-impl) será usada durante a implementação.
- Arquivos relevantes e dependentes: quatro listas — Arquivos a criar, Arquivos a modificar, Arquivos de referência (padrão a seguir), Documento-fonte apontando para o PRD/Investigação/Spike de origem.
Aplique as adaptações por tipo de documento-fonte:
- PRD: evite repetir requisitos funcionais; foque em como implementar.
- Investigação: referencie IDs dos itens (ex.: INV-001) no Sequenciamento e em Decisões; respeite a ordem de priorização; reforce rollback em Riscos Conhecidos.
- Spike: referencie achados/evidências do spike nas Decisões Principais; documente como a opção recomendada se traduz em componentes; trate perguntas abertas remanescentes em Riscos Conhecidos.
Garanta conformidade com as regras de .claude/rules/ (code-style, naming-conventions, controller-patterns, faixas de EnumErro) ao descrever componentes, interfaces e modelos. Desvios devem ser justificados na linha correspondente da tabela de Decisões Principais.

Passo 6: Salvar a Tech Spec (Obrigatório)

Derive o diretório de saída a partir do documento-fonte:
- PRD → ./docs/tasks/prd-[nome]/techspec.md
- Investigação → ./docs/tasks/investigacao-[nome]/techspec.md
- Spike → ./docs/tasks/spike-[nome]/techspec.md
Salve o documento via Write no caminho derivado, sem criar diretório novo (o documento-fonte já o garante).
Se já existir techspec.md no destino, confirme com o usuário se deve sobrescrever ou usar sufixo numérico (techspec-v2.md).

Passo 7: Validar com o Checklist de Qualidade (Obrigatório)

Leia references/quality-checklist.md.
Verifique cada item obrigatório contra o documento gerado.
Se algum item obrigatório falhar, retorne ao Passo correspondente e corrija antes de reportar.

Passo 8: Reportar Resultados

Informe o caminho completo do arquivo gerado.
Forneça um resumo bem breve com: tipo do documento-fonte, decisão arquitetural central e principais pontos de impacto.
Não anexe o conteúdo do documento na resposta — apenas o resumo e o caminho.

Helpers Bundled

assets/techspec-template.md — read-only. Estrutura canônica do documento final. Replicar sem alterar ordem ou numeração das seções.
references/clarification-checklist.md — read-only. Base para as perguntas obrigatórias do Passo 3, com blocos comuns e adaptações por tipo de documento-fonte.
references/quality-checklist.md — read-only. Auditoria final no Passo 7.

Tratamento de Erros

Documento-fonte ausente no caminho esperado: liste o conteúdo de ./docs/tasks/ via Bash e peça ao usuário para confirmar o caminho; não invente conteúdo.
Mais de um documento-fonte para o mesmo nome (ex.: PRD + Spike): pergunte qual deve ser usado como base e registre a relação com os demais em ## 13. Referências.
Usuário não respondeu às perguntas de clarificação: repita o Passo 3 com perguntas mais específicas; não suponha respostas.
Decisão sem evidência factual: rebaixe a decisão para hipótese em ## 12. Riscos e Mitigações indicando o experimento ou spike necessário; nunca trate como decisão fechada.
Desvio inevitável de regra em .claude/rules/: documente em ## 11. Conformidade com Padrões com justificativa e alternativa conforme; não silencie o desvio.
techspec.md já existe no destino: confirme sobrescrita ou use sufixo -v2; nunca apague o arquivo anterior sem confirmação.