ssheleg/super-ux

vision — ce qu’est le produit, et ce qu’il refuse de devenir

Fait partie de super-ux — voir system-map.md pour l’ensemble du pipeline. Après avoir écrit le document, exécutez python3 docs/ux/lint.py.

La couche au-dessus de ux-foundation. Foundation répond qui utilise le produit et pourquoi ; vision répond ce qu’est le produit et ce qu’il refuse de devenir. Sans elle, « devrait-on construire cela ? » n’a pas de réponse qui survive à la personne qui a eu le dernier avis.

Ne la confondez pas avec scenarios.md, l’autre couche dont le nom commence par « quoi » : les scénarios disent ce que le produit fait, étape par étape. Une fonctionnalité peut être parfaitement scénarisée et violer pourtant l’anti-vision.

Cette compétence produit deux choses, et la seconde est le point crucial.

1. docs/ux/vision.md — le document.
2. Une règle d’alignement sur la vision dans le fichier d’instructions du projet lui-même, afin que toute fonctionnalité ultérieure soit vérifiée par rapport à la vision plutôt que celle-ci soit écrite une fois et jamais relue.

Une vision que personne ne lit est un document, pas une contrainte.

S’insère dans la chaîne : vision → fondation (personas, JTBD, parcours, récits) → flux → scénarios → audit. Chaque couche remonte à celle qui la précède.

Étape 0 — lisez le projet, pas son README

Avant d’écrire le moindre mot :

1. README.md, ARCHITECTURE.md, ROADMAP.md, CHANGELOG.md, tout ce qui se trouve dans docs/.
2. Source clé : points d’entrée, services principaux, schéma, table de routage.
3. Surfaces marketing si elles existent — page d’accueil, tarification, fonctionnalités.
4. package.json / pyproject.toml / Cargo.toml pour ses dépendances réelles.
5. L’interface live. Ce que le produit fait, pas ce qu’il dit faire.
6. Si docs/ux/foundation.md existe, lisez-le — la vision ne doit pas contredire les personas et les jobs déjà validés.

Une vision écrite à partir du seul README décrit le README. L’écart entre ce qu’un projet dit qu’il est et ce que son code fait est généralement l’endroit où se cache la véritable vision, et nommer cet écart à voix haute est souvent la chose la plus précieuse que cette compétence apporte.

Étape 1 — la transformation

Répondez intérieurement avant d’écrire :

Utilisateur AVANT que ce produit existe →  [chaos / complexité / douleur]
Utilisateur APRÈS que ce produit existe →  [clarté / simplicité / puissance]

Tout le reste découle de cela. Si vous ne pouvez pas le formuler, vous ne connaissez pas encore assez le produit pour écrire sa vision — revenez à l’étape 0.

Étape 2 — écrivez docs/ux/vision.md en neuf couches

Chaque couche est obligatoire. Écrivez dans la langue de documentation du projet.

1. Essence. Une phrase. [Produit] est [type de système] qui change la façon dont [l’utilisateur] [fait X]. Pas de noms de fonctionnalités, pas d’interface, pas de technologie. Le test : si le produit était reconstruit de zéro sur une pile différente, cette phrase serait-elle toujours vraie ? Sinon, elle nomme une implémentation, pas une essence.

2. Idée centrale. Pas un énoncé de problème — une observation sur le monde.

[X] est abondant.
[Y] est rare.
→ ce produit comble l’écart.

Une observation, pas une liste. « L’information est abondante, la clarté est rare. »

3. Ce que fait le système. Comportement continu, verbes pas noms : observe … comprend … transforme … présente …. Pas de noms de fonctionnalités. « A un tableau de bord » n’est pas un comportement ; « révèle les contradictions entre les sources » l’est.

4. Le rôle de l’utilisateur. Ce que devient l’utilisateur en l’utilisant. Pas « l’utilisateur clique » — l’utilisateur dirige, juge, décide. Si le rôle de l’utilisateur est indistinguible de l’utilisation d’un autre outil, la vision n’est pas encore spécifique.

5. Principes. Trois à cinq, chacun sous la forme nous faisons X, pas Y, où Y est quelque chose qu’une équipe raisonnable pourrait réellement choisir. Un principe sans alternative rejetée est un slogan.

