ssheleg/super-ux

visão — o que o produto é, e o que ele se recusa a se tornar

Parte do super-ux — veja system-map.md para todo o pipeline. Depois de escrever o documento, execute python3 docs/ux/lint.py.

A camada acima do ux-foundation. A fundação responde quem usa o produto e por quê; a visão responde o que o produto é e o que ele se recusa a se tornar. Sem ela, "devemos construir isso?" não tem resposta que sobreviva à pessoa que teve a última opinião.

Não a confunda com scenarios.md, a outra camada cujo nome começa com "o que": cenários dizem o que o produto faz, passo a passo. Uma funcionalidade pode ser perfeitamente cenarizada e ainda assim violar a antvisão.

Esta skill produz duas coisas, e a segunda é o ponto principal.

1. docs/ux/vision.md — o documento.
2. Uma regra de alinhamento com a visão no próprio arquivo de instruções do projeto, para que todo recurso futuro seja verificado contra a visão, em vez de a visão ser escrita uma vez e nunca lida.

Uma visão que ninguém lê é um documento, não uma restrição.

Encaixa-se na cadeia: visão → fundação (personas, JTBD, jornadas, histórias) → fluxos → cenários → auditoria. Cada camada rastreia até a camada acima dela.

Passo 0 — leia o projeto, não o seu README

Antes de escrever uma palavra:

1. README.md, ARCHITECTURE.md, ROADMAP.md, CHANGELOG.md, tudo em docs/.
2. Código-fonte chave: pontos de entrada, serviços principais, o schema, a tabela de roteamento.
3. Superfícies de marketing se existirem — landing page, preços, funcionalidades.
4. package.json / pyproject.toml / Cargo.toml para saber do que ele realmente depende.
5. A UI funcionando. O que o produto faz, não o que ele diz que faz.
6. Se docs/ux/foundation.md existir, leia-o — a visão não deve contradizer as personas e jobs já acordados.

Uma visão escrita apenas a partir do README descreve o README. A lacuna entre o que um projeto diz que é e o que seu código realmente faz é geralmente onde a visão real está escondida, e nomear essa lacuna em voz alta é frequentemente a coisa mais valiosa que esta skill faz.

Passo 1 — a transformação

Responda internamente antes de escrever:

Usuário ANTES deste produto existir →  [caos / complexidade / dor]
Usuário DEPOIS deste produto existir →  [clareza / simplicidade / poder]

Tudo abaixo flui disto. Se você não conseguir afirmar isso, você ainda não conhece o produto bem o suficiente para escrever sua visão — volte ao passo 0.

Passo 2 — escreva docs/ux/vision.md em nove camadas

Toda camada é obrigatória. Escreva no idioma da documentação do projeto.

1. Essência. Uma frase. [Produto] é [tipo de sistema] que muda como [usuário] [faz X]. Sem nomes de funcionalidades, sem UI, sem tecnologia. O teste: se o produto fosse reconstruído do zero em uma pilha tecnológica diferente, essa frase ainda seria verdadeira? Se não, ela nomeia uma implementação, não uma essência.

2. Ideia central. Não é uma declaração de problema — é uma observação sobre o mundo.

[X] é abundante.
[Y] é escasso.
→ este produto preenche a lacuna.

Uma observação, não uma lista. "Informação é abundante, clareza é escassa."

3. O que o sistema faz. Comportamento contínuo, verbos, não substantivos: observa … entende … transforma … revela …. Sem nomes de funcionalidades. "Ter um dashboard" não é comportamento; "revelar contradições entre fontes" é.

4. O papel do usuário. O que o usuário se torna ao usar isso. Não é "o usuário clica" — o usuário direciona, julga, decide. Se o papel do usuário é indistinguível de operar qualquer outra ferramenta, a visão ainda não é específica.

5. Princípios. Três a cinco, cada um no formato fazemos X, não Y, onde Y é algo que uma equipe razoável realmente escolheria. Um princípio sem alternativa rejeitada é um slogan.

