teqo-backup/docs/plans/ops114-plan-issue-design-hifi-no-gate-impl.md

136 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Impl: OPS114 — plan-issue: design hi-fi obrigatório no gate (substitui o rascunho low-fi)
Status: rascunho
Atualizado em: 2026-09-16
Issue: #1057
Intenção: docs/plans/ops114-plan-issue-design-hifi-no-gate.md
Appetite restante: herdado — doc-only em `.agents/skills/plan-issue/**`, ~0,5 dia eng
## Leitura da intenção
- **Outcome:** para item que muda UI (B/C/D), o gate passa a exigir `docs/plans/<slug>-ui-design.html` + `docs/plans/<slug>-ui-design-assets/*.svg` produzidos pelo sub-agente `designer`; o escritor do plano não gera mais UI e nenhuma referência ao low-fi (`ui-draft-html.md`, `-ui-draft.html`, "Rascunho UI") sobra na superfície da skill.
- **O que NÃO negociar:**
- Planos antigos e seus `-ui-draft.html`/PNGs ficam intactos (nenhum arquivo **existente** em `docs/plans/**` ou `docs/changelog/**` é editado, renomeado ou migrado).
- O design hi-fi não carrega lógica de negócio e não nomeia componente final; a doutrina do gate continua fora de `docs/plans/`.
- O painel/CLI e seus testes são OPS116 — **não** tocar aqui.
- `.opencode/commands/plan-issue.md` só delega à skill — não muda.
- **O que reavaliar:**
- **A varredura global "zero" da intenção é falsa como escrita.** Sobram hits de `-ui-draft` em `scripts/lib/issues-panel.mjs`, `scripts/issues-tui.mjs` e `tests/unit/issuesPanel.unit.spec.ts` — donos OPS116. A prova honesta é dupla: (a) **zero** em `.agents/**`/`.opencode/**`; (b) globalmente, o conjunto de hits é **exatamente** o set OPS116 pinado (não "vazio"). O PR registra os dois resultados em vez de fingir sweep vazio.
- **A verificação "nada sob `docs/plans/`" conflita com o contrato do `work-issue`.** A entrega commita o novo `ops114-…-impl.md` (este arquivo) e a entrada nova de changelog. O critério correto é: **nenhum arquivo antigo** de `docs/plans/**`/`docs/changelog/**` modificado; as únicas adições são `*-impl.md` e `docs/changelog/<data>-ops114.md`. O sweep do OPS114 não renomeia nem migra `-ui-draft.html`/PNGs — a prova de "planos antigos intactos" é o diff não conter nenhum caminho `-ui-draft`.
- A hipótese "há `git mv` a fazer" está errada: o rename já foi entregue no OPS113 (commit `488d7af7`, "rename puro") e `ui-design-html.md` é o único arquivo de doutrina na pasta. Só faltam os ponteiros.
- `ui-design-html.md:93` tem uma nota transitória ("`Rascunho UI:` hoje; `Design UI:` a partir do OPS114") — este item **é** o OPS114, então a nota deve ser finalizada para não virar stale.
## Abordagem recomendada
```mermaid
flowchart LR
idea["Ideia B/C/D (muda UI)"] --> expl["Explorador"]
expl --> writer["Escritor: plano SEM UI"]
writer --> designer["designer: -ui-design.html + -ui-design-assets/*.svg"]
designer --> disk["Orquestrador grava em docs/plans/"]
disk --> plan["Plano: campo Design UI: + seção + cenas 390/1280/estados"]
plan --> gate["GATE: abre o HTML, itera, confirma"]
```
**Opções consideradas:** A | B | C
- **A)** Atualizar os ponteiros da skill no lugar (`.agents/skills/plan-issue/SKILL.md`, `intention-template.md`, `shaping.md`, `skills-map.md`) e finalizar a nota transitória em `ui-design-html.md:93`; painel/CLI/testes intocados.
- **B)** Reescrever a doutrina hi-fi e/ou migrar os planos antigos para o nome novo.
- **C)** Incluir painel/CLI/testes (retrocompat `-ui-design.html`) neste mesmo item.
**Recomendação:** **A** — o rename da doutrina já está em `main` (OPS113); o trabalho restante é reescrever ponteiros de documentação, doc-only, sem código de app e sem schema.
**Rejeitadas:** **B** — reescrever a doutrina está fora do escopo (o OPS113 a elevou) e migrar `docs/plans/**` viola o acervo imutável. **C** — quebra a separação OPS114/OPS116 e os testes unitários pinados em `tests/unit/issuesPanel.unit.spec.ts`.
### Componentes / mudanças
**`.agents/skills/plan-issue/SKILL.md`** — 6 pontos + coerência de frontmatter:
| Linha | Antes (atual) | Depois |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 3 (`description`) | `...intention plans and UI drafts.` | `...intention plans and hi-fi UI designs.` (coerência; não é exigência da varredura) |
| 26 (regra dura 4) | `**Rascunho UI (obrigatório se muda UI):** HTML+Tailwind commitado no repo. Classe A/sem UI → sem rascunho.` | `**Design UI (obrigatório se muda UI):** o sub-agente `designer`produz`docs/plans/<slug>-ui-design.html`+`docs/plans/<slug>-ui-design-assets/\*.svg`(doutrina:`ui-design-html.md`). Classe A/sem UI → sem design.` |
| 42 (input do escritor) | `... + intention-template.md + shaping.md (+ ui-draft-html.md se UI)` | `... + intention-template.md + shaping.md` — o escritor não recebe mais doutrina de UI |
| 60 (checklist item 5) | `GATE: overview + rascunho UI (se muda UI) + decisão de dados` | `GATE: overview + design UI (se muda UI) + decisão de dados` |
| 100 (Passo 3c) | `- Se UI: ui-draft-html.md` | remover a linha (o escritor não gera UI); manter `- Se dados: data-presentation.md` |
| 112 (Passo 3d item 4) | `Se UI: cria docs/plans/<slug>-ui-draft.html (sub-agente ou inline)` | `Se UI: dispatcha o sub-agente designer (paralelo, 1 por ideia UI) para produzir docs/plans/<slug>-ui-design.html + docs/plans/<slug>-ui-design-assets/*.svg; o orquestrador grava os arquivos retornados no disco.` |
| 119 (Passo 4 GATE) | `Para cada item UI: aponte o link do .html fonte` | `Para cada item UI: aponte o link de docs/plans/<slug>-ui-design.html e confirme as cenas 390/1280 + estados críticos` |
**`.agents/skills/plan-issue/intention-template.md`**:
| Linha | Depois |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| 15 (campo) | `Design UI: <N/A — sem UI \| docs/plans/<slug>-ui-design.html>` |
| 32–33 (comentário do esboço) | citar `Design UI` e linkar `ui-design-html.md` (não `ui-draft-html.md`) |
| 39 (seção) | `### Design UI (B/C/D)` |
| 41–45 (comentário + bullet) | comentário aponta `docs/plans/<slug>-ui-design.html` (+ `-ui-design-assets/`); bullet `- Design UI (gate): docs/plans/<slug>-ui-design.html` |
| 98 (Referências) | `- Design UI (gate): <link do .html + assets em <slug>-ui-design-assets/ \| N/A>` — remove "PNGs embutidos acima" (órfão) |
| 106 (nota A) | `Classe A: Impeccable: A — N/A; Design UI: N/A; omita esboço de fluxo.` |
| 107 (nota B/C/D) | `Classe B/C/D: design hi-fi obrigatório no gate ([ui-design-html.md](ui-design-html.md)); commite o .html + os assets no repo.` |
**`.agents/skills/plan-issue/shaping.md:56`** (hoje link quebrado): `Se o item muda UI: design hi-fi no gate ([ui-design-html.md](ui-design-html.md)) antes de registrar — não conta como "engenharia no plano"; é validação visual da intenção.`
**`.agents/skills/plan-issue/skills-map.md:42`** (hoje link quebrado): `**Exceção de superfície:** o **design hi-fi do gate** — HTML+Tailwind commitado no repo ([ui-design-html.md](ui-design-html.md)) — é usado no plan-issue só quando o item muda UI. Não é implementação de /campanha nem substituto de Impeccable.`
**`.agents/skills/plan-issue/ui-design-html.md:93`** (finaliza a nota transitória): `Campo do cabeçalho do plano aponta o caminho do artefato (\`Design UI:\`) — ou \`N/A — sem UI\`.`
- **Migration:** sem migration (não toca schema/Payload).
- **Access / Consent:** N/A — nenhum caminho de escrita LGPD/access.
- **UI:** Impeccable **A — N/A** (muda doutrina de ferramenta de agentes, não UI de produto).
### Dados → forma (se aplicável)
N/A — mudança de doutrina de ferramenta de agentes; nenhuma superfície de dados.
## Decisões de engenharia
1. **Quem gera o artefato (Passo 3d).** Dispatch do sub-agente `designer` em paralelo por ideia UI; o **orquestrador grava** os arquivos retornados no disco (`docs/plans/<slug>-ui-design.html` + `-ui-design-assets/`). O `designer` já tem `permission.edit` restrita a `docs/plans/*-ui-design*`, então também pode gravar direto; o orquestrador é o escritor canônico para garantir o gate. **Rejeitada:** o escritor do plano gerar o HTML — é o comportamento velho que este item aposenta, e viola a permission do `designer`.
2. **Doutrina já renomeada no OPS113.** Não fazer `git mv`; só atualizar ponteiros + finalizar a nota transitória de `ui-design-html.md:93`. **Rejeitada:** reescrever a doutrina (fora do escopo; OPS113 elevou o conteúdo).
3. **PNG embutido.** Remover a exigência (`intention-template.md:98`); o renderizador `scripts/render-ui-draft.mjs` foi removido em 2026-08-21 — o fluxo é HTML-only e o humano abre o HTML. **Rejeitada:** reintroduzir PNG/rasterizador.
4. **Escopo do sweep.** Atualizar só `.agents/skills/plan-issue/**` + a nota em `ui-design-html.md`; painel/CLI/testes ficam para o OPS116. **Rejeitada:** tocar o painel agora — quebra a separação OPS114/OPS116 e os testes pinados. Consequência registrada: a varredura global **não** fica vazia; a prova é zero em `.agents/**`/`.opencode/**` e globalmente o set exato OPS116 (ver F3).
5. **Coerência de vocabulário.** Ajustar a `description` do frontmatter de `SKILL.md` ("UI drafts" → "hi-fi UI designs") para o inventário de skills não anunciar o artefato aposentado. **Rejeitada:** deixar como está — a varredura por `ui-draft`/`Rascunho UI` não pega "UI drafts", mas o descritor fica enganoso.
## Fases verificáveis
1. **F1 — `SKILL.md` (owner).** Aplicar os 6 pontos + `description`: regra dura 4 (l.26), input do escritor (l.42), checklist (l.60), Passo 3c (l.100, remove a linha de UI), Passo 3d (l.112, dispatch do `designer` + gravação), Passo 4/GATE (l.119, link `-ui-design.html` + cenas). Quota: metade do appetite.
2. **F2 — Template e vizinhos.** `intention-template.md` (campo/seção/paths/notas), `shaping.md:56`, `skills-map.md:42` e finalizar `ui-design-html.md:93`. Quota: a outra metade.
3. **F3 — Sweep + prova.**
- `grep -rnE "ui-draft|Rascunho UI|rascunho UI" .agents .opencode` → **vazio**.
- `grep -rnE "ui-draft|Rascunho UI|rascunho UI"` fora de `docs/plans/**`, `docs/changelog*/**`, `docs/CHANGELOG-AGENTS-HISTORY.md`, `node_modules`, `.git` → conjunto **exatamente** `scripts/lib/issues-panel.mjs`, `scripts/issues-tui.mjs`, `tests/unit/issuesPanel.unit.spec.ts` (OPS116); qualquer hit fora disso é falha.
- `git diff --name-only <base>...HEAD` → **nenhum arquivo antigo** de `docs/plans/`/`docs/changelog/`; as únicas adições são este `ops114-…-impl.md` e `docs/changelog/<data>-ops114.md`. Nenhum caminho `-ui-draft` no diff (planos antigos intactos).
- `.opencode/commands/plan-issue.md` **ausente** do diff.
- `pnpm format:check` verde (os markdown editados entram no check).
- Leitura do `SKILL.md` final: escritor sem doutrina de UI; 3d dispatcha `designer`; gate exibe `-ui-design.html` + cenas.
- Walkthrough estático de um item UI fictício pelo fluxo novo: explorador → escritor (plano sem UI) → 3d dispatcha `designer` → orquestrador grava os arquivos e preenche `Design UI:`/seção → gate abre o `.html` com as cenas.
- Push via `pnpm push`.
## Rabbit holes / Não escopo (engenharia)
- **Migrar/renomear planos antigos** (`-ui-draft.html`, PNGs) — acervo imutável vira PR gigante; retrocompat fica no OPS116.
- **Tocar `scripts/lib/issues-panel.mjs`, `scripts/issues-tui.mjs`, `tests/unit/issuesPanel.unit.spec.ts`** — OPS116 (retrocompat do painel).
- **Alterar a doutrina `ui-design-html.md` além da l.93** — conteúdo elevado no OPS113.
- **Mexer em `docs/design-refs/`** — questão aberta de produto; aqui não é ação.
- **Gates de implementação** (`work-issue`/`agent-work-issue`) — continuam lendo o plano como está.
- **UI de produto / `/impeccable`** — fora de escopo.
- **Reintroduzir PNG/rasterizador** — renderizador removido em 2026-08-21.
## Riscos e mitigação
- **Doutrina ainda no nome antigo (OPS113 incompleto).** Fail-closed: verificado que `ui-design-html.md` existe (OPS113 mergeado); a F3 começa confirmando o arquivo antes de linkar. Se não existisse, o item estaria bloqueado pelo `depends`, não se adivinha path.
- **Referência oculta ao low-fi.** Mitigação: varredura dupla por nome (`ui-draft`) e por vocabulário (`Rascunho UI`/`rascunho UI`), com globs explícitos de exclusão.
- **Sweep vazar para arquivos imutáveis.** Mitigação: checar `git diff --name-only` contra `docs/plans/` e `docs/changelog/`; nenhum plano antigo modificado e nenhum novo `-ui-draft`.
- **Critério de aceite "zero fora de docs/plans" conflitar com o resíduo OPS116.** Mitigação: a prova em F3 é dupla e honesta (zero em `.agents/**`/`.opencode/**` + set exato OPS116 global), registrada no PR; nada de declarar sweep vazio.
- **Prettier vermelho nos markdown editados.** Mitigação: `pnpm format` antes do commit; `format:check` na verificação.
- **`description` do frontmatter fora do sweep.** Mitigação: mudança de coerência coberta pela leitura final do `SKILL.md`, não só pela varredura literal.
## Aceite de engenharia
- [ ] Aceite de produto da intenção ainda coberto (B/C/D exige `-ui-design.html` + `-ui-design-assets/*.svg` do `designer`; escritor não gera UI).
- [ ] Frontmatter `Design UI:` e seção `### Design UI (B/C/D)` no template; PNG embutido deixa de ser exigência.
- [ ] Zero `ui-draft`/`Rascunho UI`/`rascunho UI` em `.agents/**` e `.opencode/**`; globalmente só o set OPS116 pinado.
- [ ] `shaping.md:56` e `skills-map.md:42` com link corrigido para `ui-design-html.md`; nota transitória de `ui-design-html.md:93` finalizada.
- [ ] Invariantes AGENTS/engineering-standards: doc-only, sem migration, sem editar `docs/plans/**`/`docs/changelog/**` existentes, sem tocar painel/CLI/tests.
- [ ] `.opencode/commands/plan-issue.md` inalterado (confirmado por `git diff --name-only`).
- [ ] `pnpm format:check` verde; push via `pnpm push`.
Self-score decision-quality: 5/5 — decisões caras com alternativas rejeitadas; cabe no appetite (~0,5 dia, doc-only); rabbit holes nomeados; reusa a doutrina `ui-design-html.md` e os shells existentes sem twinar; aceite de produto da intenção preservado.