renatoasse/ibeia-skills/michelangelo

Michelangelo

Skill de design com quatro modos e uma regra fixa: nenhuma entrega termina sem passar pelo detector. Não é "acho que ficou melhor" — é P0/P1 = 0.

A skill opera em três escopos, e confundi-los é a falha mais cara que ela comete:

O detector mede defeito, não ambição. Um `PASS` é alcançável pelo design mais insosso possível. Por isso os dois redesigns usam comparação visual, mas com guardrails opostos: o redesign do artefato prova magnitude sem romper a lei, enquanto o redesign do DS usa orçamento de mudança e antes/depois para provar que a própria lei mudou. A primeira decisão da skill nunca é qual modo rodar, e sim qual escopo foi autorizado.

Abertura — três decisões antes de rotear

Pergunte as três juntas, numa única mensagem, em texto plano (nunca via UI de chips), antes de abrir qualquer arquivo do alvo:

1. Ambição: quer refino (mantenho a direção visual e conserto/elevo o craft) ou

redesign do artefato (reorganizo estrutura e hierarquia, mantendo a identidade)?

2. Lei visual: o design system atual deve ser preservado ou o pedido é para

redesenhar o próprio design system (paleta, tipografia e linguagem visual)?

3. Meio: o alvo é web, documento impresso/PDF ou slide? (muda quais

regras valem — ver reference/medium.md)

Não há default seguro na primeira. Errar a ambição custa a sessão inteira: um refino entregue a quem queria redesign lê como você não ter feito o trabalho — o resultado "está igualzinho" aos olhos de quem pediu, porque a direção visual, que é o que se vê primeiro, não mudou.

Na segunda há um default seguro e obrigatório: preservar o design system vigente. Palavras como "redesign", "refaça", "repense", "100x melhor" ou "irreconhecível" descrevem a magnitude do artefato, não autorizam trocar a identidade do produto. Só roteie para design-system new quando o pedido disser explicitamente que quer mudar o design system, a identidade visual, a paleta ou a tipografia da marca/produto.

Pule a pergunta só quando a resposta já está escrita no pedido, e registre em uma linha qual leitura você fez:

• Redesign do artefato, DS preservado — o pedido diz redesign/refaça/repense ou usa

intensificador de magnitude, mas aponta uma tela, componente, seção, documento ou slide específico e não pede para mudar a identidade do produto.

• Redesign do design system — o pedido nomeia explicitamente a lei a trocar: design

system, identidade visual, paleta de marca, tipografia institucional ou linguagem visual do produto inteiro.

• Refino — o pedido nomeia um defeito específico ("o espaçamento está apertado",

"corrige o contraste"), OU pede explicitamente para não mexer na direção.

A resposta de meio fixa o perfil de checks e de craft para o resto da sessão, e é gravada no briefing quando houver (reference/audit.md §Passo 5).

Antes de rotear, abra a lei. Leia PRODUCT.md (quem usa, para quê, e as anti-referências — o que este projeto explicitamente não pode parecer) e DESIGN.md (a lei visual) na raiz do repo, se existirem. Se nenhum dos dois existir e o alvo for web com framework, ofereça `design-system document` uma vez e siga com o que foi pedido: a falta deles nunca bloqueia o trabalho.

Antes de travar o alvo, confirme que ele é o alvo de verdade. Um arquivo pode ser uma casca fina que só embala outros arquivos — um viewer de galeria cujo corpo é <img src="...">/<iframe> apontando para os assets reais. Abra o arquivo e olhe o que ele de fato renderiza antes de assumir que o HTML apontado é onde o design mora. Sinal de casca: o arquivo é majoritariamente chrome (nav, grid, <section> genérica) em volta de referências a outros arquivos. Se for o caso, diga o que você encontrou e confirme com o usuário qual dos dois é o alvo — a casca ou o que ela embala — antes de gastar a sessão redesenhando a camada errada.

Roteador — qual modo usar

Quatro modos, cada um carrega sua própria prosa de reference/. Não carregue o que o modo não usa. Todo modo carrega `reference/medium.md` — é ele que diz quais regras do generate.md valem e quais checks do detector se aplicam ao alvo.

design-system — a lei visual: registrar, trocar ou evoluir

Uma porta, três caminhos. O `design-system` é o único escritor da lei — audit mede contra ela, polish e rebuild propõem, e a escrita em DESIGN.md acontece sempre aqui dentro. Sem argumento, o caminho sai de dois sinais que já existem:

• `document` — registro, não mudança: uma varredura escreve PRODUCT.md, DESIGN.md

e a rota da vitrine. Não muda um pixel do alvo. Carregar: reference/design-system/document.md + reference/register.md + reference/brand.md.

• `new` — troca a direção. Não termina no artefato: quem reconstrói é o rebuild,

e os dois formam uma cadeia única. Carregar: reference/design-system/new.md + reference/directions.md (critério das 3 direções) + reference/brand.md (a identidade e os assets que alimentam as direções) + reference/register.md (brand vs product, dials) + reference/gallery.md (empacotar as 3 para escolha) + reference/generate.md (o craft de cada direção) + reference/slop.md (o que nenhuma direção pode parecer) + reference/inspiration.md (se houver consentimento para minerar referências).

• `improve` — refina a lei sem trocar a direção. É também onde entram as propostas que

