🆚 skills/critique/ manual vs crítica embutida em discovery.ts
Duas modalidades, dois usos.
O que é
Há duas críticas no OD:
Step 8 do discovery.ts — agente roda em todo turn automaticamente; usuário não invoca
Skill critique — usuário invoca explicitamente; relatório mais profundo, com radar chart
Por que aprender
A embutida é o primeiro filtro — pega problemas óbvios, força re-roll antes de chegar ao usuário. Manual é o segundo filtro — mais profundo, opcional. Saber as duas = saber quando pular pra crítica manual ou ajustar a embutida.
Conceitos-chave
- Embutida: sempre roda, scoring rápido
- Manual: on-demand, scoring profundo
- Configurável: embutida pode ser desligada por skill
- Threshold customizável: default 7, pode subir para 8
📐 As 5 dimensões — definição operacional
Philosophy, Hierarchy, Execution, Specificity, Restraint.
O que é
Cinco dimensões com definição operacional precisa (não vague):
- Philosophy: coerência entre direção/marca e execução. "Editorial Monocle, mas accent neon? -2."
- Hierarchy: ordem de leitura. "H1 menor que H2 = -3."
- Execution: microcopy, micro-spacing, polish. "Lorem ipsum em produção = -2."
- Specificity: não-slop. "Métrica inventada visível = -3."
- Restraint: ausência de decoração desnecessária. "Gradiente de fundo + 5 ícones emoji = -2."
Por que aprender
Sem definição operacional, "Hierarchy ruim" é inútil. Com "H1 menor que H2 = -3", modelo sabe exatamente o que verificar e penalizar. Operacionalização > nomes bonitos.
Conceitos-chave
- Philosophy = coerência ↔ marca
- Hierarchy = ordem mecânica
- Execution = polish
- Specificity = anti-slop
- Restraint = subtração
📊 Score 0-10 vs 1-5 — quando usar qual
Resolução vs ruído.
O que é
Duas escalas:
- 0-10 (default): resolução fina, deltas pequenos visíveis. Usar quando a barra é alta (ex: cliente pago).
- 1-5 (coarse): resolução grossa, decisão binária ("ok" ou "não"). Usar quando o context é exploração rápida.
Por que aprender
0-10 dá poder mas vira ruído (a diferença entre 7 e 8 é confiável?). 1-5 perde nuance mas é robusto. Para decisão rápida (sprint, exploração), 1-5. Para fine-tuning (entrega cliente, refinamento), 0-10.
Conceitos-chave
- 0-10 default: quando há tempo para iteração
- 1-5 fast: quando o gate é binário
- Threshold 7/10 ≈ 4/5: equivalência prática
- Skill define: escala em
references/dimensions.md
🚧 O gate "anything < 3/5 é regressão"
A regra dura.
O que é
Em escala 1-5: qualquer dimensão < 3 é regressão — agente NÃO emite o artefato; força re-roll com instrução específica do que falhou. Em 0-10, equivalente a < 6. Não é warning; é hard gate.
Por que aprender
Sem hard gate, modelo emite "OK enough" mesmo com problemas óbvios — e cliente percebe. Hard gate força modelo a corrigir antes de você ver. Pipeline mais lento, output melhor.
Conceitos-chave
- < 3/5 = block: não chega ao usuário
- 3-4/5 = ship com warnings: entrega + relatório
- 5/5 raro: reservado para excelência
- Customizável: P0 da skill pode subir gate para 4
🔁 Loop de 2 passes como norma
Por que 2 e não mais nem menos.
O que é
Pipeline esperado: draft (pass 1) → critique embutida → quick-wins (pass 2) → emit. 2 passes é norma porque pass 1 captura macro estrutura; pass 2 refina detalhes. 3+ passes indica brief vago — sem âncora estável, modelo nunca converge.
Por que aprender
Saber que 3+ passes é sintoma evita armadilha comum: "só mais um ajuste". Pare, refaça brief. Convergência é exponencial: ou ela acontece em 2 passes ou nunca.
Conceitos-chave
- Pass 1: macro draft
- Pass 2: critique-driven quick-wins
- Pass 3+: red flag
- Token budget: 2 passes ≈ 30k tokens
🔧 Integração com POST /api/artifacts/lint
Findings reais alimentam a próxima rodada.
O que é
Após emit, daemon roda /api/artifacts/lint automaticamente. Findings (ex: "missing safe-area-inset", "<artifact> tag não fechada") são injetados no contexto do agente para a próxima ação. Crítica subjetiva + lint mecânico = feedback loop completo.
Por que aprender
Lint pega o que crítica não pega: erros estruturais determinísticos. Combinados, cobrem ~95% dos modos de falha. Lint sem crítica = bonito errado; crítica sem lint = subjetivo dócil.
Conceitos-chave
- Auto-run após emit: daemon dispara
- Findings injetadas: agente lê na próxima ação
- Severity: error / warning / info
- UI feedback: toast notif quando há findings
🎚️ Aumentar/reduzir a barra por skill
P0 hard gate por skill via references/checklist.md.
O que é
Em references/checklist.md da skill, você declara P0 específicos:
# P0 (hard gate — bloqueia emit) - text-size mínimo 72px em headlines de carrossel social - contraste WCAG AA (verificável em OKLch) - 1 cor de marca apenas, não 2 # P1 (warning — emite com toast) - pricing tier "popular" highlighted - mobile breakpoints sm/md/lg presentes
Por que aprender
Cada tipo de artefato tem regras diferentes. Carrossel exige texto grande; dashboard não. Skill custom = barra customizada. Saber editar P0 = adaptar OD para seu padrão de cliente.
Conceitos-chave
- P0 = bloqueio: agente não emite
- P1 = warning: emite + reporta
- P2 = nice-to-have: opcional
- 5-8 P0 por skill: sweet spot
- Mensurável: P0 deve ser verificável (grep ou regex)
🚫 Anti-AI-slop blacklist como Specificity check
A blacklist é a operacionalização de "Specificity".
O que é
A dimensão "Specificity" da crítica é avaliada cruzando o output com a blacklist anti-slop. Cada item da blacklist (gradient roxo, métricas inventadas, Inter como display, glass buttons) é uma penalidade -1 a -2 em Specificity.
Por que aprender
Specificity vira mecânico, não opinião. Modelo grep o output pelos itens da blacklist e penaliza. Subjetividade reduzida ao mínimo.
Conceitos-chave
- Blacklist = -2 to -1 cada: escala de penalidade
- Verificável: grep mecânico
- Customizável: skill estende blacklist
- Override: usuário pode permitir item se justificar
🛠️ Hands-on
Brief: Configurar uma skill custom com critique mais agressivo (P0 inclui "no rounded cards"). Rodar e ver o agente refazer.
- Copie skill base:
cp -r ~/.claude/skills/saas-landing ~/.claude/skills/landing-no-rounded - Edite checklist.md: adicione P0 "border-radius máximo 4px em cards e botões"
- Reinicie daemon:
pnpm tools-dev restart - Brief: "Faça uma landing pra um app de finanças. Use a skill landing-no-rounded."
- Observe: primeira tentativa do agente terá rounded grandes; critique vai bloquear; agente refaz com rounded ≤ 4px.
Snippet de checklist.md customizado
# P0 (hard gate) - border-radius máximo 4px (NUNCA 8, 12 ou 16) - box-shadow ZERO em cards - 1 cor de marca apenas - mobile breakpoint sm: presente - contraste WCAG AA verificado em OKLch
📚 Fontes
No repositório
packages/contracts/src/prompts/discovery.ts(RULE 3, Step 8)skills/critique/SKILL.mdskills/critique/references/dimensions.md
Externas
- Code review patterns — gate pre-merge analogia
- WCAG 2.2 — contraste verificável
📌 Resumo do Módulo
1. Crítica embutida (auto, em todo turn) ≠ skill critique manual (on-demand).
2. 5 dimensões com definição operacional precisa: Philosophy, Hierarchy, Execution, Specificity, Restraint.
3. 0-10 para fine-tuning; 1-5 para decisão rápida.
4. < 3/5 é regressão = hard gate; agente não emite, refaz.
5. 2 passes é norma; 3+ = brief errado.
6. Lint mecânico complementa crítica — findings injetadas no próximo turn.
7. Skill com checklist.md custom muda barra (P0 endurecidos por contexto).
8. Anti-slop blacklist é operacionalização de "Specificity" — verificável.
Próximo módulo:
Módulo 3.5 · Criando uma Skill Própria →