jarvis-ai-framework 1.0.0

package/skills/prod-specs/references/prod.spec.clarify.md

@@ -0,0 +1,176 @@
+---
+name: prod.spec.clarify
+description: Identificar áreas subespecificadas na especificação da feature atual fazendo até 5 perguntas de esclarecimento altamente direcionadas e incorporando as respostas de volta na spec.
+auto_execution_mode: 3
+env_file: "@/ENV.md"
+recommended_model: gpt-4o
+model_tier: medium
+model_justification: Esclarecimento de specs requer análise estruturada e formulação de perguntas, mas segue processo bem definido
+---
+
+## Clarify workflow
+
+Detectar e reduzir ambiguidades ou pontos de decisão ausentes na especificação da feature ativa e registrar os esclarecimentos diretamente no arquivo da spec.
+
+Observação: Este workflow de esclarecimento deve ser executado (e concluído) ANTES da etapa de planejamento. Se o usuário declarar explicitamente que está pulando o esclarecimento (por exemplo, spike exploratório), você pode prosseguir, mas deve avisar que o risco de retrabalho posterior aumenta.
+
+Utilize o que o usuário fornecer analisar em:
+<requirement>
+#$ARGUMENTS
+</requirement>
+
+Etapas de execução:
+
+1. Carregue o arquivo atual da spec. Realize uma varredura estruturada de ambiguidades e cobertura usando esta taxonomia. Para cada categoria, marque o status: Claro / Parcial / Ausente. Produza um mapa de cobertura interno usado para priorização (não divulgue o mapa bruto a menos que nenhuma pergunta seja feita). Analise o arquivo da spec e realize uma cobertura apenas com os itens que estão incluídos na especificação do usuário.
+
+Ao final do processo, peça ao usuário para confirmar o esclarecimento e liste os itens ausentes, perguntando se ele quer esclarecê-los.
+
+Escopo Funcional & Comportamento:
+- Principais objetivos do usuário & critérios de sucesso
+- Declarações explícitas de fora de escopo
+- Diferenciação de papéis / personas dos usuários
+
+Domínio & Modelo de Dados:
+- Entidades, atributos, relacionamentos
+- Regras de identidade & unicidade
+- Transições de ciclo de vida/estado
+- Suposições de volume de dados / escala
+
+Interação & Fluxo de UX:
+- Jornadas / sequências críticas do usuário
+- Estados de erro/vazio/carregamento
+- Observações de acessibilidade ou localização
+
+Atributos de Qualidade Não Funcionais:
+- Desempenho (latência, metas de throughput)
+- Escalabilidade (horizontal/vertical, limites)
+- Confiabilidade & disponibilidade (expectativas de uptime e recuperação)
+- Observabilidade (logging, métricas, sinais de tracing)
+- Segurança & privacidade (authN/Z, proteção de dados, suposições de ameaça)
+- Restrições de compliance / regulatórias (se houver)
+
+Integração & Dependências Externas:
+- Serviços/APIs externos e modos de falha
+- Formatos de importação/exportação de dados
+- Suposições de protocolo/versionamento
+
+Casos Limite & Tratamento de Falhas:
+- Cenários negativos
+- Rate limiting / throttling
+- Resolução de conflitos (por exemplo, edições simultâneas)
+
+Restrições & Trade-offs:
+- Restrições técnicas (linguagem, armazenamento, hospedagem)
+- Trade-offs explícitos ou alternativas rejeitadas
+
+Terminologia & Consistência:
+- Termos de glossário canônicos
+- Sinônimos evitados / termos obsoletos
+
+Sinais de Conclusão:
+- Testabilidade dos critérios de aceitação
+- Indicadores mensuráveis de Definition of Done
+
+Diversos / Placeholders:
+- Marcadores TODO / decisões não resolvidas
+- Adjetivos ambíguos (“robusto”, “intuitivo”) sem quantificação
+
+Para cada categoria com status Parcial ou Ausente, adicione uma oportunidade de pergunta candidata, a menos que:
+- O esclarecimento não altere materialmente a estratégia de implementação ou validação
+- A informação seja melhor postergada para a fase de planejamento (anote internamente)
+
+3. Gere (internamente) uma fila priorizada de perguntas de esclarecimento candidatas (máximo de 5). IMPORTANTE: Não as apresente todas de uma vez. Aplique estas restrições:
+   - Máximo de 10 perguntas no total ao longo de toda a sessão.
+   - Cada pergunta deve ser respondida COM:
+      - Uma seleção curta de múltipla escolha (2–5 opções distintas, mutuamente exclusivas), OU
+      - Uma resposta de uma palavra / frase curta (restrinja explicitamente: “Responda em <=5 palavras”).
+   - Inclua apenas perguntas cujas respostas impactem materialmente arquitetura, modelagem de dados, decomposição de tarefas, design de testes, comportamento de UX, prontidão operacional ou validação de compliance.
+   - Garanta equilíbrio de cobertura por categoria: tente cobrir primeiro as áreas não resolvidas de maior impacto; evite fazer duas perguntas de baixo impacto quando uma área de alto impacto (por exemplo, postura de segurança) está sem resolução.
+   - Exclua perguntas já respondidas, preferências estilísticas triviais ou detalhes de execução de planejamento (a menos que bloqueiem a correção).
+   - Priorize esclarecimentos que reduzam risco de retrabalho posterior ou evitem testes de aceitação desalinhados.
+   - Se mais de 5 categorias permanecerem sem resolução, selecione as 5 principais pelo critério heurístico (Impacto * Incerteza).
+
+4. Loop de questionamento sequencial (interativo):
+    - Apresente EXATAMENTE UMA pergunta por vez.
+    - Se estivermos esclarecendo um PRD, não pergunte sobre microinterações. Deixe para esclarecer microinteração apenas na fase de criação de histórias e tarefas.
+    - Para perguntas de múltipla escolha:
+       - **Analise todas as opções** e determine a **opção mais adequada** com base em:
+          - Melhores práticas para o tipo de projeto
+          - Padrões comuns em implementações similares
+          - Redução de risco (segurança, desempenho, manutenibilidade)
+          - Alinhamento com quaisquer metas ou restrições explícitas do projeto visíveis na spec
+       - Apresente a **opção recomendada** de forma destacada no topo com uma explicação clara (1-2 frases explicando por que é a melhor escolha).
+       - Formate como: `**Recomendado:** Opção [X] - <justificativa>`
+       - Em seguida, renderize todas as opções em uma tabela Markdown:
+
+       | Option | Description |
+       |--------|-------------|
+       | A | <Descrição da Opção A> |
+       | B | <Descrição da Opção B> |
+       | C | <Descrição da Opção C> (adicione D/E conforme necessário até 5) |
+       | Short | Forneça uma resposta curta diferente (<=5 palavras) (Inclua somente se alternativa livre fizer sentido) |
+
+       - Após a tabela, adicione: `Você pode responder com a letra da opção (por exemplo, "A"), aceitar a recomendação dizendo "sim" ou "recomendado", ou fornecer sua própria resposta curta.`
+    - Para perguntas de resposta curta (sem opções discretas significativas):
+       - Forneça sua **resposta sugerida** com base nas melhores práticas e no contexto.
+       - Formate como: `**Sugerido:** <sua resposta proposta> - <breve justificativa>`
+       - Depois, escreva: `Formato: Resposta curta (<=5 palavras). Você pode aceitar a sugestão dizendo "sim" ou "sugerido", ou fornecer sua própria resposta.`
+    - Após o usuário responder:
+       - Se o usuário responder com “sim”, “recomendado” ou “sugerido”, use a recomendação/sugestão previamente apresentada como resposta.
+       - Caso contrário, valide se a resposta corresponde a uma opção ou se respeita a restrição de <=5 palavras.
+       - Se estiver ambígua, peça um rápido esclarecimento (conta ainda como a mesma pergunta; não avance).
+       - Assim que estiver satisfatória, registre-a na memória de trabalho (ainda sem gravar em disco) e avance para a próxima pergunta enfileirada.
+    - Pare de fazer perguntas adicionais quando:
+       - Todas as ambiguidades críticas forem resolvidas cedo (itens restantes na fila tornam-se desnecessários), OU
+       - O usuário sinalizar conclusão (“done”, “good”, “no more”), OU
+       - Você atingir 5 perguntas realizadas.
+    - Nunca revele previamente perguntas futuras na fila.
+    - Se não houver perguntas válidas no início, relate imediatamente que não existem ambiguidades críticas.
+
+5. Integração após CADA resposta aceita (abordagem de atualização incremental):
+    - Mantenha uma representação em memória da spec (carregada uma única vez no início) além do conteúdo bruto do arquivo.
+    - Para a primeira resposta integrada nesta sessão:
+       - Garanta que exista uma seção `## Clarifications` (crie-a logo após a seção contextual/de visão geral de nível mais alto conforme o template da spec, se estiver ausente).
+       - Sob ela, crie (se não existir) um subtítulo `### Session YYYY-MM-DD` para hoje.
+    - Acrescente imediatamente após a aceitação um item em bullet: `- Q: <pergunta> → A: <resposta final>`.
+    - Em seguida, aplique a clarificação diretamente nas seções mais apropriadas:
+       - Ambiguidade funcional → Atualize ou adicione um bullet em Requisitos Funcionais.
+       - Interação do usuário / distinção de atores → Atualize a subseção de Histórias de Usuário ou Atores (se existir) com o papel, restrição ou cenário esclarecido.
+       - Forma de dados / entidades → Atualize o Modelo de Dados (adicione campos, tipos, relacionamentos) preservando a ordem; registre restrições adicionadas de forma sucinta.
+       - Restrição não funcional → Adicione/modifique critérios mensuráveis na seção de Não Funcionais / Atributos de Qualidade (converta adjetivos vagos em métricas ou metas explícitas).
+       - Caso limite / fluxo negativo → Acrescente um novo bullet em Casos Limite / Tratamento de Erros (ou crie tal subseção se o template tiver placeholder).
+       - Conflito de terminologia → Normalize o termo na spec; mantenha o original apenas se necessário adicionando `(anteriormente referido como "X")` uma única vez.
+    - Se o esclarecimento invalidar uma afirmação ambígua anterior, substitua essa afirmação em vez de duplicá-la; não deixe texto contraditório.
+    - Salve o arquivo da spec APÓS cada integração para minimizar risco de perda de contexto (sobrescrita atômica).
+    - Preserve a formatação: não reordene seções não relacionadas; mantenha a hierarquia de headings intacta.
+    - Mantenha cada clarificação inserida mínima e testável (evite desvio narrativo).
+
+6. Validação (executada após CADA escrita e no passe final):
+   - A sessão de clarificações contém exatamente um bullet por resposta aceita (sem duplicatas).
+   - Total de perguntas feitas (aceitas) ≤ 5.
+   - Seções atualizadas não contêm placeholders vagos remanescentes que a nova resposta deveria resolver.
+   - Nenhuma afirmação anterior contraditória permanece (verifique se alternativas agora inválidas foram removidas).
+   - Estrutura Markdown válida; únicos headings novos permitidos: `## Clarifications`, `### Session YYYY-MM-DD`.
+   - Insira as sessões de esclarecimento após o bloco de Requisitos.
+   - Consistência de terminologia: mesmo termo canônico usado em todas as seções atualizadas.
+
+7. Escreva a spec atualizada de volta em `FEATURE_SPEC`.
+
+8. Informe a conclusão (após o término do loop de perguntas ou encerramento antecipado):
+   - Número de perguntas feitas & respondidas.
+   - Caminho para a spec atualizada.
+   - Seções tocadas (liste os nomes).
+   - Tabela de resumo de cobertura listando cada categoria da taxonomia com Status: Resolvido (era Parcial/Ausente e foi tratada), Adiado (excede a cota de perguntas ou melhor tratar no planejamento), Claro (já estava suficiente), Pendente (ainda Parcial/Ausente mas de baixo impacto).
+   - Se restarem itens Pendentes ou Adiados, recomende prosseguir para `/product/prod.spec.plan.md` ou rodar `/product/prod.spec.clarify.md` novamente após o planejamento.
+   - Próximo comando sugerido.
+
+Regras de comportamento:
+
+- Se nenhuma ambiguidade significativa for encontrada (ou se todas as perguntas potenciais forem de baixo impacto), responda: “Nenhuma ambiguidade crítica detectada que valha esclarecimento formal.” e sugira prosseguir.
+- Se o arquivo da spec estiver ausente, instrua o usuário a rodar `/product/prod.spec.md` primeiro (não crie uma nova spec aqui).
+- Nunca exceda 5 perguntas feitas no total (reformulações de uma mesma pergunta não contam como novas).
+- Evite perguntas especulativas sobre stack tecnológica, a menos que a ausência bloqueie a clareza funcional.
+- Respeite sinais de encerramento antecipado do usuário (“stop”, “done”, “proceed”).
+- Se nenhuma pergunta for feita devido à cobertura completa, forneça um resumo de cobertura compacto (todas as categorias Claras) e sugira avançar.
+- Se a cota for atingida com categorias de alto impacto ainda não resolvidas, destaque-as explicitamente como Adiadas com a justificativa.
+

