ESP — Especificação e Histórias

O ponto de vista ESP (Especificação) é o núcleo de toda a especificação. Todos os demais pontos de vista consomem ou se subordinam às definições feitas aqui. Nenhuma história pode ser implementada sem estar registrada e aprovada no ESP (Especificação).

Subpastas do ESP (Especificação)

Subpasta	Documentos Esperados	Siglas
`00-indice/`	Índice e contexto	IDX, CTX
`01-visao-geral/`	Visão do produto e requisitos	VIS, BRD, PRD, STY
`02-historias/`	Histórias por tipo (11 subpastas)	HNI…HI
`03-decisoes/`	Decisões de escopo e requisitos	DEC
`04-evidencias/`	Validações e aprovações	EVD
`05-checklists/`	Listas de verificação	CHK
`06-modelos/`	Modelos de domínio e guias visuais	DOM, STY, TPL
`07-referencias/`	Referências externas	REF
`08-publicado/`	Versões aprovadas para consumo	—

11 Tipos de Histórias

Todas as histórias ficam em artefatos/ESP-Especificacao/02-historias/<TIPO>/ e seguem o padrão de nomenclatura ESP-<TIPO>-<NNNN>--<slug>.md.

HNI — Negócio Institucional

Processos e regras no nível organizacional: fluxos de aprovação, hierarquias, normas internas.

id: ESP-HNI-0001
tipo: HNI
titulo: "Fluxo de aprovação de pedidos"
status: rascunho  # rascunho | refinada | aprovada | implementada | cancelada

HNE — Negócio Especializado

Regras de negócio complexas: cálculos tributários, algoritmos de pontuação, lógica proprietária.

HNU — Negócio de Usuário

Tarefas e jornadas do usuário final. Formato canônico: “Como [persona], quero [ação] para [benefício].”

id: ESP-HNU-0001
tipo: HNU
persona: "Servidor público"
historia: "Como servidor público, quero registrar uma solicitação para acompanhá-la digitalmente."

HS — Sistema

Comportamentos internos automatizados: jobs, eventos, processos assíncronos, regras de cache.

HRD — Regra de Decisão

Condições lógicas explícitas: tabelas de decisão, regras de elegibilidade, validações.

regras:
  - condicao: "CPF já cadastrado"
    resultado: "Bloquear cadastro e exibir mensagem"

HUX — Experiência do Usuário

Requisitos de interface: estados de tela (vazio, erro, carregando, sucesso), responsividade, fluxos.

HC — Conformidade

Obrigações legais e regulatórias: LGPD, lei de acessibilidade, normas setoriais, auditorias.

norma: "LGPD Art. 7, inciso I — consentimento do titular"

HAI — Autenticação e Identidade

HAC — Acessibilidade

Requisitos WCAG 2.1 AA, leitores de tela, navegação por teclado, contraste mínimo.

criterio-wcag: "WCAG 2.1 AA 1.4.3 — Contrast (Minimum)"

HIVC — Identidade Visual e Comunicação

Aplicação do design system, microcopy, ícones, paleta de cores, tom de voz.

HI — Integração

APIs externas, sistemas legados, mensageria, webhooks, importação/exportação de dados.

sistema-externo: "Gateway de Pagamentos XYZ"
protocolo: "REST"
frequencia: "Tempo real"

Fluxo de Vida de uma História

stateDiagram-v2
    [*] --> rascunho: criação
    rascunho --> refinada: refinamento com time
    refinada --> aprovada: aprovação pelo PO/GTI (Governança de TI)
    aprovada --> implementada: IMP (Implementação) conclui + DOD atendido
    aprovada --> cancelada: descartada
    implementada --> [*]
    cancelada --> [*]

Regras de Validação

Todo artefato ESP (Especificação) deve ter: id, tipo, status, autor, data, criterios-de-aceite.
Histórias aprovadas exigem ao menos uma evidência em ESP (Especificação)/04-evidencias/.
Histórias de sistema (HS) devem referenciar ao menos uma HNU ou HNE de origem.
Integrações (HI) devem ter correspondência em IMP (Implementação)/03-decisoes/ (API contract).
Apenas artefatos com evidência em 04-evidencias/ podem ser movidos para 08-publicado/.