vieram do polish e do rebuild, e onde a lei morta (token que ninguém consome mais) vira proposta de remoção. Sem DS ainda → redireciona para document. Carregar: reference/design-system/improve.md + reference/gallery.md + reference/generate.md + reference/audit.md (a renderização como canvas) + reference/register.md.

Carregue só o arquivo do caminho escolhido — os três juntos custam o triplo e remisturam os dois regimes que a Abertura acabou de separar.

rebuild — reconstruir o artefato na direção escolhida

O elo entre a lei nova e o arquivo do usuário. Recebe a direção aprovada e reescreve o alvo real, com antes/depois pareado e um orçamento de mudança que prova que a mudança aconteceu. É o modo que fecha um redesign — sem ele, design-system new entrega um DESIGN.md e o artefato continua como estava.

Carregar: reference/rebuild.md + reference/generate.md + reference/brand.md + reference/medium.md + reference/patterns/ (o repertório de estruturas já resolvidas).

audit — diagnosticar sem alterar

Mede um alvo contra o design system e devolve um briefing pronto. Não toca em código.

Carregar: reference/audit.md (Camada 1 = detector determinístico; Camada 2 = crítica perceptual) + reference/slop.md (a taxonomia de "cara de IA" que a Camada 2 procura) + reference/patterns/ (o repertório — o que a Camada 2 pode PROPOR no lugar do que está lá).

polish — aplicar o briefing

Transforma um briefing (do audit, ou pedido direto) em código, reusando o que existe.

Carregar: reference/polish.md + reference/generate.md + reference/patterns/ (quando o briefing propõe um padrão nomeado) + reference/gallery.md (quando a mudança de arranjo é ampla demais para aplicar às cegas).

As três cadeias

• Refino: audit → polish. Não pule direto para polish sem medir o estado atual —

sem baseline não há como saber o que mudou. Este é o default depois de a Abertura resolver que o caso é refino, nunca o default do pedido genérico.

• Redesign do artefato com DS preservado: baseline real → galeria nível tela de

reference/gallery.md → polish. As três opções variam arranjo, hierarquia, densidade local e composição, mas reutilizam os mesmos tokens, tipografia, componentes, raios, elevação e motion do DESIGN.md. Rode o detector com --ds DESIGN.md em cada opção. Trate mudar paleta, família tipográfica ou linguagem de superfície como falha de escopo.

• Redesign do design system: design-system new → rebuild. A galeria escolhe a direção; o rebuild

a aplica no artefato. Parar depois da galeria é entregar uma promessa, não um resultado. `rebuild` nunca aplica no artefato final sem antes mostrar a proposta e esperar reação do usuário — 3 direções quando fizer sentido, ou 1 proposta concreta e visual quando a identidade de cor/tipografia for fixa (brand.md caso 2: o artefato retrata outra marca). Identidade fixa restringe QUAIS eixos podem variar — nunca é licença para pular o checkpoint inteiro e decidir sozinho. Ver rebuild.md §Passo 0.

Um redesign do design system pode terminar com um audit de conferência, mas nunca começa por ele: o briefing mediria contra a lei antiga que será descartada. Um redesign do artefato faz o oposto: começa pelo baseline real e mede todas as opções contra a lei vigente, porque reconhecibilidade é parte do critério de sucesso.

Rodar o detector

A skill é global; o cwd é o projeto do usuário. Sempre invoque por caminho absoluto, nunca relativo:

node ~/.claude/skills/michelangelo/scripts/detector/run.mjs <url|arquivo.html> \
  [--ds DESIGN.md] [--medium web|print|slide]

No Windows/Git Bash, ~ resolve; se falhar, use /c/Users/<user>/.claude/skills/michelangelo/scripts/detector/run.mjs.

• --medium desliga os checks que não fazem sentido no alvo (scrollbar, alvo de toque e

transição não existem em papel). Default web. Ver reference/medium.md.

• Gate: `BLOCKED` se `P0 + P1 > 0`; `PASS` caso contrário. P2/P3 não travam.
• Código de saída: 1 se BLOCKED, 0 se PASS — use no loop de correção em vez de

parsear texto.

Vale para todos os modos: cada direção candidata passa o gate antes de ir pra galeria, cada delta antes de entrar na mini-galeria, e nada é "aplicado" até o detector confirmar.

Setup (uma vez por máquina): a partir de ~/.claude/skills/michelangelo/, rode npm install && npx playwright install chromium. Já está instalado nesta máquina.

Pasta de saída — scratch datado por trabalho

Todo artefato que a skill escreve — prints, variantes da galeria, briefing.md — vai para uma pasta datada dentro do scratch do repo, nunca solto na raiz e nunca fora do repo:

1. Ache o scratch existente na raiz (_scratch/, scratch/, .scratch/, tmp/). Se não

houver, crie .scratch/ (e adicione ao .gitignore se o repo usa git).

1. Dentro dele, michelangelo/<slug>-<AAAA-MM-DD>/.

Chamo essa pasta de `<OUT>` no resto da doc. Um novo pedido abre uma nova pasta datada — o histórico anterior nunca é sobrescrito.

Higiene de runtime — nenhum build temporário fica no repo

<OUT> guarda a entrega e a evidência visual. Cache de framework, build isolado, saída de teste, log e servidor são runtime descartável, não artefato: nunca deixe na raiz pastas como .next/.next-*/.next-e2e*, test-results/, playwright-report/, output/playwright/ ou logs soltos criados pela sessão.

Gate obrigatório antes de abrir servidor