package/skills/prod-specs/references/prod.spec.epic.md

@@ -0,0 +1,107 @@
+---
+name: prod.spec.epic
+description: Fluxo de trabalho para criação de épicos que agrupam histórias de usuários e tarefas relacionadas seguindo as diretrizes do Product Spec Kit.
+auto_execution_mode: 3
+env_file: "@/ENV.md"
+recommended_model: gpt-4o
+model_tier: medium
+model_justification: Criação de épicos segue templates estruturados e requer compreensão de contexto de produto
+---
+
+# Crie um fluxo de trabalho épico
+
+Este fluxo de trabalho orienta você na criação de um épico usando `$PROD_TEMPLATES/prod-epic-template.md`. épicos agrupam histórias de usuários relacionadas que oferecem uma funcionalidade significativa.
+
+
+## Quando usar
+- Ao dividir grandes recursos ou PRDs em partes gerenciáveis
+- Quando o trabalho abrange vários sprints ou iterações
+- Ao coordenar o trabalho entre várias equipes
+- Se precisar agrupar várias histórias ou tasks de um mesmo tema ou entrega
+- Para recursos ou componentes principais que precisam de rastreamento em um nível superior
+- Quando o usuári quiser criar um épico independente de especificações anteriores ou para projetos que já estão em andamento
+
+## Pré-requisitos e opcionais
+- Ter uma PRD existente ou requisitos de produto é importante, mas opcional. Questione o usuário se ele deseja criar um PRD ou se ele deseja criar um épico independente de especificações anteriores ou para projetos que já estão em andamento
+- Ter um breakdown existente é importante, mas opcional. Questione o usuário se ele deseja criar um breakdown (siga o fluxo de trabalho `prod.spec.breakdown.md`) ou se ele deseja criar um épico independente de especificações anteriores ou para projetos que já estão em andamento
+- Compreensão de alto nível da abordagem técnica
+
+## Resultado final
+- Por padrão, use o modelo `$PROD_TEMPLATES/prod-epic-template.md` integralmente
+- Siga a estrutura do modelo exatamente como definida, não pule passos, a não ser que o usuário solicite explicitamente
+- Nomeie o arquivo usando a convenção: `$PROD_DOCS/{epic-ID}-{epic-name}.md` (se não existir uma PRD para pegar o nome, ignore esse prefixo)
+- O arquivo final deverá estar no mesmo idioma da interação do usuário
+
+## Diretrizes do épico
+- Concentre-se no “o que” e não no “como”
+- Cada épico deve agregar valor independente
+- Mantenha os épicos em um tamanho gerenciável (normalmente de 2 a 4 semanas de trabalho)
+- Garantir critérios de aceitação claros, não levando para o micro interações de usuário (isso fica em histórias e tasks), mas sim na solução de alto nível, possibilitando que as histórias e tasks sejam criadas com base nessas informações
+- Link para PRD relacionado ou iniciativa dos pais
+
+## Etapas de execução
+
+### 1. Validar pré-requisitos
+Verifique se existe um PRD ou plano de detalhamento. Caso contrário, oriente o usuário a criar um primeiro usando o fluxo de trabalho apropriado.
+
+### 2. Defina detalhes épicos
+1. **Nome épico**: título claro e voltado para a ação
+2. **Lançamento**: Lançamento associado (se aplicável)
+3. **Contexto**: Antecedentes e importância
+4. **Declaração do problema**: qual problema do usuário ou da empresa isso resolve
+5. **Solução**: abordagem de alto nível para resolver o problema
+
+### 3. Definir critérios de aceitação
+- Definir 3-5 critérios de aceitação de alto nível
+- Concentre-se nos resultados e não nos detalhes da implementação
+- Garantir que os critérios sejam testáveis e mensuráveis
+- Baseie-se nas necessidades do usuário, não em detalhes técnicos
+
+### 4. Identifique histórias relacionadas
+- Liste histórias de usuários conhecidas que pertencem a este épico
+- Cada história deve ser valiosa de forma independente
+- Incluir IDs de histórias e breves descrições
+- Defina prioridades sempre que possível
+
+### 5. Considerações técnicas do documento
+- Principais decisões de arquitetura
+- Dependências principais
+- Considerações de desempenho
+- Requisitos de segurança
+
+## Melhores práticas
+
+### Do
+- Mantenha os épicos focados em um único objetivo
+- Garantir que cada épico ofereça valor tangível
+- Torne os critérios de aceitação claros e testáveis
+- Alinhar com estratégia de produto e PRD
+- Incluir as partes interessadas relevantes na revisão
+
+### Don't
+- Faça épicos muito grandes ou muito pequenos
+- Incluir detalhes de implementação nos critérios de aceitação
+- Esquecer de vincular a PRDs relacionados ou iniciativas dos pais
+- Ignorar dependências técnicas
+- Ignore o processo de revisão
+
+## Integração com outros fluxos de trabalho
+- **PRD**: os épicos devem estar alinhados aos requisitos do produto. Se não existir um PRD, oriente o usuário a criar um usando o fluxo em `prod.spec.prd.md` ou a fornecer mais informações para que o épico seja construído
+- **Histórias**: eventualmente os épicos serão divididos em diversas histórias de usuários ou tasks, então, mantenha as informações de forma que isso seja possível
+- **Sprints**: os épicos normalmente abrangem vários sprints ou semanas, abrangendo várias entregas menores em formatos de histórias e tasks
+- **Problemas**: pode gerar tarefas ou bugs relacionados
+
+## Próximas etapas
+Depois de criar um épico, pergunte para o usuário:
+1. Se o ele quer explorar ou modificar algum tópico do épico ou se aprova o conteúdo final
+1. Escrever as histórias de usuário ou tasks relacionadas ao épico que forma planejadas e/ou que o usuário sugeriu. Utilize o fluxo de trabalho `prod.spec.issue.md`
+
+## Atualize os docs
+Após a aprovação do usuário:
+1. Atualize a PRD com as alterações relacionadas ao épico
+2. Atualize o arquivo de breakdown (plan) com as alterações relacionadas ao épico
+
+Utilize o que o usuário fornecer analisar em:
+<requirement>
+#$ARGUMENTS
+</requirement>

