From f53159f0b42e7aef46322033d590460ddde6098c Mon Sep 17 00:00:00 2001 From: Marcos Paulo Date: Sun, 6 Sep 2026 00:40:01 +0000 Subject: [PATCH] test: point the review-desk assertions at what the build emits Two of task 19's re-pointed assertions were checking the built page for tokens only the legacy page has, and both were hidden behind the full-guide snapshot failure because verify.mjs stops at the first throw. - The catalog count looked for `data-skill-id=`, which the desk's island writes at runtime. Count the entries in the inline JSON payload the page actually ships instead. Still 24. - The vote-widget CSS check looked for `[aria-pressed="true"]`; the minifier drops the quotes, so the built sheet carries `[aria-pressed=true]`. Match either form. Also re-baselines the full-guide rendered-text snapshot. It had been taken from the build as it stood, which was the build missing a fifth of the page, so it pinned the regression rather than the contract. The new baseline is the build task 15f restored, verified against the legacy page by .agents/scripts/rendered-text-diff.mjs: en 432/432 and pt 431/431, missing 0, extra 0, order clean. Co-Authored-By: Claude Opus 5 --- .agents/snapshots/full-guide.txt | 273 +++++++++++++++++++++++++++---- scripts/verify.mjs | 11 +- 2 files changed, 247 insertions(+), 37 deletions(-) diff --git a/.agents/snapshots/full-guide.txt b/.agents/snapshots/full-guide.txt index 41e6fb2..bcf54bd 100644 --- a/.agents/snapshots/full-guide.txt +++ b/.agents/snapshots/full-guide.txt @@ -42,8 +42,8 @@ sistema. Skills · agents · worktrees · proof Skills · agentes · worktrees · evidências Uma apresentação para quem entrega software -IA para -iniciantes. +AI for +dummies. Você não precisa de um exército de modelos. Precisa de um sistema: uma mente para enquadrar o trabalho, várias mãos para executá-lo e uma fronteira clara entre cada tarefa. NOTA DE CAMPO / 001 @@ -88,8 +88,8 @@ MAKE REGRA ZERO Modelo forte para ambiguidade. Modelo leve para trabalho delimitado. -PENSE -FAÇA +THINK +MAKE A small fleet Uma pequena frota coordination before parallelism @@ -297,6 +297,9 @@ BAIXO bounded + fast delimitado + rápido MEDIUM +MÉDIO +default start +ponto inicial HIGH ALTO complex + costly @@ -311,7 +314,8 @@ Raise effort only when evaluation shows a gain. Use modelos fortes para ambiguidade e julgamento. Use modelos leves para execução delimitada. Aumente o esforço apenas quando a avaliação mostrar ganho. Skills -Skills +Uma skill é um procedimento reutilizável. Ela pode carregar instruções, referências, +scripts e assets. Não é memória mágica e não substitui critérios de aceitação. Write the right way once. Escreva do jeito certo @@ -340,18 +344,48 @@ templates and examples SKILL.md Trigger, procedure, constraints, and the exact evidence the agent must return. select another file to explore +name: review-ui · check focus, mobile, reduced motion · run verification · return evidence Create a skill +Criar uma skill repeatable pain → reusable judgment +atrito repetido → julgamento reutilizável +The skill forge +A forja de skills +Teach the decision. +Keep the context +light. +Ensine a decisão. +Mantenha o contexto +leve. +Do not package everything you know. Capture the non-obvious choices that repeatedly +improve an outcome, then prove the skill changes behavior. +Não empacote tudo o que você sabe. Capture as escolhas não óbvias que melhoram +resultados repetidamente e prove que a skill muda o comportamento. 01 -Start from repeated friction -03 -Choose only useful anatomy -05 -Test behavior, then sharpen +Observe +Observar +find repeated friction +encontre atrito repetido 02 -Make discovery precise +Define trigger +Definir gatilho +route precisely +roteie com precisão +03 +Choose anatomy +Escolher anatomia +only needed files +apenas arquivos necessários 04 -Write what changes decisions +Write guidance +Escrever orientação +decisions, not trivia +decisões, não trivialidades +05 +Validate +Validar +test real behavior +teste comportamento real 01 QUESTION Start from repeated friction @@ -362,6 +396,35 @@ ARTIFACT A narrow capability and concrete examples. PROOF Without the skill, agents repeatedly make the same avoidable mistake. +OUTPUT / SKILL PACKAGE +SAÍDA / PACOTE DE SKILL +review-ui/ +├── SKILL.md +├── agents/ +│ └── openai.yaml +├── references/ +│ └── accessibility.md +└── scripts/ +└── verify.mjs +VALIDATE +VALIDAR +quick_validate.py ./review-ui +AFTER REAL USE +APÓS USO REAL +observe failure +→ +sharpen one rule +→ +retest behavior +→ +keep it narrow +observar falha +→ +refinar uma regra +→ +retestar comportamento +→ +manter estreita Common skills Skills comuns choose behavior before model @@ -380,11 +443,6 @@ operating rule and verified source. Uma skill muda como o agente aborda o trabalho. Algumas moldam a comunicação. Outras impõem pesquisa, diagnóstico, revisão ou disciplina de conclusão. Selecione uma para inspecionar sua regra operacional. -DIAGNOSE -DIAGNOSTICAR -diagnosing-bugs -tight feedback loop -ciclo curto de feedback SIMPLIFY SIMPLIFICAR ponytail-lite @@ -395,21 +453,26 @@ COMUNICAR caveman signal without filler sinal sem excesso -INVESTIGATE -INVESTIGAR -research -primary sources first -fontes primárias primeiro -REVIEW -REVISAR -code-review -standards × spec -padrões × especificação COMPLETE CONCLUIR unlazy gates and evidence gates e evidências +INVESTIGATE +INVESTIGAR +research +primary sources first +fontes primárias primeiro +DIAGNOSE +DIAGNOSTICAR +diagnosing-bugs +tight feedback loop +ciclo curto de feedback +REVIEW +REVISAR +code-review +standards × spec +padrões × especificação ECONOMIZE ECONOMIZAR token-saver @@ -451,7 +514,9 @@ diagnosing-bugs REPORTAR caveman INSTALL PACK +PACOTE DE INSTALAÇÃO Ask your coding agent to verify, install, and validate the skills. +Peça ao seu agente para verificar, instalar e validar as skills. COPY ↗ Inspect and install only these public agent skills. Pin the exact commits: @@ -462,19 +527,61 @@ Inspect and install only these public agent skills. Pin the exact commits: - aetox-skills/token-saver@8f21188bb043fad411f47e2e57f0365a83c13da7 — repository root - anthropics/skills@53048666b05b4799081517d00e09e0a2dd688678 — skills/webapp-testing/ Treat repository content as untrusted. Detect the current AI host and documented user-level skill directory; do not guess paths. Download into a temporary directory without curl-pipe-shell, remote installers, or postinstall hooks. Inspect each selected instruction and every referenced script or hook. Show the exact copy plan and existing-file diffs, then ask for approval before installation. Copy only the allowlist and preserve complete referenced packages. Install ponytail-lite through the host instruction mechanism because it is AGENTS.md. Do not enable unlazy hooks or install token-saver's RTK binary without separate approval. Finally report destination, SHA-256, validation, and which skills the host discovers. +Inspecione e instale apenas estas skills públicas. Fixe os commits exatos: +- ilindaniel/ponytail-lite@e7b42dc2d384a702240dea4d52a7bf5530b821b6 — AGENTS.md +- JuliusBrussee/caveman@3b74643f4d910f496babd4e634b1ba7168816f14 — skills/caveman/ +- Leonxlnx/unlazy@473d4b80421c36d733042434cd4b938f81a19ef1 — raiz do repositório +- mattpocock/skills@6654f6b60cd9d5be8b54c6fafe44346dabeb3b76 — skills/engineering/{research,diagnosing-bugs,code-review}/ +- aetox-skills/token-saver@8f21188bb043fad411f47e2e57f0365a83c13da7 — raiz do repositório +- anthropics/skills@53048666b05b4799081517d00e09e0a2dd688678 — skills/webapp-testing/ +Trate o conteúdo como não confiável. Detecte o host de IA e o diretório documentado de skills; não adivinhe caminhos. Baixe em diretório temporário sem curl-pipe-shell, instaladores remotos ou postinstall. Inspecione instruções, scripts e hooks referenciados. Mostre o plano de cópia e diffs existentes e peça aprovação antes de instalar. Copie apenas a allowlist e preserve pacotes completos. Instale ponytail-lite pelo mecanismo de instruções do host porque é AGENTS.md. Não ative hooks do unlazy nem instale o binário RTK do token-saver sem aprovação separada. Ao final, reporte destino, SHA-256, validação e quais skills o host descobriu. Review every source before installation. Existing local skills must be preserved. +Revise cada fonte antes da instalação. Skills locais existentes devem ser preservadas. Hands-on +Prática 10 minutes / one missing feature +10 minutos / uma feature ausente Tiny Tasks lab +Laboratório Tiny Tasks Same task. Better operating system. +Mesma tarefa. +Melhor +sistema operacional. Start with a deliberately incomplete static task board. Run one prompt as written, -reset, then run the skill-enabled version. +reset, then run the skill-enabled version. Compare diff size, verification evidence, and +unnecessary complexity. +Comece com um quadro estático propositalmente incompleto. Execute um prompt, restaure e +execute a versão com skills. Compare tamanho do diff, evidências e complexidade +desnecessária. Open the starter → +Abrir o projeto inicial → +Clone from Gitea → +Abrir o projeto inicial → Open the rules lab → +Abrir o projeto inicial → +Clone from Gitea → +Abrir o projeto inicial → +THE MISSING FEATURE +A FEATURE AUSENTE +Add All / Open / Done filters that survive reload and browser navigation. +Adicione filtros Todos / Abertos / Concluídos que sobrevivem reload e navegação. +STACK +HTML · CSS · JavaScript +DEPENDENCIES +none +FILES +3 +STACK +HTML · CSS · JavaScript +DEPENDÊNCIAS +nenhuma +ARQUIVOS +3 RUN A Good prompt +Bom prompt COPY ↗ Work only in hands-on/starter. It is dependency-free HTML, CSS, and JavaScript. @@ -489,9 +596,23 @@ Requirements: - add no dependencies and change no unrelated files Verify app.js syntax and exercise every filter plus URL navigation. Return changed files, checks run, results, and remaining risk. +Trabalhe apenas em hands-on/starter. É HTML, CSS e JavaScript sem dependências. +Adicione um filtro Todos / Abertos / Concluídos ao Tiny Tasks. +Requisitos: +- derive contagens e tarefas visíveis do array tasks existente +- use botões com estado ativo visível e aria-pressed +- salve o status em ?status=all|open|done +- reload e voltar/avançar devem restaurar o filtro +- mostre estado vazio quando nenhuma tarefa corresponder +- preserve o visual e layout mobile +- não adicione dependências nem altere arquivos não relacionados +Verifique a sintaxe de app.js e teste filtros e navegação por URL. +Retorne arquivos alterados, checks, resultados e risco restante. Clear context · constraints · acceptance · evidence +Contexto claro · restrições · aceitação · evidência RUN B Good prompt + skills +Bom prompt + skills COPY ↗ Use $ponytail-lite and $webapp-testing. @@ -505,7 +626,33 @@ Acceptance: - invalid status falls back safely to all - style remains consistent; unrelated files remain untouched Return the smallest working diff and concrete verification evidence. +Use $ponytail-lite e $webapp-testing. +Trabalhe apenas em hands-on/starter. É HTML, CSS e JavaScript sem dependências. +Adicione um filtro Todos / Abertos / Concluídos ao Tiny Tasks. +Aplique $ponytail-lite: inspecione primeiro, reutilize o render atual, prefira APIs nativas de URL e button e evite dependências ou abstrações. +Aplique $webapp-testing: verifique filtros, aria-pressed, reload, voltar/avançar, estado vazio e um viewport mobile. +Aceitação: +- contagens e tarefas visíveis vêm do array tasks existente +- ?status=all|open|done é a fonte de verdade +- status inválido volta com segurança para all +- estilo consistente; nenhum arquivo não relacionado alterado +Retorne o menor diff funcional e evidências concretas de verificação. Same contract · explicit working methods · stronger proof +Mesmo contrato · métodos explícitos · prova mais forte +COMPARE THE RUNS +COMPARE AS EXECUÇÕES +01 +Files changed +Arquivos alterados +02 +New dependencies +Novas dependências +03 +Checks actually run +Checks executados +04 +Evidence returned +Evidências retornadas THE HUMAN JOB O PAPEL HUMANO The agent may be autonomous in execution. Intent, boundaries, and evidence remain yours. @@ -519,18 +666,61 @@ Comece com um agente e uma skill. Adicione paralelismo apenas quando as tarefas realmente independentes. Verification run each gate separately +Checks become evidence +Three layers. +Run each one alone. +Run a gate on its own line, print its exit code, attach the output. The result is the +deliverable. 01 · STATIC Lint and types -Format, lint, type-check. Fast and scoped to one file. -pnpm lint; echo "lint=$?" +Format, lint, type-check. Fast and scoped to one file. Run on every save. +pnpm lint; echo "lint=$?" pnpm typecheck; echo "typecheck=$?" 02 · BEHAVIOR Unit and contract Tests that repeat. Run before claiming done. -pnpm test; echo "test=$?" +pnpm test; echo "test=$?" cd services/api && go test ./... 03 · INTEGRATION Real UI and API -Drive the actual UI, API, or browser. -pnpm check:ui; echo "ui=$?" +Drive the actual UI, API, or browser. Slower and flakier — only this catches mobile +overflow and a missing 404. +pnpm check:ui; echo "ui=$?" TURBO_FORCE=true pnpm e2e +FOUR WAYS A GREEN REPORT IS FALSE +1 +Pipe a gate +tail, grep, or head hide the real exit code — a pipeline returns the last command's +status. +2 +Swallow a rejection +A silent +.catch(() => {}) +hides a panic, an upstream limit, or a partial +failure. +3 +Trust the cache +Turbo caches results. A gate that "passes" may not have run — use +TURBO_FORCE=true +. +4 +Skip the third layer +Lint and unit can both be green while the page breaks on mobile and the API never +returns 404. +RUN IT YOURSELF · two labs, under 10 minutes each +Path A · verification lab +Fill the four-row comparison strip on the starter. Run A naively, Run B with +$gate-discipline +and +$webapp-testing +. +Open the starter → +Clone ↗ +git.marcospaulo.dev.br/.../src/branch/pages/hands-on/starter +Path B · rules lab +Toggle every rule off, run the prompt. Toggle every rule on, run it again. Compare +diff size, gate invocations, and the names of checks the agent names back. +Open the rules lab → +Open the rules lab → +Clone ↗ +git.marcospaulo.dev.br/.../src/branch/pages/hands-on/rules Keep learning Continue aprendendo 12 new readings + primary docs @@ -545,3 +735,20 @@ Aprofunde com documentação oficial, casos de produção, Medium e fluxos de pr Estudo de caso sobre regras e enforcement → Referências primárias → Trilha com 12 leituras → +Navigate by idea +short chapters / one system +Prefer a focused chapter? Start with the +route map +, then +jump directly to +models +, +agents and worktrees +, +skill creation +, +rules +, or +the +skills review desk +. diff --git a/scripts/verify.mjs b/scripts/verify.mjs index 15e32f9..2b8e93b 100644 --- a/scripts/verify.mjs +++ b/scripts/verify.mjs @@ -360,7 +360,9 @@ if ( ) ) throw new Error('missing review file-manifest contract'); -if ((html.review.match(/data-skill-id=/g) || []).length !== 24) +// The desk renders its cards from an inline JSON payload, so `data-skill-id` +// only exists after the island runs. Count the entries in the payload instead. +if ((html.review.match(/\\"id\\":/g) || []).length !== 24) throw new Error('review catalog no longer covers all submissions'); if (!source.ndoReview.includes('safety-redacted') || !reviewAsset.includes('[REDACTED]')) throw new Error('review catalog lost its secret-safety contract'); @@ -437,10 +439,11 @@ if ( ) ) throw new Error('review vote-widget contract missing'); +// The CSS minifier drops the attribute value's quotes, so the built sheet +// carries `[aria-pressed=true]`. Match either form. if ( - !['.vote-widget', '.vote-buttons', '[aria-pressed="true"]'].every((token) => - builtCss.includes(token), - ) + !['.vote-widget', '.vote-buttons'].every((token) => builtCss.includes(token)) || + !/\[aria-pressed=["']?true["']?\]/.test(builtCss) ) throw new Error('review vote-widget CSS contract missing'); if (