diff --git a/.agents/workflows/utf-design.md b/.agents/workflows/utf-design.md index 1d3dcda..51188a4 100644 --- a/.agents/workflows/utf-design.md +++ b/.agents/workflows/utf-design.md @@ -55,6 +55,19 @@ não consegue guardar — os tokens, os breakpoints e as decisões de abandono. `docs/design-tokens.md` e no README. O protótipo é a jornada navegável: telas das stories principais, no fluxo real. + Explique por que **três a cinco telas, e não todas** (guia, §3.5): a tela desenhada + antes da spec envelhece, e quem mantém a coerência entre as telas são os tokens. As + demais telas nascem no ciclo de cada história. + + **Confira o conteúdo das telas contra o `docs/prd.md`.** Se o MCP da ferramenta + estiver conectado, leia o texto de cada tela; senão, peça ao aluno que o percorra + com você. Ferramenta de protótipo inventa regra de negócio — preço, prazos, + "verificado", "certificado", filtros que o PRD deixou fora de escopo. Cada + contradição vira uma **pendência do protótipo** no documento, para a equipe corrigir + a tela; não vira requisito, e não é aceita em silêncio. Registre também: **quando + protótipo e documentos divergirem, vale o documento** — o `design-tokens.md` para a + aparência, o `prd.md` para o conteúdo. + ## Passo 2 — Mobile-First (ID2) Pergunte e registre nos tokens: os **breakpoints** e a regra de layout — o design diff --git a/.agents/workflows/utf-issue.md b/.agents/workflows/utf-issue.md index e893b34..e6eebf9 100644 --- a/.agents/workflows/utf-issue.md +++ b/.agents/workflows/utf-issue.md @@ -15,7 +15,7 @@ Sempre que o usuário pedir para trabalhar em uma Issue (Feature), você atuará - Leia a Issue apontada e busque no `docs/prd.md` os critérios e o Glossário Ubíquo. - Faça perguntas ao usuário de forma proativa. Questione sobre casos de borda, caminhos tristes (ex: falhas de rede, dados inválidos) e como validar os critérios de aceite. - Após sanar as dúvidas, **crie a branch da história a partir da `develop`** (`git switch develop && git pull && git switch -c feature/-`). Ela nasce agora, antes da aprovação, porque no Gitflow `main` e `develop` são bloqueadas — e o commit de aprovação do usuário precisa de um lugar para viver. -- Redija o documento e salve no caminho `specs/-/spec.md`, commitando o rascunho na branch. **A estrutura é a de `docs/modelo-spec.md`** — copie-a e preencha; os comentários dela explicam cada seção e são apagados no caminho. Não invente seções novas nem pule as existentes. O frontmatter: +- Redija o documento e salve no caminho `specs/-/spec.md`, commitando o rascunho na branch. **A estrutura é a de `docs/modelo-spec.md`** — copie-a e preencha; os comentários dela explicam cada seção e são apagados no caminho. Não invente seções novas nem pule as existentes. Se a história tem tela, a referência visual é o `docs/design-tokens.md` — não o protótipo, que tem só as telas principais e pode estar desatualizado. Se a tela desta história ainda não existe no protótipo, ela nasce agora, a partir da spec aprovada e dos tokens; se existe, confira o texto dela contra os critérios desta spec — o que a tela mostra e a spec não pede é fora de escopo, não requisito. O frontmatter: ```yaml --- diff --git a/docs/design-tokens.md b/docs/design-tokens.md index dfada83..a9e2c50 100644 --- a/docs/design-tokens.md +++ b/docs/design-tokens.md @@ -6,7 +6,7 @@ > 🤖 **Este documento existe para a IA parar de inventar um botão diferente a cada > tela.** Não é um design system — é o mínimo que dá à prototipagem assistida algo a -> que obedecer. +> que obedecer. **Quando o protótipo e este documento divergirem, vale este documento.** > > ✍️ **Não preencha na mão:** rode `/utf-design`. diff --git a/docs/guia-sdd.md b/docs/guia-sdd.md index 0d9300e..3f0e9c5 100644 --- a/docs/guia-sdd.md +++ b/docs/guia-sdd.md @@ -243,6 +243,30 @@ problema real, que é a IA inventar um botão diferente a cada tela, é bem meno Com isso no repositório, a prototipagem assistida por IA tem a que obedecer. Sem isso, cada tela nasce de um gosto diferente. +**Por que três a cinco, e não todas.** O protótipo é a jornada (§3.4) e é avaliado +(ID1) — mas "três a cinco" não é um mínimo a superar, é uma escolha: + +- **A tela envelhece antes de ser construída.** Cada história ainda vai passar pela + conversa do `/utf-issue`, que quase sempre ajusta detalhes. Uma tela desenhada hoje + para uma história que só será feita daqui a semanas chega errada ao ciclo, e alguém + vai confiar nela. +- **Quem mantém as telas coerentes é o `design-tokens.md`, não o protótipo.** Com + paleta, escala, tipografia, estados de botão e breakpoints escritos, a tela feita + durante a história já nasce igual às outras. + +Escolha as telas **das jornadas principais e arriscadas**: onde a pessoa trava, espera +ou desiste, e onde uma decisão de tela errada custa caro. **As demais nascem no ciclo de +cada história**, a partir da spec aprovada e dos tokens. + +**A ferramenta de protótipo inventa regra de negócio.** Gerador de tela por IA preenche +o vazio com o que é comum no mercado: põe preço onde o PRD decidiu não ter, promete +"disponível imediatamente", "verificado" ou "certificado" onde o sistema não confere +nada, cria filtro que o PRD deixou fora de escopo. Por isso: gere as telas **depois** do +`prd.md`, nunca antes, e **leia o texto** de cada tela contra ele — conteúdo de +protótipo não é requisito. Quando protótipo e documentos divergem, vale o documento: o +`design-tokens.md` para a aparência, o `prd.md` para o conteúdo — e o protótipo, que é +entrega avaliada, é corrigido para concordar com eles. + Os tokens, os breakpoints, a identidade PWA e o link do protótipo saem do mesmo comando, o `/utf-design`. ### 3.6 A regra de ouro dos documentos diff --git a/docs/modelo-spec.md b/docs/modelo-spec.md index 1a6782e..5108823 100644 --- a/docs/modelo-spec.md +++ b/docs/modelo-spec.md @@ -43,8 +43,10 @@ status: rascunho # rascunho | aprovada ## Abandono no meio