fsolla/teqo-backup
1
0
Fork 0
mirror of https://github.com/fsolla/teqo.git synced 2026-11-14 08:53:11 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
teqo-backup/docs/plans/ops114-plan-issue-design-hifi-no-gate-impl.md

16 KiB
Raw Permalink Blame History

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

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 designerproduzdocs/plans/-ui-design.html+docs/plans/-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.