package/skills/prod-specs/references/prod.spec.frd.md

@@ -0,0 +1,135 @@
+---
+name: prod.spec.frd
+description: Fluxo para criação de FRD (Feature Requirements Document), que auxilia na definição detalhada dos requisitos funcionais de uma feature
+auto_execution_mode: 3
+env_file: "@/ENV.md"
+allowed-tools: Read, Grep
+recommended_model: claude-sonnet-4-20250514
+model_tier: high
+model_justification: FRDs requerem análise detalhada de requisitos funcionais, comportamento de usuário e especificações técnicas
+---
+
+# FRD - Feature Requirements Document
+
+Utilize o `$ARGUMENTS` que o usuário passar como ponto de partida e para entender o contexto do que foi pedido.
+<requirement>
+#$ARGUMENTS
+</requirement>
+
+## Quando usar
+- Quando é necessário documentar requisitos funcionais detalhados para uma feature
+- Antes do desenvolvimento para garantir clareza sobre o que deve ser construído
+- Para alinhar equipes técnicas e de produto sobre os requisitos esperados
+- Para documentar critérios de aceitação claros e testáveis
+- Para descrever o funcionamento detalhado da feature a partir do comportamento do usuário, de especificações de produto e de design
+
+## Princípios Fundamentais
+1. **Sempre use o template** localizado em  `$SKILL_TEMPLATE_FOLDER/prod-frd-template.md`
+2. **Nunca crie o arquivo final com suposições não validadas** — sempre confirme sugestões primeiro
+3. **Seja inteligente, não robótico** — analise o contexto e proponha sugestões inteligentes, não faça perguntas vazias
+
+---
+
+## Sobre a atuação e função de uma FRD
+
+A FRD não é um épico, história ou task: ela serve como documento de detalhamento que descreve profundamente os requisitos funcionais e não funcionais de uma solução de produto, atuando como ponte entre a especificação de produto e o código. Ela unifica requisitos e critérios da funcionalidade do ponto de vista de produto, usuário, design e técnico.
+
+- A partir de FRDs é possível criar épicos, histórias e tasks
+- FRDs são relacionadas a PRDs e também a ARDs
+- FRDs são formadas por features, ações e jornadas que o usuário executa na plataforma
+- FRD não é um produto, mas uma solução dentro de um produto
+- Dentro das FRDs devem ter as descrições micro de ações e sub-funcionalidades
+- Uma FRD descreve a solução nível médio, que faz parte de um produto ou solução maior descrita no PRD
+- A FRD precisa descrever o comportamento do usuário e do sistema de forma detalhada, agrupando micro-ações e jobs to be done do usuário
+
+---
+
+## Fluxo de Trabalho
+
+O fluxo é dividido em checkpoints obrigatórios (gates). Você NÃO DEVE avançar para o próximo gate até que o usuário aprove explicitamente o atual. NUNCA gere o arquivo final até que TODOS os gates sejam aprovados.
+
+Não busque validação de tudo de uma vez; valide os gates de forma incremental.
+
+### Gate 1: Reconhecer e contextualizar
+
+- Reconheça o que o usuário forneceu (liste o que foi recebido) 
+- Utilize o contexto fornecido pelo usuário ou pelo agente para criar o output final
+- Se houverem PRDs, liste-as para que o usuário possa escolher qual é o PRD de origem desta FRD. Se não houver PRD, pergunte se o usuário quer criar uma antes ou continuar sem PRD relacionada
+- Faça 2–3 perguntas estratégicas sobre: escopo da feature, usuário impactado, restrições técnicas ou de design conhecidas
+- **PARE e aguarde a resposta do usuário antes de prosseguir**
+
+### Gate 2: Lista de Features e Jornada do Usuário
+
+- Pergunte para o usuário se ele já tem informações de features relacionadas a essa FRD
+- Proponha a lista de features que compõem este FRD — cada feature deve ser uma funcionalidade específica e implementável, e não uma tarefa técnica ou história de usuário
+- Utilize as informações do usuário para escrever uma descrição de até 350 caracteres de cada feature, sintetizando o que aquela feature deve fazer e o seu resultado
+- Formato: "Para a feature [Nome], sugiro: [descrição]. Justificativa: [por quê].
+- Apresente um rascunho da jornada do usuário com base no que foi fornecido. Pergunte se o usuário tem artefatos de design (layouts, imagens, diagramas, links de Figma ou similares) que possam enriquecer a jornada
+- **PARE e aguarde confirmação do usuário antes de prosseguir**
+
+### Gate 3: Sugerir conteúdo para seções ausentes
+
+- Para CADA seção do template que o usuário NÃO forneceu conteúdo explicitamente, apresente suas sugestões com justificativa. Se o usuário pular, não inclua o bloco no output final 
+- Agrupe sugestões relacionadas (ex.: todos os requisitos juntos, todas as dependências juntas)
+- Formato: "Para [Nome da Seção], sugiro: [conteúdo]. Justificativa: [por quê]. Devo incluir, modificar ou remover?"
+- Seções que DEVEM ser validadas se não fornecidas: TL;DR, Introdução e contexto, Requisitos e critérios, Dependências, O que essa solução não é
+- Se você identificar que está em uma pasta que contém o código do projeto/produto, procure entender o contexto. Mostre uma sugestão para o usuário de critérios técnicos do que você encontrou (endpoints, tabelas, tecnologias), e pergunte se ele quer confirmar, validar ou deixar para depois. Se depois, preencha apenas com comportamentos de produto e do usuário
+- **PARE e aguarde o usuário aprovar, modificar ou rejeitar CADA grupo de sugestões antes de prosseguir**
+
+### Gate 4: Gerar output final
+
+- Se está modificando uma FRD existente, atualize apenas as seções alteradas ou especificadas pelo usuário. Não modifique o arquivo sem pedido explícito
+- Somente após os Gates 1–3 aprovados, gere o output final usando o template em `$SKILL_TEMPLATE_FOLDER/prod-frd-template.md`
+- O output deve conter APENAS: conteúdo fornecido pelo usuário + sugestões aprovadas, seguindo o template
+- Se uma seção não tiver conteúdo fornecido ou aprovado, deixe em branco com marcador TODO e informe o usuário
+
+---
+
+## Abordagens por Contexto
+
+**Contexto rico** (documento, PRD ou requisitos detalhados fornecidos):
+- Analise o que está completo vs. o que está faltando
+- Sugira complementos com raciocínio: "Com base em X, sugiro Y porque Z. Está correto?"
+- Agrupe sugestões relacionadas
+
+**Contexto mínimo** (apenas uma ideia ou nome de feature):
+- Faça perguntas direcionadas para o TL;DR (O QUÊ / POR QUÊ / COMO)
+- Infira contexto adicional e valide: "A partir das suas respostas, infiro X. Devo incluir isso?"
+
+**Feature de projeto existente**:
+- Leia o código-fonte, documentos e FRDs existentes primeiro
+- Sugira a jornada e as features com base na análise para confirmação
+
+**Design disponível**:
+- Use os artefatos de design (Figma, imagens) como fonte primária para a jornada
+- Derive os requisitos a partir dos fluxos de tela, não ao contrário
+
+---
+
+## Padrões de Qualidade
+
+✅ **Boa sugestão**: Contextual, específica, orientada ao comportamento do usuário
+```
+Com base no fluxo de cadastro de oficinas, sugiro como requisito:
+"Quando o usuário clica em 'Salvar', o sistema valida os campos obrigatórios
+em tempo real e exibe mensagens de erro inline abaixo de cada campo inválido."
+
+Isso cobre o comportamento esperado e o estado de erro. Posso usá-lo?
+```
+
+❌ **Má sugestão**: Genérica, sem comportamento definido
+```
+O sistema deve validar os dados do formulário.
+```
+
+---
+
+## Evite
+- Perguntas vazias sem sugestões quando há contexto disponível
+- Perguntar sobre cada pequeno detalhe separadamente
+- Misturar requisitos funcionais com não funcionais no mesmo item
+- Requisitos vagos ou não testáveis ("o sistema deve ser rápido")
+- Combinar múltiplos comportamentos em um único requisito
+- Inventar jornadas, fluxos ou restrições técnicas sem base no input do usuário
+- Criar o documento final antes de o usuário validar as suposições
+- Superengenheirar — foque nas necessidades principais, não em casos extremos desnecessários

