ssheleg/super-ux

visión — qué es el producto, y qué se niega a convertirse

Parte de super-ux — consulta system-map.md para conocer toda la cadena. Después de escribir el documento, ejecuta python3 docs/ux/lint.py.

La capa superior de ux-foundation. Foundation responde quién usa el producto y por qué; visión responde qué es el producto y qué se niega a convertirse. Sin ella, "¿deberíamos construir esto?" no tiene una respuesta que sobreviva a la persona que tuvo la última opinión.

No lo confundas con scenarios.md, la otra capa cuyo nombre comienza con "qué": los escenarios dicen lo que el producto hace, paso a paso. Una funcionalidad puede estar perfectamente escenificada y aún así violar la anti-visión.

Esta habilidad produce dos cosas, y la segunda es el punto.

1. docs/ux/vision.md — el documento.
2. Una regla de alineación con la visión en el archivo de instrucciones propio del proyecto, para que cada funcionalidad futura se verifique contra la visión en lugar de que la visión se escriba una vez y nunca se lea.

Una visión que nadie lee es un documento, no una restricción.

Encaja en la cadena: visión → foundation (personas, JTBD, journeys, stories) → flujos → escenarios → auditoría. Cada capa se remonta a la capa superior.

Paso 0 — lee el proyecto, no su README

Antes de escribir una palabra:

1. README.md, ARCHITECTURE.md, ROADMAP.md, CHANGELOG.md, todo lo que hay en docs/.
2. Código fuente clave: puntos de entrada, servicios principales, el esquema, la tabla de enrutamiento.
3. Superficies de marketing si existen — landing, precios, características.
4. package.json / pyproject.toml / Cargo.toml para saber de qué depende realmente.
5. La IU en vivo. Lo que el producto hace, no lo que dice que hace.
6. Si existe docs/ux/foundation.md, léelo — la visión no debe contradecir las personas y trabajos ya acordados.

Una visión escrita solo desde el README describe el README. La brecha entre lo que un proyecto dice ser y lo que su código hace es, por lo general, donde se esconde la visión real, y nombrar esa brecha en voz alta suele ser lo más valioso que hace esta habilidad.

Paso 1 — la transformación

Responde internamente antes de escribir:

Usuario ANTES de que exista este producto →  [caos / complejidad / dolor]
Usuario DESPUÉS de que exista este producto →  [claridad / simplicidad / poder]

Todo lo demás fluye de esto. Si no puedes expresarlo, aún no conoces el producto lo suficiente como para escribir su visión — vuelve al paso 0.

Paso 2 — escribe docs/ux/vision.md en nueve capas

Toda capa es obligatoria. Escribe en el idioma de documentación del proyecto.

1. Esencia. Una oración. [Producto] es [tipo de sistema] que cambia cómo [usuario] [hace X]. Sin nombres de funcionalidades, sin IU, sin tecnología. La prueba: si el producto se reconstruyera desde cero en una pila diferente, ¿esta oración seguiría siendo cierta? Si no, nombra una implementación, no una esencia.

2. Idea central. No es una declaración del problema — es una observación sobre el mundo.

[X] es abundante.
[Y] es escaso.
→ el producto tiende un puente.

Una observación, no una lista. "La información es abundante, la claridad es escasa."

3. Lo que hace el sistema. Comportamiento continuo, verbos no sustantivos: observa… entiende… transforma… presenta…. Sin nombres de funcionalidades. "Tiene un panel" no es comportamiento; "presenta contradicciones entre fuentes" sí lo es.

4. El rol del usuario. En qué se convierte el usuario al usarlo. No "el usuario hace clic" — el usuario dirige, juzga, decide. Si el rol del usuario es indistinguible de operar cualquier otra herramienta, la visión aún no es específica.

5. Principios. De tres a cinco, cada uno en la forma hacemos X, no Y, donde Y es algo que un equipo razonable podría elegir realmente. Un principio sin alternativa rechazada es un eslogan.

