wizz-method 2.8.1 → 2.10.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wizz-method",
-  "version": "2.8.1",
+  "version": "2.10.0",
   "description": "Wizz Method: método de agência orientado por IA em PT-BR",
   "keywords": [
     "agile",

package/skills-registry.yaml

@@ -86,10 +86,21 @@ areas:
       - id: wizz-decision-maker
         entry: true
         door: direcao
-        when: "PORTA de direção: todo trabalho de decidir ANTES de construir. Brief visual inicial (6 decisões de estética + 3 lógicas) no kickoff. Puxa: wizz-taste-skill (direção anti-slop de brief novo) e wizz-motion-3d-director (decidir caminho motion/3D/vídeo)."
+        when: "PORTA de direção: todo trabalho de decidir ANTES de construir. Brief visual inicial (6 decisões de estética + 3 lógicas) no kickoff. Puxa: wizz-design-needs (o que precisa ser pesquisado), wizz-taste-skill (direção anti-slop de brief novo) e wizz-motion-3d-director (decidir caminho motion/3D/vídeo)."
         rel:
-          before: [wizz-ui-ux-pro-max]
+          before: [wizz-design-needs, wizz-ui-ux-pro-max]
           pairs_with: [wizz-motion-3d-director, wizz-taste-skill]
+      # Arquitetura (NÃO no `when:`, que é critério de seleção e fica guloso com
+      # explicação dentro): esta entrada só PRODUZ o mapa. Quem executa o mapa
+      # são os dois mineradores, que a puxam pela aresta `before` abaixo — é
+      # assim que o protocolo rel garante que ninguém minere sem mapa.
+      - id: wizz-design-needs
+        door: direcao
+        when: "Decidir O QUE precisa ser pesquisado num projeto de site/UI: transformar o brief na lista de referências, efeitos, componentes e comportamentos a minerar."
+        not_when: "Executar a pesquisa (é wizz-premium-landing-ui-researcher ou wizz-ui-component-curator), escolher componente ou escrever UI."
+        rel:
+          after: [wizz-decision-maker]
+          before: [wizz-premium-landing-ui-researcher, wizz-ui-component-curator]
       - id: wizz-taste-skill
         door: direcao
         when: "Anti-slop em briefs NOVOS: lê o brief, define a direção e audita contra defaults de AI. Também cobre projeto EXISTENTE: audita o código atual, lista problemas, prioriza fixes (protocolo de redesign)."
@@ -111,15 +122,21 @@ areas:
           after: [wizz-decision-maker]
           before: [wizz-impeccable]
           pairs_with: [wizz-huashu-design, wizz-premium-landing-ui-researcher, wizz-ui-component-curator]
+      # Executa o mapa do wizz-design-needs, uma necessidade por passada (a
+      # aresta `after` abaixo é o que o protocolo rel lê; nota de arquitetura
+      # dentro do `when:` deixa a entrada gulosa e mexe no roteamento).
       - id: wizz-premium-landing-ui-researcher
         door: construcao
         when: "Projeto NOVO (greenfield): cria landing premium do zero, hero, 3D high-end. Estratégia source-first."
         rel:
+          after: [wizz-design-needs]
           pairs_with: [wizz-ui-ux-pro-max]
+      # Idem: a relação com o mapa vive na aresta `after`, não no `when:`.
       - id: wizz-ui-component-curator
         door: construcao
         when: "Projeto EXISTENTE: qual componente/efeito adicionar que combina com o estilo atual."
         rel:
+          after: [wizz-design-needs]
           pairs_with: [wizz-ui-ux-pro-max]
       - id: wizz-impeccable
         door: construcao
@@ -533,11 +550,21 @@ areas:
 
   social:
     agent: wizz-social
-    summary: "Social e roteiros virais: Reels/Shorts, hooks, calendário de conteúdo. Persona Rafa, aplica o Blueprint de Roteiro Viral e roteia para as CLIs de vídeo quando o roteiro vira vídeo."
+    # O `summary:` é critério de SELEÇÃO de área, igual ao `when:` de uma
+    # entrada — não é narrativa de arquitetura. Até 2026-09-21 ele dizia "roteia
+    # para as CLIs de vídeo quando o roteiro vira vídeo", prometendo um handoff
+    # que a área não pode fazer: as CLIs de vídeo (get-brolls, hyperframes,
+    # buttercut, claude-video) moram em `designer`, e o único cli daqui é o
+    # postiz. Medido: essa frase puxava pedido de ASSET ("imagens de apoio pro
+    # meu Reel", "carrossel pro Instagram") para social, que não tem a
+    # ferramenta. A fronteira ficou no summary; a nota ficou aqui.
+    summary: "Social e roteiros virais: o TEXTO e o ROTEIRO de Reels/Shorts, hooks, legenda, thread, calendário de conteúdo. Persona Rafa, aplica o Blueprint de Roteiro Viral. Captar, desenhar ou montar o asset em si (b-roll, vídeo, carrossel, imagem) não é desta área."
     skills:
       - id: wizz-social-content
         when: "Criar/agendar conteúdo de social (LinkedIn, X, TikTok, IG...), o que inclui ESCREVER o texto: post, story, carrossel, legenda, thread. Gatilhos: 'escreve copy pra story', 'post pro LinkedIn', 'legenda do carrossel', 'thread pro X'."
-        not_when: "Editar/revisar texto de social já escrito: aí é wizz-copy-editing."
+        not_when:
+          - "Editar/revisar texto de social já escrito: aí é wizz-copy-editing."
+          - "Pedir SÓ o asset de um Reel/vídeo — b-roll, 'imagens de apoio', 'cenas de apoio', imagem de corte, footage — sem que o texto ou o roteiro façam parte do pedido: a captação é get-brolls, na área designer. Esta entrada entra quando o TEXTO ou o ROTEIRO é parte do que se pede; se o pedido junta roteiro E captação, são 2 áreas."
         rel:
           before: [get-brolls, postiz]
           pairs_with: [wizz-canvas-design, wizz-content-strategy, wizz-copy-editing, wizz-launch-strategy]

package/src/modules/wizz/agents/wizz-designer/SKILL.md

@@ -28,13 +28,13 @@ You are Wizz's Designer. It creates high-level interfaces and landing pages, sho
 > **Single source (registry) — ALWAYS read before the examples below:** the real list for your area (`designer`) lives in `skills-registry.yaml`. Resolve the **light slice for your area** first, `{project-root}/_wizz/_config/registry/designer.yaml` (already comes as the full `areas.designer` block — skills/mcps/clis/references); if it's missing (old install), fall back to the monolith in order `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml` and find the `areas.designer` block there. If you need something cross-cutting (utility/mcp_utility/cli_utility/squads), also read `{project-root}/_wizz/_config/registry/_shared.yaml`. Route by the `when:` field — `skills:` (invoke via `Skill`), `clis:` (run the `check:`; if missing, show the `install:`, opt-in; respect `platform:` — e.g. `buttercut` is `darwin-arm64` only) and `mcps:` (propose `claude mcp add <id>` with the `server` block). **Follow `rel:` before answering.** An entry's `rel` (`pairs_with`, `before`, `after`, `instead_of`) is how the method knows that a request about A also needs C. Every edge is reciprocal by construction — the schema validator rejects one-way edges — so the relation shows up whichever side the user enters from. Do it in this order, before answering: (1) pick the entries whose `when:` matches the request; (2) LIST every id named in the `rel` of those entries — including the ids you do not recognise, which are exactly the point; (3) for each id outside YOUR slice, resolve id → area through the `ids:` map (id → area) in `{project-root}/_wizz/_config/registry/index.yaml` and read that area's slice to get its `when:` (a target marked `_shared` lives in `_shared.yaml`); (4) either bring it in or discard it with a stated reason. A related capability you never named is one the method lost: silence is the failure, not the discard. When the target is in ANOTHER area and shapes the SAME deliverable (the thing you are about to hand over is incomplete without it), say so and offer `wizz-maestro`, who coordinates areas — you never invoke the other area's agent yourself, and you never hand the request back to whoever delegated it to you (anti-loop). Tell the user what the related capability is instead of delivering only the half they asked for, and when the relation is `before`, say what has to come first. **Entry points (skills):** offer only the 3 skills with `entry: true` (direction → wizz-decision-maker, building → wizz-ui-ux-pro-max, motion/assets → wizz-animate); the rest carry a `door:` field and only come in pulled by their layer's door or by an explicit user request — never offer the full list. The examples below are just a readable shortcut; the registry is the source of truth and picks up whatever gets added later (e.g. video tools: hyperframes, get-brolls, claude-video, buttercut, voicebox, ctc-align). **Video:** before choosing a tool, apply `_shared/video-pipeline.md` — HyperFrames draws the screens (silent visual, one scene per composition), Remotion assembles the film (audio, SFX, captions, frame timing via ctc-align); never position audio/captions in HyperFrames. **B-roll:** when the script names something real (a fact, a person, a product, a news item, a screen), the insert is sourced with `get-brolls`, not drawn — it searches the literal source, builds a Storyboard, and stops at a human approval gate you never sign for the user. Stock only enters if the user asks for stock.
 
 For every task, **go through the right door via the `Skill` tool** and bring the result in plain language:
-- Decide BEFORE building (brief, visual direction, motion/3D path) → `wizz-decision-maker` (pulls in wizz-taste-skill, wizz-motion-3d-director)
+- Decide BEFORE building (brief, visual direction, motion/3D path) → `wizz-decision-maker` (pulls in wizz-design-needs, wizz-taste-skill, wizz-motion-3d-director)
 - Create/improve UI (landing, design system, component, polish) → `wizz-ui-ux-pro-max` (pulls in wizz-premium-landing-ui-researcher, wizz-ui-component-curator, wizz-impeccable, wizz-taste-skill, wizz-huashu-design, wizz-react-components)
 - Run animation and generate media → `wizz-animate` (pulls in wizz-design-motion-principles, wizz-remotion-best-practices, wizz-canvas-design, wizz-algorithmic-art)
 
 Always **show the visual/plan before the code**. Code building is `wizz-agent-dev`'s job; for a one-off tweak, point to `wizz-quick-dev`.
 
-**Research gate:** for a non-trivial component/effect, the build door must cover the record of searches, demos and exact code/registry, review date/license, dependencies, visual evaluation, and reason for the choice. The output of `wizz-ui-ux-pro-max` is a local guideline lookup, not web component mining. Before the handoff to dev, confirm the evidence or state the limitations and the justification for a custom implementation. Optional sources being unavailable doesn't block research in other public sources.
+**Research gate:** for a non-trivial component/effect, research runs against the project's research map (`design-state.yaml`, produced by `wizz-design-needs`): one need per pass, with the need's own source budget, floor and `proibidos` block. Without a map, non-trivial work goes through `wizz-design-needs` first — otherwise the user ends up naming every effect by hand, one request at a time. The build door must cover the record of searches, demos and exact code/registry, review date/license, dependencies, visual evaluation, and reason for the choice. The output of `wizz-ui-ux-pro-max` is a local guideline lookup, not web component mining. Before the handoff to dev, confirm the evidence or state the limitations and the justification for a custom implementation. Optional sources being unavailable doesn't block research in other public sources.
 
 ## Closing
 Close in the Wizz format: `✅ O que fiz` (simple sentences) / `➡️ Próximo passo` (usually wizz-agent-dev or wizz-quick-dev to build) / `🎯 Comando`.

package/src/skills-lib/wizz-design-needs/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: wizz-design-needs
+description: Turns a website brief into the project's research map — the explicit list of what has to be mined before any UI is built, with a budget and a stop condition for each item. Reads the brief, decomposes the project into surfaces, sections, components and behaviours, derives the research needs, subtracts the ones the brief forbids, checks what the project already has, and writes everything to design-state.yaml. Use when a site, landing page, portfolio or app UI is about to be researched, designed or rebuilt and nobody has written the list of what to look for; use before wizz-premium-landing-ui-researcher or wizz-ui-component-curator, which mine one need at a time against this map. Does not mine, does not choose components and does not write UI code.
+---
+
+# Design Needs — the project's research map
+
+The miner is good at searching and cannot know what to search for. That is this skill's only job: read the brief and produce the list, so the human stops being the system's to-do list.
+
+Output: a `needs` block in `design-state.yaml`. Nothing else. This skill never opens a source, never recommends a component and never writes UI.
+
+## Hard rules (always, before reading any reference)
+
+1. **Every need carries a `why` that traces back to the brief.** If you cannot point at the phrase, the requirement or the page type that produced it, the need does not exist. A need without a `why` is noise, and noise is what makes a system research forever.
+2. **Signals subtract as well as add.** A brief that says "minimalista" does not merely fail to ask for particles: it *forbids* opening that search. Removal always beats addition, and the conflict is recorded, not silently resolved.
+3. **The level caps the behaviour layer.** The site level (1-5, from `wizz-premium-landing-ui-researcher/references/site-levels.md`) sets the motion budget, and that budget is the stop condition for behaviour research. Ambition above the level is not a need, it is scope creep.
+4. **Gap analysis runs before any query is written.** A need already satisfied by the project, the local cache or an earlier selection is closed with a reason, not researched again.
+5. **Never mine here.** Producing the map and executing it are different jobs on purpose: one bad map costs the whole project, one bad search costs one search.
+6. **Declare hypotheses, do not ask for them.** Missing objective, audience or stage become stated hypotheses in the state file. Only the questions in `references/derivacao.md` ("What stays with the human") are worth stopping for, and there are at most three.
+
+## Flow
+
+1. **Read the brief.** Whatever exists: the `wizz-decision-maker` output, a PRD, a paragraph in chat, an existing site. Extract objective, audience, page type, signals, constraints and stack. Missing fields become hypotheses.
+2. **Set the level** (1-5) and read its motion budget. A signal that pulls up and a signal that pulls down is a conflict: record it, and the restrictive one wins.
+3. **Decompose.** Surfaces → sections → components → behaviours. Procedure in [decomposicao](references/decomposicao.md).
+4. **Derive the needs** with the four rules and the signal table in [derivacao](references/derivacao.md). This is where needs are both created and forbidden.
+5. **Run the gap analysis** ([gap-analysis](references/gap-analysis.md)): project inventory → local cache → needs already satisfied on another surface. What survives gets a query, a source budget and a floor. What does not survive is closed with `status: dropped` and a reason.
+6. **Write `design-state.yaml`** in the shape of [design-state](references/design-state.md), and hand off.
+
+## Output format
+
+Report in `{communication_language}`, short, in this order:
+
+- the level and the motion budget, with the one-line reason
+- the count: needs open, dropped, deferred
+- the needs, grouped by layer (system, section, behaviour), one line each
+- **what the brief forbade**, with the signal that forbade it. This block is not optional: it is the proof that the map is dirigido and not a shopping list
+- the open questions for the human, at most three, only the ones from `references/derivacao.md`
+- the handoff line: which miner runs next and against which needs
+
+## Handoff
+
+The map is executed by the miner, one need per pass:
+
+- greenfield surface or whole-page direction → `wizz-premium-landing-ui-researcher`
+- one isolated need inside an existing project → `wizz-ui-component-curator`
+
+Both read `design-state.yaml`, take the need's `budget` and `floor` as given, and write their findings back as `discoveries`. Never hand a miner a request in prose when a need id exists: the id carries the budget and the stop condition, the prose does not.
+
+Level 4 or 5 also hands off to `wizz-motion-3d-director` before any behaviour need is mined.
+
+## References map (read on demand)
+
+| For... | Read |
+|---|---|
+| Surfaces, sections, components, behaviours: how to break the project down | [decomposicao](references/decomposicao.md) |
+| The four derivation rules, the signal table that adds and subtracts, and the three questions that stay with the human | [derivacao](references/derivacao.md) |
+| The three lookups that close a need before it costs a search | [gap-analysis](references/gap-analysis.md) |
+| The `design-state.yaml` schema, who writes each block and the read contract | [design-state](references/design-state.md) |
+
+Final rule: a map that lists everything is the same as no map. The value of this skill is in what it refuses to research.

package/src/skills-lib/wizz-design-needs/references/decomposicao.md

@@ -0,0 +1,54 @@
+# Decomposition
+
+Four layers, top down. Each layer answers a different question, and only two of them generate research.
+
+| Layer | Question | Generates research? |
+|---|---|---|
+| Surface | which pages/routes exist | no, it sets the scope |
+| Section | what each surface is made of | yes, when the project has no compatible component |
+| Component | which pieces a section needs | yes, same condition |
+| Behaviour | what moves, reacts and transitions | yes, capped by the level |
+
+## 1. Surfaces
+
+A surface is a route with its own job. Derive from the page type, not from imagination.
+
+| Page type | Usual surfaces |
+|---|---|
+| Landing / offer | one surface. Extra pages (thanks, terms) are not surfaces |
+| Authority / portfolio | home, project list, individual project, about, contact |
+| SaaS marketing | home, product, pricing, one proof page, docs entry |
+| App / dashboard | shell, main list, detail, empty/first run, settings |
+
+When the project has more than three surfaces or the hierarchy is genuinely in question, that is `wizz-site-architecture`'s job (area `seo`). Name it to the user and take its sitemap as the surface layer if they run it; do not re-derive what that skill owns. It is deliberately NOT a registry `rel` edge: a cross-area edge would inject a seo entry into every designer discovery prompt, and the surface layer needs it in maybe one project out of ten.
+
+## 2. Sections
+
+The required structure per page type already exists in `wizz-premium-landing-ui-researcher/references/landing-page-strategy.md` and, for the other two modes, in `dashboard-and-portfolio-modes.md`. Read the one that matches and take its section list. This skill does not invent a competing structure.
+
+Rule: a section becomes a research need **only if the gap analysis finds no compatible component in the project**. A contact section in a project that already has a form is not a need, it is an assembly.
+
+## 3. Components
+
+Break each section into its pieces only where the piece carries the brief. A card grid in a portfolio carries the brief; a footer does not.
+
+Test to apply: *if this piece were generic, would anyone notice?* If the answer is no, it is not a need. Generic is the correct answer for most footers, most legal pages and most form fields.
+
+## 4. Behaviours
+
+Everything that is not a static state. Six families, and they are the whole list:
+
+| Family | Covers |
+|---|---|
+| Entry | how something appears the first time (reveal, stagger, mask) |
+| Scroll | what the page does as it scrolls (parallax, sticky, progress, pinning) |
+| Pointer | hover, tilt, magnetism, cursor |
+| Transition | route to route, list to detail, state to state |
+| Feedback | loading, empty, error, success, disabled |
+| Adaptive | what changes on mobile, on keyboard, under `prefers-reduced-motion` |
+
+The Adaptive family is never a separate need: it is a required field on every other behaviour need. A behaviour whose mobile and reduced-motion answer is unknown is not researched, it is incomplete.
+
+## Output of this step
+
+An ordered list with `surface → section → component/behaviour`, no queries yet, no sources yet. Queries are written only after the gap analysis, because half of this list usually dies there.

package/src/skills-lib/wizz-design-needs/references/derivacao.md

@@ -0,0 +1,62 @@
+# Derivation rules
+
+Four rules turn the decomposition into needs. Rules 1 to 3 create; rule 4 both creates and forbids.
+
+## Rule 1 — System layer: five needs, always
+
+Typography, grid, colour, spacing and image treatment. They do not depend on the brief, they are not negotiable and they decide more of "does this look expensive" than any effect does.
+
+Budget is small for each (one or two sources), because the answer usually comes from the local base in `wizz-ui-ux-pro-max` plus one real reference. Image treatment is the exception: give it three sources when the project is image-led (portfolio, architecture, photography, product).
+
+## Rule 2 — Section layer: comes from the page type, not from the brief
+
+Take the section list from the page-type structure (see `decomposicao.md`, step 2). Each section becomes a candidate need. The gap analysis decides which ones survive.
+
+A section need is written as a question about *composition*, never about a component name: "how does a selected-projects grid breathe" is a need, "find a card component" is a shopping item.
+
+## Rule 3 — Behaviour layer: the level sets the ceiling
+
+The site level (1-5) carries a motion budget in `wizz-premium-landing-ui-researcher/references/site-levels.md`. Convert the budget into a number of behaviour needs, not into a number of animations: one researched pattern repeats across the page.
+
+| Level | Motion budget (existing) | Behaviour needs |
+|---|---|---|
+| 1 Basic | 5-8 light animations | 1 |
+| 2 Intermediate | 10-15 animations | 2 |
+| 3 Advanced | 15-25 coordinated | 4 |
+| 4 High-End 3D | 20-35 + hero scene | 6, and `wizz-motion-3d-director` runs first |
+| 5 Signature | 1 wow + 2-3 secondary | 8, same handoff |
+
+When more behaviours compete than the ceiling allows, rank by how much each one carries the brief and mark the losers `deferred`, with the reason. A deferred need is cheap to reopen later and expensive to have researched now.
+
+## Rule 4 — Brief signals add and subtract
+
+This is the rule that stops the system from researching everything.
+
+| Signal in the brief | Adds | Forbids |
+|---|---|---|
+| editorial | typographic rhythm, image treatment, deliberate grid break | symmetric 3-column grid, decorative icon set |
+| minimalista | hover states, intentional emptiness | particles, glow, saturated gradient, 3D/WebGL |
+| sofisticado / premium | route transition, focus states, micro-hover | badges, emoji, default shadow scale |
+| portfólio / arquitetura / estúdio | project grid, cursor, scroll reveal | logo carousel, generic testimonial card |
+| SaaS / produto | empty state, loading, data density | cinematic hero |
+| e-commerce | image zoom, variant state, cart feedback | long-form scroll narrative |
+| institucional / corporativo | clear hierarchy, dependable patterns | experimental layout, heavy motion |
+| performance crítica / mobile-first | LCP, font strategy, bundle weight | WebGL, background video, heavy shader |
+| lúdico / consumer | expressive states, colour accents | austere editorial restraint |
+
+Reading rules:
+
+1. **Forbidden beats added.** When one signal adds what another forbids, the search does not open. Record it under `conflitos` with both signals named.
+2. **A forbidden item is never researched, not even "to compare".** Comparison is the most common way a forbidden capability gets back in.
+3. **A signal that is not in the table is still a signal.** Write the add/forbid pair yourself, name it in `derived_from`, and keep it in the state file so the next session inherits it.
+4. **A reference the user supplied outranks a signal.** If they sent a site that uses exactly what a signal forbids, the reference wins and the conflict is recorded: they chose it on purpose.
+
+## What stays with the human
+
+At most three questions, and only these kinds. Each one changes the work and none can be inferred:
+
+1. **Which outcome the surface is for**, when two plausible outcomes need different heroes and different CTAs (capture a lead vs impress a peer, sell vs educate).
+2. **Whether the required raw material exists** (professional photography, real product screenshots, real numbers). Its absence changes the nature of needs, not their priority.
+3. **Whether the identity is already locked** (typeface, palette, logotype). If locked, system needs close without research.
+
+Everything else is a hypothesis, declared in the state file and carried forward. Asking a fourth question is a failure of this skill, not diligence.

package/src/skills-lib/wizz-design-needs/references/design-state.md

@@ -0,0 +1,108 @@
+# design-state.yaml
+
+One file per project, the shared memory of the design chain. It exists so a decision taken during research survives until implementation and QA, instead of evaporating in a prose handoff.
+
+## Location and read contract
+
+Path: `{output_folder}/design-state.yaml`, next to `project-context.md` (default `_wizz-output/`, configurable via `output_folder` in `_wizz/bmm/config.yaml`).
+
+Read contract, deliberately identical to the one the router and the maestro already use for `project-context.md`:
+
+- **Fail-open.** No file, no complaint: proceed and say the map does not exist yet.
+- **Cheap read first.** `grep -m1 '^nivel:'` and `grep -c 'status: open'` answer most questions without loading the file.
+- **Full read only to write.** Whoever is going to change a block loads the file; whoever only needs context greps it.
+
+## Who writes what
+
+| Block | Written by | Read by |
+|---|---|---|
+| `brief`, `identidade`, `stack` | `wizz-decision-maker`, `wizz-design-needs` | everyone |
+| `nivel`, `orcamento_motion`, `conflitos` | `wizz-design-needs` | miner, implementer |
+| `superficies`, `inventario`, `needs` | `wizz-design-needs` | miner |
+| `discoveries` | the miner | implementer, QA |
+| `implementacao` | `wizz-agent-dev` / `wizz-quick-dev` | QA |
+| `problemas` | QA, the audit protocol, the user | `wizz-design-needs` when reopening a need |
+
+No block has two owners. A skill that needs a field it does not own asks the owner or records a `problema`; it never overwrites.
+
+## Schema
+
+```yaml
+version: 1
+atualizado_em: 2026-09-21
+
+brief:
+  objetivo: "captar contato de cliente de alto padrão"   # hipotese: true quando inferido
+  publico: "..."
+  tipo_pagina: autoridade
+  sinais: [editorial, minimalista, sofisticado]
+  hipoteses: ["objetivo inferido do tipo de página, não informado pelo usuário"]
+
+nivel: 3
+orcamento_motion: "15-25 animações coordenadas"
+conflitos:
+  - { entre: [premium, minimalista], resolvido_para: minimalista, motivo: "restritivo vence" }
+
+identidade: { tipografia: null, paleta: null, travada: false }
+stack: { framework: next, styling: tailwind, motion: null, orcamento_bundle_kb: 180 }
+
+superficies:
+  - { id: home, rota: "/", tipo: landing, secoes: [hero, manifesto, projetos, processo, prova, contato] }
+
+inventario:
+  componentes: []
+  tokens: null
+  motion_utils: []
+  lido_em: 2026-09-21
+
+needs:
+  - id: b1-hero-entrada
+    surface: home
+    section: hero
+    layer: comportamento          # sistema | secao | componente | comportamento
+    question: "como o hero entra e como reage ao primeiro scroll"
+    why: "brief pede sensação editorial; o hero é o teste dos 3 segundos"
+    derived_from: [sinal:editorial, tipo:autoridade, nivel:3]
+    query: "editorial hero scroll reveal mask typography react"
+    budget: { fontes: 3 }
+    floor: 7
+    signature: true               # no máximo 1 por superfície
+    adaptive: { mobile: null, reduced_motion: null }   # obrigatório antes de fechar
+    status: open                  # open | mining | evaluated | selected | unmet | dropped | deferred
+    reason: null                  # obrigatório em dropped, deferred, unmet
+    satisfied_by: []
+
+proibidos:
+  - { o_que: "partícula, glow, gradiente saturado, 3D", por: sinal:minimalista }
+  - { o_que: "carrossel de logos, card de depoimento genérico", por: tipo:autoridade }
+
+discoveries: []      # escrito pelo minerador
+implementacao: {}    # escrito pelo dev
+problemas: []        # escrito pelo QA
+```
+
+## The `proibidos` block
+
+It is not documentation. It is an active constraint: before opening any query, the miner checks it, and a query that would land on a forbidden capability is not run. Without this block the rest of the map is a shopping list with extra steps.
+
+It also survives sessions. A month later, "add something impressive to the hero" is still answered against the same brief.
+
+## Status lifecycle
+
+```text
+open ──▶ mining ──▶ evaluated ──▶ selected ──▶ (implementado)
+  │                     │
+  │                     └──▶ unmet      (budget esgotado, nada acima do piso)
+  ├──▶ dropped   (gap analysis, ou duplicata)
+  └──▶ deferred  (perdeu para o teto do nível)
+```
+
+`unmet`, `dropped` and `deferred` require a `reason`. That is what makes reopening cheap: the next round knows what was already tried and why it failed, and does not re-search the same ground.
+
+## Reopening
+
+QA, the audit protocol or the user record a `problema`. `wizz-design-needs` converts it into a need:
+
+- objective defect (contrast, focus, overflow, reduced-motion, LCP) → not a need. It is a fix, handled by the implementer.
+- missing piece → reopen the need with `status: open` and a `budget` reduced by what was already spent, and with the previously rejected discoveries carried forward so they are not proposed again.
+- wrong direction → this is not a need either. It goes back to the brief, and it is the human's call.

package/src/skills-lib/wizz-design-needs/references/gap-analysis.md

@@ -0,0 +1,46 @@
+# Gap analysis
+
+Three lookups, in this order, before a single query is written. The first one that satisfies a need closes it.
+
+## 1. Project inventory
+
+Inspect what the project already has: dependencies, tokens, theme, shared primitives, existing animation utilities, components already built. This is phase 1 of the source-first protocol; the difference here is that **the result is written down**, in `design-state.inventario`, so it is paid for once per project instead of once per search.
+
+Look at: `package.json`, the token/theme file, the shared component folder, any motion utility, and the two or three pages that already exist.
+
+A need is closed by the inventory when the existing piece is compatible *as is or with token-level adaptation*. "We have a card, it just needs a full redesign" does not close the need.
+
+**A capability is often satisfied at a different layer than the one that uses it.** Check the global layer before declaring a component gap, or the inventory invents needs that do not exist. Measured on a real project (MeJu, 2026-09-21): nine of twelve landing-page effect components had no `useReducedMotion` call, and every one of them was already covered, either by a global `@media (prefers-reduced-motion: reduce)` block in the stylesheet or by Tailwind's `motion-safe:` variant. Reading only the component files would have produced nine false needs.
+
+So, for any cross-cutting concern (reduced motion, dark mode, focus rings, i18n, spacing scale, container widths), look in this order: global stylesheet → framework variant/utility → provider or layout → the component itself. Only the absence at **every** layer is a gap.
+
+When the layers disagree or the coverage cannot be proven by reading (a CSS rule that may or may not reach a JS-driven animation, for instance), that is **not** a research need. Record it under `problemas`, split into what you observed and what you inferred, and route it to the polish/QA skills. Research finds what the project lacks; it does not diagnose what the project already has.
+
+## 2. Local cache and user material
+
+- `~/.claude/design-sources/` (React Bits, Cult UI, Ali Imam, StyleUI, Watermelon)
+- `modelos lp/` or whatever local reference folder the project uses
+- anything the user pasted, linked or screenshotted in this conversation
+
+Cache freshness rule: check the revision and date before treating a cached item as current. A stale cache is still a valid source for a pattern; it is not a valid source for an API. When the cache answers a need, record the revision in the discovery, not just the path.
+
+User-supplied material outranks every catalogue. A reference the user chose is worth more than a better reference they did not.
+
+## 3. Needs already satisfied on another surface
+
+Within one project, a pattern is researched once. A hover resolved on the home page is not re-researched for the project list. The second occurrence is closed with `status: dropped`, `reason: "resolvido por <need-id>"`, and it inherits that need's discovery.
+
+This is the deduplication that makes multi-surface projects affordable, and it only works because the state file persists between sessions.
+
+## Output
+
+For each need in the decomposition, one of:
+
+| Outcome | Status | What is recorded |
+|---|---|---|
+| satisfied by the project | `dropped` | which file or component satisfies it |
+| satisfied by cache or user material | `selected` | the source, revision and why it fits |
+| satisfied by another need | `dropped` | the need id it inherits from |
+| not satisfied | `open` | the query, the source budget and the floor |
+
+Report the count of each. A project where the gap analysis closes nothing is a project where the inventory was not actually read.

package/src/skills-lib/wizz-premium-landing-ui-researcher/SKILL.md

@@ -7,6 +7,15 @@ description: Research animations, components, visual references, and conversion
 
 Autonomous strategist for premium landing pages, SaaS UI, and advanced visual experiences (React, Next.js, Tailwind, shadcn/ui, Framer Motion, Three.js, R3F). This file is the index: only the always-active rules live here. The detail for each step lives in `references/` and should be read only when that step is executed.
 
+## Gate 0: the research map (always, before Gate 1)
+
+Check for `{output_folder}/design-state.yaml` (default `_wizz-output/`). Cheap check first: `grep -c 'status: open'`.
+
+- **It exists, with open needs:** you are not deciding what to research. Work **one need per pass**, in the order given, and take `query`, `budget.fontes` and `floor` as given. Read the `proibidos` block before writing any query: a query that lands on a forbidden capability is not run, not even for comparison. Write each finding back under `discoveries` with the `need` id, and move the need to `selected` or `unmet` with a reason. Stop when the needs are exhausted, not when the ideas are.
+- **It exists, no open needs:** the map is done. Do not open new research on your own: report it and hand back to `wizz-design-needs` if something is genuinely missing.
+- **It does not exist, and the work is non-trivial:** invoke `skill:wizz-design-needs` first. Mining without a map is how a project ends up depending on the user to name every effect, one request at a time.
+- **It does not exist, and the work is one isolated component the user named:** proceed, and say the map was not created.
+
 ## Gate 1: Source-First (always, before any UI code)
 
 This skill exists because writing shaders, animations, hovers, and components from scratch is NOT the way. The way is to curate mature components, animations, and shaders from professional sources (the user's `modelos lp/`, React Bits, Cult UI, Ali Imam, Watermelon, StyleUI, Skiper UI, Componentry, and public registries) and adapt them to the brand.

package/src/skills-lib/wizz-premium-landing-ui-researcher/references/source-first-protocol.md

@@ -24,7 +24,9 @@ Choose sources based on the effect needed, using [component-sources](component-s
 | Carousel | Embla, shadcn/ui |
 | Visual direction and reference motion | Sites provided by the user, Landing Love, Godly, Design Spells, Refero Styles |
 
-For each non-trivial component:
+The set of "non-trivial components" is not improvised here: it is the list of open needs in `design-state.yaml` (produced by `wizz-design-needs`). With no state file, derive it from the approved section structure and say you did, so the gap is visible.
+
+For each open need:
 
 1. Formulate a concrete search with function, style, and stack; check at least two suitable sources when available.
 2. Open the exact item: demo, documentation, and the code file or registry JSON. A search result alone doesn't prove compatibility.

package/src/skills-lib/wizz-router/SKILL.md

@@ -40,6 +40,12 @@ Assess the **Area**: how many areas does the request touch? The canonical area l
 
 **Dispatch rule:** IF 2+ areas → `wizz-maestro`, always. OTHERWISE count the 3 remaining factors (multi-step, needs planning, produces a memorable artifact); 2+ factors → `wizz-maestro`. The area clause decides on its own, without combining with anything else.
 
+**One gate runs before dispatch, and it is deliberately narrow: the ambiguous referent.** Ask the user instead of dispatching ONLY when all three hold: (a) the request names a target that does not resolve to ONE thing — the context shows several objects that fit the name, or there is no antecedent at all; (b) a single short factual question settles which one; (c) guessing wrong lands the work on the wrong object at a cost worth a question. When it fires, ask via `AskUserQuestion` and dispatch only after the answer. "Update the price on the page" with three live sales pages is the case; "improve this" with nothing to point at is the case; "remove the banner" where a promo banner and a cookie banner both exist is the case.
+
+**Clause (c) is eliminatory, and it is the clause that settles most cases — check it last and let it close the gate.** The bar is that a wrong guess costs more than redoing the delivery: a change lands on the wrong live object, or work already done has to be thrown away. A short piece of text that is cheap to rewrite never clears that bar, however unresolved its referent looks: "write a headline to sell this plan" has no antecedent at all for "this plan", clause (a) holds, and it still goes to `agent:copy` — a headline aimed at the wrong plan is rewritten in a minute. **Clause (a) alone never fires the gate.** (Calibrated on `a04`, measured 2026-09-21: the gate fired there and should not have.)
+
+This gate does NOT fire for an open-scope request. "My site is bad, sort it out", "my sales page converts badly": the target resolves fine, it is the SCOPE that is undefined, and discovering scope is the Manager's work — that is the counterpart clause below, and it stays the maestro's. It does NOT fire for an area that is defensible either way: pick the area, do not ask. And it never outranks the sensitive-subsystem clause below — an ambiguous request that touches authentication, payments, permissions or production data goes to `wizz-maestro`, who asks as part of planning what must not break. One rule per case: the Director asks only about WHICH object, never about what the work should be. **When in doubt, the gate does NOT fire.** (Owner's decision, 2026-09-21.)
+
 **Decision order — capabilities → required relations → areas → shortcuts.** Match the catalogue entries, inspect their `rel`, and include only capabilities needed for the requested deliverable and not already supplied in the context. Resolve their owning areas before applying ANY one-area shortcut. One artifact can require multiple areas; the word "copy" does not prove that only copy is needed. For full sales-page copy, if either the offer or the conversion structure is missing from the supplied context, include the missing capability: `wizz-offer-forge` for the offer and/or `wizz-page-cro` for conversion structure (growth), alongside `wizz-copywriting` (copy); route to maestro. Do not assume those inputs are ready merely because the user did not mention them. If both are already approved and the request is limited to text, keep copy-only work in copy. An isolated headline or CTA does not require redesigning the whole page. Optional neighbours and separate deliverables do not add areas; `pairs_with` alone never escalates.
 
 **What you count are the areas of the catalogue ENTRIES the request matches — never the topics named in the sentence.** A request can name four subjects and still match one entry, and then it is one area. "Full audit of the site: performance, SEO, security, accessibility" names four topics and matches `wizz-launch-readiness` (qa), whose `when:` already spans build, security, SEO, analytics, content, legal and infra: those four legs are that single audit's own scope, not four deliverables, so the answer is `agent:qa`. Counting nouns instead of entries is the most common way to over-escalate. (Owner's decision, 2026-09-19.)

package/src/skills-lib/wizz-router/references/routing-table-flat.md

@@ -42,6 +42,7 @@ Use this table to map skills/CLIs/MCPs directly **outside a Wizz project** (no `
 |---|---|---|
 | Visual brief at kickoff, "what should this look like", deciding direction BEFORE building | `wizz-decision-maker` (designer's direction door: 6 aesthetic decisions + 3 logical ones) + `wizz-taste-skill` | 1 |
 | Design, UI, visual, component, style, palette, typography, design system | `wizz-ui-ux-pro-max` + `wizz-ui-component-curator` | 1 |
+| "What do I need to research for this site", turning a brief into the list of references/effects/components to mine, before any research | `wizz-design-needs` (research map in design-state.yaml; the miners then run one need per pass) | 1 |
 | Turn a design into React/Vite components (Stitch MCP output) | `wizz-react-components` | 2 |
 | Review/audit NATIVE UI (iOS/macOS: SwiftUI, Flutter, React Native, Tauri, Electron) against the Apple HIG and Liquid Glass | CLI `apple-design` (designer registry) — covers what `wizz-taste-skill` declares out of scope; for web UI it's `wizz-ui-ux-pro-max` instead | 2 |
 | Landing page, hero, motion, 3D animation, conversion, visual CRO | `wizz-premium-landing-ui-researcher` | 1 |

package/src/skills-lib/wizz-ui-component-curator/SKILL.md

@@ -15,6 +15,12 @@ Act as a UI curator with taste and restraint — not a gallery explorer. Optimiz
 
 # Step-by-step flow
 
+## 0. Check the research map
+
+If `{output_folder}/design-state.yaml` exists, the need being worked is already written there: take its `query`, `budget.fontes` and `floor` instead of improvising them, honour the `proibidos` block, and write the result back under `discoveries` with the `need` id. If the request does not match any open need, say so before researching: an unplanned need is either a gap in the map (go back to `wizz-design-needs`) or scope creep.
+
+With no state file, continue normally.
+
 ## 1. Read and infer the style DNA
 
 Inspect the relevant UI files before searching anything. Look at: main shell, hero/homepage, shared primitives, buttons, cards, nav, animation utilities, theme/token files.