6. Anti-vision. Ce que ce produit refuse de devenir, explicitement. C’est la couche que les équipes sautent et la seule qui mette jamais fin à une dispute. Nommez les produits adjacents dans lesquels il pourrait dériver et dites non à chacun.

7. Horizon. Où cela va dans deux à trois ans, comme une direction, pas une feuille de route. Les feuilles de route appartiennent au gestionnaire de tâches et deviennent obsolètes en un trimestre.

8. La phrase unique. Si quelqu’un se souvient d’une seule chose, c’est celle-ci.

9. Le test d’alignement. Trois à cinq questions auxquelles toute fonctionnalité proposée doit répondre. Ce sont celles que la règle de l’étape 4 exécutera réellement.

Étape 3 — validez avant de livrer

Vérifiez chaque point, et corrigez plutôt que de rationaliser :

• L’essence survit à une réécriture totale sur une technologie différente
• Aucune couche ne nomme une fonctionnalité, un écran ou un fournisseur
• L’anti-vision nomme de vraies alternatives, pas des hommes de paille
• Les principes ont un côté rejeté que quelqu’un aurait pu vraiment choisir
• Rien ne contredit docs/ux/foundation.md — et si quelque chose le fait, c’est une observation à soulever, pas à étouffer discrètement
• Un inconnu pourrait utiliser le test d’alignement pour rejeter une fonctionnalité plausible

Étape 4 — installez la règle d’alignement

Écrivez la règle dans le fichier d’instructions du projet lui-même, le même que ux-rule utilise : CLAUDE.md pour Claude Code, AGENTS.md pour Codex et opencode, GEMINI.md pour Gemini. Détectez lequel le projet a déjà ; créez CLAUDE.md uniquement si aucun n’existe. Ne codez jamais en dur le chemin d’un seul agent — une règle installée là où l’agent en cours d’exécution ne peut pas la voir est pire que pas de règle, car tout le monde croit qu’elle est couverte.

Idempotent : si l’en-tête est déjà présent, mettez à jour le bloc sur place plutôt que d’ajouter une seconde copie.

## Alignement sur la vision — règle stricte (super-ux)

Avant de planifier toute nouvelle fonctionnalité, capacité ou changement significatif,
vérifiez-la par rapport à `docs/ux/vision.md` — en particulier **l’anti-vision** et
le **test d’alignement**.

**Aligné** → procédez, et dites en une ligne quelle partie de la vision elle sert.

**Non aligné** → arrêtez-vous et dites-le avant d’écrire du code :
1. Nommez le conflit — quelle couche il contredit, en citant cette couche.
2. Proposez deux voies : (a) remodeler la fonctionnalité pour qu’elle corresponde, avec
   le changement spécifique ; (b) amender la vision, en disant quelle couche change et
   quel en est le coût.
3. Attendez la décision. N’en choisissez pas une en silence.

**Ne PAS déclencher pour :** les corrections de bugs, les refactorisations, le travail sur
les dépendances, les tests, la documentation, ou tout ce qui n’a pas de surface utilisateur.
Une vérification de vision sur une correction de faute de frappe est la façon dont une
équipe apprend à sauter la vérification qui compte.

Étape 5 — pointez le README vers elle

Une ligne sous l’aperçu du projet liant à docs/ux/vision.md. Une vision que personne ne peut trouver depuis la porte d’entrée est une vision que personne ne lit.

Erreurs courantes

Erreur	Pourquoi ça casse
L’essence nomme la technologie	elle cesse d’être vraie à la première réécriture
Principes sans côté rejeté	« nous valorisons la qualité » ne tranche aucun débat
Pas d’anti-vision	la seule couche qui décide du périmètre, manquante
Horizon écrit comme une feuille de route	obsolète en un trimestre, et tout le document devient alors obsolète
La vision contredit foundation.md	deux sources de vérité, et les équipes suivent celle qu’elles lisent en dernier
La règle installée sur un chemin codé en dur d’un seul agent	invisible pour l’agent en cours d’exécution ; personne ne le remarque, car l’absence a le même aspect que la conformité
Écrite à partir du README	décrit le README