6. Antvisão. O que este produto se recusa a se tornar, explicitamente. Esta é a camada que as equipes pulam e a única que realmente resolve uma discussão. Nomeie os produtos adjacentes nos quais ele poderia se transformar e diga não a cada um.

7. Horizonte. Para onde isso vai em dois ou três anos, como uma direção, não um roadmap. Roadmaps pertencem ao rastreador de tarefas e ficam obsoletos em um trimestre.

8. A frase única. Se alguém se lembra de exatamente uma coisa, é esta.

9. O teste de alinhamento. Três a cinco perguntas que qualquer funcionalidade proposta deve passar. São essas que a regra no passo 4 realmente executará.

Passo 3 — valide antes de enviar

Verifique cada um e corrija em vez de racionalizar:

• A essência sobrevive a uma reescrita total em tecnologia diferente
• Nenhuma camada nomeia uma funcionalidade, uma tela ou um fornecedor
• A antvisão nomeia alternativas reais, não espantalhos
• Os princípios têm um lado rejeitado que alguém poderia genuinamente ter escolhido
• Nada contradiz docs/ux/foundation.md — e se algo contradiz, isso é uma descoberta a ser levantada, não para ser abafada silenciosamente
• Um estranho poderia usar o teste de alinhamento para rejeitar uma funcionalidade plausível

Passo 4 — instale a regra de alinhamento

Escreva a regra no arquivo de instruções do próprio projeto, o mesmo que ux-rule usa: CLAUDE.md para Claude Code, AGENTS.md para Codex e opencode, GEMINI.md para Gemini. Detecte qual o projeto já tem; crie CLAUDE.md apenas se nenhum existir. Nunca codifique o caminho de um único agente — uma regra instalada onde o agente em execução não pode vê-la é pior do que nenhuma regra, porque todos acreditam que ela está coberta.

Idempotente: se o título já estiver presente, atualize o bloco no lugar em vez de acrescentar uma segunda cópia.

## Alinhamento com a visão — regra rígida (super-ux)

Antes de planejar qualquer nova funcionalidade, capacidade ou mudança significativa, verifique-a
contra `docs/ux/vision.md` — especificamente a **antvisão** e o
**teste de alinhamento**.

**Alinhado** → prossiga e diga em uma linha a qual parte da visão ele serve.

**Desalinhado** → pare e diga isso antes de escrever código:
1. Nomeie o conflito — qual camada ele contradiz, citando essa camada.
2. Ofereça dois caminhos: (a) reformatar a funcionalidade para se encaixar, com a mudança
   específica; (b) alterar a visão, dizendo qual camada muda e qual é o custo.
3. Aguarde a decisão. Não escolha um silenciosamente.

**NÃO dispare para:** correções de bugs, refatorações, trabalho em dependências, testes,
documentação ou qualquer coisa sem superfície voltada para o usuário. Uma verificação de visão em uma
correção de digitação é como uma equipe aprende a pular a verificação que importa.

Passo 5 — aponte o README para ela

Uma linha abaixo da visão geral do projeto linkando para docs/ux/vision.md. Uma visão que ninguém consegue encontrar pela porta da frente é uma visão que ninguém lê.

Erros comuns

Erro	Por que quebra
Essência nomeia a tecnologia	deixa de ser verdadeira na primeira reescrita
Princípios sem lado rejeitado	"nós valorizamos qualidade" não resolve nenhuma discussão
Sem antvisão	a única camada que decide questões de escopo, faltando
Horizonte escrito como um roadmap	obsoleto em um trimestre, e então todo o documento parece desatualizado
Visão contradiz foundation.md	duas fontes de verdade, e as equipes seguem a que leram por último
A regra instalada no caminho codificado de um único agente	invisível para o agente realmente em execução; ninguém percebe, porque a ausência parece idêntica à conformidade
Escrito a partir do README	descreve o README