6. Anti-visión. Qué se niega a convertirse este producto, explícitamente. Esta es la capa que los equipos omiten y la única que alguna vez resuelve una discusión. Nombra los productos adyacentes en los que podría derivar y di no a cada uno.

7. Horizonte. Hacia dónde va esto en dos o tres años, como dirección, no como hoja de ruta. Las hojas de ruta pertenecen al gestor de tareas y se quedan obsoletas en un trimestre.

8. La única oración. Si alguien recuerda exactamente una cosa, que sea esta.

9. La prueba de alineación. De tres a cinco preguntas que cualquier funcionalidad propuesta debe superar. Estas son lo que la regla del paso 4 ejecutará realmente.

Paso 3 — valida antes de enviarlo

Revisa cada una, y corrige en lugar de racionalizar:

• La esencia sobrevive a una reescritura completa con tecnología diferente
• Ninguna capa nombra una funcionalidad, una pantalla o un proveedor
• La anti-visión nombra alternativas reales, no hombres de paja
• Los principios tienen un lado rechazado que alguien podría haber elegido genuinamente
• Nada contradice docs/ux/foundation.md — y si algo lo hace, eso es un hallazgo que se debe informar, no algo que se deba silenciar
• Un desconocido podría usar la prueba de alineación para rechazar una funcionalidad plausible

Paso 4 — instala la regla de alineación

Escribe la regla en el archivo de instrucciones propio del proyecto, el mismo que usa ux-rule: CLAUDE.md para Claude Code, AGENTS.md para Codex y opencode, GEMINI.md para Gemini. Detecta cuál tiene ya el proyecto; crea CLAUDE.md solo si no existe ninguno. Nunca codifiques la ruta de un solo agente — una regla instalada donde el agente en ejecución no puede verla es peor que ninguna regla, porque todos creen que está cubierta.

Idempotente: si el encabezado ya está presente, actualiza el bloque en su lugar en lugar de añadir una segunda copia.

## Alineación con la visión — regla estricta (super-ux)

Antes de planificar cualquier nueva funcionalidad, capacidad o cambio significativo, verifícalo contra `docs/ux/vision.md` — específicamente la **anti-visión** y la **prueba de alineación**.

**Alineado** → procede, y di en una línea a qué parte de la visión sirve.

**Desalineado** → detente y dilo antes de escribir código:
1. Nombra el conflicto — qué capa contradice, citando esa capa.
2. Ofrece dos caminos: (a) reformular la funcionalidad para que encaje, con el cambio específico; (b) modificar la visión, diciendo qué capa cambia y qué costo tiene.
3. Espera la decisión. No elijas uno en silencio.

**NO actives para:** correcciones de errores, refactorizaciones, trabajo de dependencias, pruebas, documentación, o cualquier cosa sin superficie visible para el usuario. Una verificación de visión para una corrección tipográfica es cómo un equipo aprende a saltarse la verificación que importa.

Paso 5 — apunta el README hacia allí

Una línea debajo de la visión general del proyecto que enlace a docs/ux/vision.md. Una visión que nadie puede encontrar desde la puerta principal es una visión que nadie lee.

Errores comunes

Error	Por qué falla
La esencia nombra la tecnología	deja de ser cierta en la primera reescritura
Principios sin lado rechazado	"valoramos la calidad" no resuelve ningún argumento
Sin anti-visión	falta la única capa que decide cuestiones de alcance
Horizonte escrito como hoja de ruta	obsoleto en un trimestre, y luego todo el documento se lee como obsoleto
Visión contradice foundation.md	dos fuentes de verdad, y los equipos siguen la que leen en último lugar
Regla instalada en la ruta codificada de un solo agente	invisible para el agente que realmente se ejecuta; nadie lo nota, porque la ausencia se ve idéntica al cumplimiento
Escrito desde el README	describe el README