Guia de Criação de Issues¶

Este documento define o padrão para criação de issues no projeto Ciba. O objetivo é manter consistência, clareza e o nível certo de detalhe para cada tipo de issue.

Filosofia¶

Issue é produto, não código — Foco no comportamento e valor, não na implementação
Direciona sem amarrar — Sugestões e indicações são bem-vindas, código detalhado não
Refinamento vem depois — Quando o dev puxar o card, aí sim arquiteta a solução
Escopo claro — O que está dentro e fora da issue deve ser explícito

Tipos de Issues¶

Tipo	Prefixo	Uso
Feature	`feat:`	Nova funcionalidade
Bug	`fix:`	Correção de problema
Melhoria	`improve:`	Melhoria em feature existente
Tech Debt	`chore:`	Refatoração, cleanup, infra
Docs	`docs:`	Documentação

Labels¶

Por Tipo¶

Label	Cor	Descrição
`feature`	`#a2eeef`	Nova funcionalidade
`bug`	`#d73a4a`	Problema a corrigir
`improvement`	`#84b6eb`	Melhoria em existente
`tech-debt`	`#fbca04`	Débito técnico
`docs`	`#0075ca`	Documentação

Por Módulo¶

Label	Cor	Descrição
`agents`	`#0e8a16`	Módulo de Agentes
`conversations`	`#006b75`	Módulo de Conversas
`instances`	`#d4c5f9`	Módulo de Instâncias WhatsApp
`auth`	`#b60205`	Autenticação e usuários
`admin`	`#c5def5`	Área administrativa
`crm`	`#f9d0c4`	CRM e gestão de contatos
`integrations`	`#5319e7`	Integrações externas

Por Prioridade¶

Label	Cor	Descrição
`priority:critical`	`#b60205`	Bloqueia uso do sistema
`priority:high`	`#d93f0b`	Importante para próximo ciclo
`priority:medium`	`#fbca04`	Desejável
`priority:low`	`#0e8a16`	Nice to have

Por Tamanho¶

Label	Cor	Descrição
`size:epic`	`#5319e7`	Épico - será quebrado em issues menores
`size:large`	`#1d76db`	Grande - vários dias de trabalho
`size:medium`	`#0e8a16`	Médio - 1-2 dias
`size:small`	`#c5def5`	Pequeno - algumas horas

Estrutura: Feature (feat:)¶

# feat: [Nome da Feature]

## Problema
[Qual dor ou necessidade essa feature resolve? 1-3 frases]

## Solução
[Descrição de alto nível do que será feito. 2-4 frases]

## Comportamento Esperado
[Lista numerada do fluxo principal do usuário]
1. Usuário faz X
2. Sistema responde com Y
3. ...

## Variações e Casos Especiais
[Cenários alternativos, edge cases, regras de negócio]
- Se X acontecer, então Y
- Quando Z, o sistema deve...

## Interface / UX
[Descrição de como o usuário interage - pode incluir esboços ASCII ou descrição de telas]
- Onde fica na navegação
- Principais elementos de UI
- Feedbacks visuais esperados

## Sugestões de Implementação (opcional)
[Indicações leves de como poderia ser feito - NÃO é obrigatório seguir]
- Provavelmente precisa de nova entidade X com campos A, B, C
- Pode reaproveitar o padrão de Y que já existe
- Considerar usar Z para...

## Critérios de Aceite
[Checklist objetivo para considerar "done" - foco em comportamento, não código]
- [ ] Usuário consegue fazer X
- [ ] Sistema valida Y
- [ ] Feedback Z é exibido

## Fora do Escopo
[O que NÃO será feito nessa issue - evita scope creep]
- Não inclui integração com X
- Versão mobile fica para depois
- ...

## Dependências (se houver)
[Issues ou features que precisam existir antes]
- Depende de #XX (feature Y)
- Nenhuma

Estrutura: Bug (fix:)¶

# fix: [Descrição curta do bug]

## Comportamento Atual
[O que está acontecendo de errado]

## Comportamento Esperado
[O que deveria acontecer]

## Passos para Reproduzir
1. Ir para X
2. Clicar em Y
3. Observar erro Z

## Contexto
- Ambiente: [Produção/Dev/Local]
- Browser/Dispositivo: [se relevante]
- Usuário afetado: [tipo de usuário]

## Possível Causa (opcional)
[Se souber ou suspeitar onde está o problema]

## Screenshots/Logs (se houver)
[Evidências do problema]

Estrutura: Melhoria (improve:)¶

# improve: [Nome da melhoria]

## Situação Atual
[Como funciona hoje]

## Proposta
[Como deveria funcionar / o que melhorar]

## Motivação
[Por que essa melhoria é importante]

## Comportamento Esperado
[Detalhamento do novo comportamento]

## Critérios de Aceite
- [ ] ...

Estrutura: Epic (size:epic)¶

Épicos são features grandes que serão quebradas em issues menores. Estrutura simplificada:

# feat: [Nome do Épico]

## Visão Geral
[Descrição ampla do que o épico entrega - 1 parágrafo]

## Objetivos
- Objetivo 1
- Objetivo 2
- ...

## Escopo de Alto Nível
[Lista de capacidades/funcionalidades incluídas]
- Capacidade A
- Capacidade B
- ...

## Issues Relacionadas
[Lista de issues que compõem o épico - atualizar conforme criar]
- [ ] #XX - Parte 1
- [ ] #XX - Parte 2
- ...

## Fora do Escopo
- ...

## Notas e Decisões
[Registro de decisões tomadas durante discussões]

Nível de Detalhe¶

Incluir¶

Comportamento do ponto de vista do usuário
Regras de negócio e validações
Fluxos alternativos e edge cases
Sugestões leves de campos/estruturas
Indicações de onde fica na UI
Critérios claros de "pronto"

Evitar¶

Código fonte (classes, métodos, endpoints exatos)
Estrutura detalhada de banco de dados
Nomes exatos de componentes/arquivos
Decisões de arquitetura que amarram a implementação

Regra de Ouro¶

Se alguém de produto consegue ler e entender a issue inteira, o nível está certo. Se precisa ser dev para entender, tem detalhe técnico demais.

Exemplos¶

Bom: Sugestão leve¶

"Provavelmente precisa de uma entidade para armazenar os lembretes, com campos como data/hora, mensagem, e referência à conversa."

Ruim: Detalhe técnico¶

public class Reminder
{
    public Guid Id { get; set; }
    public Guid ConversationId { get; set; }
    ...
}

Bom: Comportamento¶

"Quando o lembrete dispara, o sistema envia a mensagem automática pelo WhatsApp e notifica o atendente."

Ruim: Implementação¶

"Criar um BackgroundService que consulta a tabela de reminders a cada 30 segundos e usa o EvolutionApiClient para enviar."

Checklist antes de criar¶

[ ] Título segue o padrão tipo: descrição
[ ] Labels de tipo, módulo e prioridade aplicadas
[ ] Problema/motivação está claro
[ ] Comportamento esperado está descrito
[ ] Critérios de aceite são objetivos
[ ] Escopo está delimitado (o que está fora)
[ ] Nível de detalhe é produto, não código