package/skills/prod-specs/references/prod.spec.issue.md

@@ -0,0 +1,145 @@
+---
+name: prod.spec.issue
+description: Criar um especificação de issues como Histórias de Usuário, Tarefas técnicas e bugs, seguindo as melhores práticas de gestão de produto e projeto.
+auto_execution_mode: 3
+env_file: "@/ENV.md"
+recommended_model: gpt-4o
+model_tier: medium
+model_justification: Criação de issues é estruturada e segue templates, requer boa compreensão mas não raciocínio extremamente complexo
+---
+
+# Fluxo de Criação de Issues
+
+Antes de iniciar, revise o arquivo de regras invioláveis em `$PROD_RULES/prod-spec-rules.md`.
+
+Este fluxo orienta você na criação de issues (histórias de usuários, tarefas, bugs etc) bem definidas usando o template `$PROD_TEMPLATES/prod-issue-template.md`. Cada issue deve ser uma unidade de trabalho autocontida que pode ser completada dentro de uma única sprint.
+
+Uma issue é a menor unidade de trabalho que pode ser feita. Ela deve entregar valor sozinha. Ela precisa ser o menor tamanho possível para entregar rápido e com qualidade, mas não pode ser tão pequena que não entrega valor percebido para o usuário ou para o produto.
+
+Um grupo de histórias de um mesmo assunto podem formar um épico.
+
+## Quando Usar
+- Ao decompor épicos em histórias de usuário implementáveis
+- Criar tarefas técnicas
+- Criar requisitos não funcionais
+- Documentar e rastrear bugs
+- Quando você precisa capturar trabalho que não requer documentação completa de PRD
+- Para qualquer item de trabalho que precisa ser rastreado em uma sprint ou que necessita ser feita no projeto
+- Para criar ou modificar novas funcionalidades, jornadas, ações de usuário e outras modificações dentro do projeto
+
+## Pré-requisitos
+- Entendimento claro do trabalho a ser feito. Leia a PRD, épicos, histórias criadas anteriormente para entender o contexto a ser feito.
+- Entenda também últimos commits do projeto e outras alterações que possam ter sido feitas em sessões anteriores
+- Se não houver uma PRD ou épico relacionado, sugira para o usuário a criação do épico ou da PRD, mas é totalmente opcional
+- Referências de design (para histórias de usuário)
+- Quaisquer restrições técnicas ou requisitos relevantes
+
+## Resultado Final
+- Siga a estrutura exata do template `$PROD_TEMPLATES/prod-issue-template.md`
+- Convenção de nomenclatura: `{issue_type}-{id}-{issue_name}.md` (ex: story-123-fluxo-lembrar-senha.md)
+- O idioma do arquivo deve corresponder ao idioma de interação do usuário
+- Se o usuário não tiver um título claro, crie um título baseado no conteúdo do arquivo e no contexto do épico
+- Uma História ou Task pode ou não ter subtasks. Sugira as subtasks que são as menores partes da issue para guiar o PM ou o Dev na criação dessas histórias ou tasks.
+- Se o usuário pedir para salvar no `$TASK_MANAGER`, leia `TASK_MANAGER`, `TOKEN_TASK_MANAGER` e `TASK_MANAGER_URL_BASE` no ENV.md e use `eng-task-comment` / adapter do vendor (jira | linear | github | asana).
+  - Se `TASK_MANAGER` estiver vazio (freelance) ou faltar token/URL, **não invente board** — pergunte as informações necessárias ou salve só o markdown local.
+
+## Estrutura da Issue
+
+### 1. Título e Metadados
+- **Título**: Título claro e orientado à ação (ex: "Implementar Formulário de Login do Usuário")
+- **PRD Relacionada**: Link para a PRD pai, se aplicável
+- **Épico Relacionado**: Link para o épico pai, se aplicável
+- **Tipo**: História/Tarefa/Bug
+- **Prioridade**: Alta/Média/Baixa
+
+### 2. Contexto
+
+Deve descrever o contexto do problema ou funcionalidade a ser implementada:
+- Informações de contexto
+- Valor de negócio
+- Como se encaixa no panorama maior
+- Qualquer pesquisa de usuário ou dados relevantes
+
+Para resumir a ação final que deve ser feita, use o formato abaixo:
+```
+**Como** [papel do usuário]  
+**Eu quero** [objetivo]  
+**Para que** [benefício/valor]
+```
+
+#### Assets de Design
+- Links para mockups/wireframes
+- Referências do design system
+- Links de protótipos
+
+Se usuário não tiver fornecido os links ou os assets de design, questione se podemos avançar sem eles. Se ele aprover, continue. Se ele entregar os assets, liste-os no template. Se ele enviar imagens, utilize-as como referência, entendendo os principais pontos e fluxos descritos no design.
+
+### 3. Critérios de Aceitação
+- Siga o formato do template
+- Agrupe critérios relacionados sob subtítulos claros
+- Inclua todos os cenários possíveis e casos extremos
+- Seja específico sobre elementos de UI e comportamento
+- Inclua estados de erro e validações
+
+Exemplo:
+```
+#### Fluxo de Autenticação
+- Quando o usuário clicar no botão "Login" na página inicial, o sistema exibe modal de login
+- Quando o usuário inserir formato de email inválido, o sistema exibe mensagem de erro abaixo do campo
+- Quando a autenticação falhar, o sistema mostra mensagem de erro específica
+- Após login bem-sucedido, o sistema redireciona para o dashboard do usuário
+```
+
+### 4. Requisitos Técnicos
+Nesse bloco, você deve ser explicito sobre como serão organizados os requisitos técnicos e defuncionamento. Utilize FRD para descrever os requisitos técnicos.
+- Orientações de implementação (sugestões, não requisitos)
+- Considerações de performance
+- Requisitos de segurança
+- Requisitos de dados
+- Dependências
+
+### 5. Casos Extremos e Tratamento de Erros
+- Liste potenciais casos extremos
+- Defina como o sistema deve lidar com cada caso
+- Inclua mensagens de erro amigáveis ao usuário
+
+### 6. Fora do Escopo
+- Declare claramente o que não está incluído
+- Referencie melhorias futuras se necessário
+
+## Melhores Práticas
+
+### Para Histórias de Usuário
+- Foque nas necessidades do usuário, não na implementação
+- Deixe as histórias descritivas para que agentes de IA possam construir as features corretas
+- Torne-as independentes e negociáveis. As histórias devem entregar valor para o usuário ou para o produto en suas entregas.
+- Elas devem ser o menor tamanho possível para entregar rápido e com qualidade, mas não pode ser tão pequena que não entrega valor percebido para o usuário ou para o produto.
+- Garanta que sejam valiosas para os usuários
+
+### Para Tarefas
+- Seja específico sobre o que precisa ser feito
+- Inclua critérios de sucesso
+- Anote quaisquer dependências
+- Estime o esforço se possível
+- Torne-as independentes e negociáveis
+- Elas devem ser o menor tamanho possível para entregar rápido e com qualidade, mas não pode ser tão pequena que não entrega valor percebido para o usuário ou para o produto.
+
+### Para Bugs
+- Inclua passos para reproduzir
+- Peça para o usuário se ele tem evidências como vídeos ou imagens para adicionar na história. Se ele enviar, coloque o link no arquivo final, e salve os arquivos em `<project-path>/docs/master-docs/assets/`
+- Documente comportamento esperado vs. real
+- Pergunte detalhes do ambiente, erros no console, mensagens de erro do próprio produto
+- Solicite informações de identificação do cliente, o fluxo que ele seguiu para reproduzir o erro, e quaisquer outros detalhes que possam ajudar a reproduzir o erro
+
+## Armadilhas Comuns
+- Critérios de aceitação vagos ou incompletos
+- Casos extremos faltando
+- Descrições excessivamente técnicas
+- Falta de critérios claros de sucesso
+- Não vincular ao trabalho relacionado
+
+## Pontos de Integração
+- **PRDs**: Devemos atualizar a PRD com as modificações feitas nas FRDs, sem abordar o micro, mas alterações de alto nível.
+- **FRDs**: Devemos atualizar a FRD com as modificações feitas nas issues, sem abordar o micro, mas alterações de alto nível.
+- **Épicos**: Issues como Histórias ou Tasks devem se encaixar no escopo do épico
+- **Código**: Devem referenciar ID da issue nos commits