ssheleg/super-ux

Vision – was das Produkt ist und was es nicht werden will

Teil von super-ux — siehe system-map.md für die gesamte Pipeline. Führen Sie nach dem Schreiben des Dokuments python3 docs/ux/lint.py aus.

Die Ebene über ux-foundation. Die Foundation beantwortet wer das Produkt verwendet und warum; die Vision beantwortet was das Produkt ist und was es nicht werden will. Ohne sie hat die Frage „Sollten wir das bauen?“ keine Antwort, die länger lebt als die Person, die zuletzt eine Meinung hatte.

Verwechseln Sie sie nicht mit scenarios.md, der anderen Ebene, deren Name mit „was“ beginnt: Szenarien sagen, was das Produkt Schritt für Schritt tut. Ein Feature kann perfekt szenariotisiert sein und dennoch gegen die Anti-Vision verstoßen.

Dieses Skill produziert zwei Dinge, und das zweite ist der Punkt.

1. docs/ux/vision.md — das Dokument.
2. Eine Ausrichtungsregel für die Vision in der projekteigenen Instruktionsdatei, sodass jedes spätere Feature gegen die Vision geprüft wird, anstatt dass die Vision einmal geschrieben und nie wieder gelesen wird.

Eine Vision, die niemand liest, ist ein Dokument, keine Einschränkung.

Passt in die Kette: Vision → Foundation (Personas, JTBD, Journeys, Stories) → Flows → Szenarien → Audit. Jede Ebene verweist auf die darüberliegende.

Schritt 0 – Lesen Sie das Projekt, nicht seine README

Bevor Sie ein Wort schreiben:

1. README.md, ARCHITECTURE.md, ROADMAP.md, CHANGELOG.md, alles in docs/.
2. Wichtige Quellen: Einstiegspunkte, Hauptdienste, das Schema, die Routing-Tabelle.
3. Marketing-Oberflächen, falls vorhanden – Landingpage, Preisseite, Features.
4. package.json / pyproject.toml / Cargo.toml für die tatsächlichen Abhängigkeiten.
5. Die Live-Benutzeroberfläche. Was das Produkt tut, nicht was es sagt, dass es tut.
6. Wenn docs/ux/foundation.md existiert, lesen Sie sie – die Vision darf nicht im Widerspruch zu den bereits vereinbarten Personas und Jobs stehen.

Eine Vision, die allein aus der README geschrieben wurde, beschreibt die README. Die Lücke zwischen dem, was ein Projekt zu sein vorgibt, und dem, was sein Code tatsächlich tut, ist oft der Ort, an dem die wahre Vision verborgen liegt. Diese Lücke beim Namen zu nennen, ist oft das Wertvollste, was dieses Skill leistet.

Schritt 1 – die Transformation

Beantworten Sie im Stillen, bevor Sie schreiben:

Benutzer VOR diesem Produkt →  [Chaos / Komplexität / Schmerz]
Benutzer NACH diesem Produkt → [Klarheit / Einfachheit / Stärke]

Alles Weitere folgt daraus. Wenn Sie es nicht formulieren können, kennen Sie das Produkt noch nicht gut genug, um seine Vision zu schreiben – gehen Sie zurück zu Schritt 0.

Schritt 2 – schreiben Sie docs/ux/vision.md in neun Schichten

Jede Schicht ist obligatorisch. Schreiben Sie in der Dokumentationssprache des Projekts.

1. Essenz. Ein Satz. [Produkt] ist [Art von System], das verändert, wie [Benutzer] [X tut]. Keine Feature-Namen, keine Benutzeroberfläche, keine Technologie. Der Test: Würde dieser Satz immer noch stimmen, wenn das Produkt von Grund auf mit einem anderen Stack neu gebaut würde? Wenn nicht, benennt er eine Implementierung, keine Essenz.

2. Kernidee. Keine Problemstellung – eine Beobachtung über die Welt.

[X] ist reichlich vorhanden.
[Y] ist knapp.
→ dieses Produkt überbrückt die Lücke.

Eine Beobachtung, keine Liste. „Informationen sind reichlich vorhanden, Klarheit ist knapp.“

3. Was das System tut. Kontinuierliches Verhalten, Verben statt Substantive: beobachtet … versteht … transformiert … macht sichtbar …. Keine Feature-Namen. „Hat ein Dashboard“ ist kein Verhalten; „macht Widersprüche zwischen Quellen sichtbar“ ist es.

4. Die Rolle des Benutzers. Was der Benutzer wird, wenn er es verwendet. Nicht „der Benutzer klickt“ – der Benutzer lenkt, beurteilt, entscheidet. Wenn die Rolle des Benutzers nicht von der Bedienung eines anderen Werkzeugs zu unterscheiden ist, ist die Vision noch nicht konkret genug.

5. Prinzipien. Drei bis fünf, jedes in der Form wir tun X, nicht Y, wobei Y etwas ist, das ein vernünftiges Team tatsächlich wählen würde. Ein Prinzip ohne abgelehnte Alternative ist ein Slogan.

6. Anti-Vision. Was dieses Produkt nicht werden will, explizit. Dies ist die Schicht, die Teams auslassen, und die einzige, die jemals einen Streit beilegt. Nennen Sie die benachbarten Produkte, in die es abgleiten könnte, und sagen Sie zu jedem Nein.

7. Horizont. Wohin sich das Produkt in zwei bis drei Jahren entwickelt, als Richtung, nicht als Roadmap. Roadmaps gehören ins Tracking-System und werden in einem Quartal alt.

8. Der eine Satz. Wenn sich jemand genau eine Sache merkt, dann diese.

9. Der Ausrichtungstest. Drei bis fünf Fragen, die jedes vorgeschlagene Feature bestehen muss. Diese sind das, was die Regel in Schritt 4 tatsächlich anwenden wird.

Schritt 3 – validieren, bevor Sie es ausliefern

Überprüfen Sie jeden Punkt und korrigieren Sie, anstatt zu rationalisieren:

• Essenz überlebt eine vollständige Neuschreibung mit anderer Technologie
• Keine Schicht nennt ein Feature, einen Bildschirm oder einen Anbieter
• Die Anti-Vision nennt reale Alternativen, keine Strohmänner
• Prinzipien haben eine abgelehnte Seite, die jemand wirklich hätte wählen können
• Nichts widerspricht docs/ux/foundation.md – und wenn doch, ist das ein Befund, den man ansprechen muss, nicht stillschweigend glattbügeln
• Ein Fremder könnte mit dem Ausrichtungstest ein plausibles Feature ablehnen

Schritt 4 – die Ausrichtungsregel installieren

Schreiben Sie die Regel in die projekteigene Instruktionsdatei, dieselbe, die auch ux-rule verwendet: CLAUDE.md für Claude Code, AGENTS.md für Codex und opencode, GEMINI.md für Gemini. Erkennen Sie, welche das Projekt bereits hat; erstellen Sie CLAUDE.md nur, wenn keine existiert. Hardcoden Sie niemals den Pfad eines einzelnen Agenten – eine Regel, die an einem Ort installiert ist, wo der laufende Agent sie nicht sehen kann, ist schlimmer als keine Regel, weil alle glauben, sie sei abgedeckt.

Idempotent: Wenn die Überschrift bereits vorhanden ist, aktualisieren Sie den Block an Ort und Stelle, anstatt eine zweite Kopie anzuhängen.

## Vision-Ausrichtung – harte Regel (super-ux)

Bevor Sie ein neues Feature, eine neue Fähigkeit oder eine wesentliche Änderung planen, prüfen Sie sie gegen `docs/ux/vision.md` – insbesondere gegen die **Anti-Vision** und den **Ausrichtungstest**.

**Ausgerichtet** → fortfahren und in einem Satz sagen, welchem Teil der Vision es dient.

**Nicht ausgerichtet** → anhalten und sagen, bevor Code geschrieben wird:
1. Den Konflikt benennen – welche Schicht widersprochen wird, mit Zitat dieser Schicht.
2. Zwei Wege anbieten: (a) das Feature umgestalten, damit es passt, mit der spezifischen Änderung; (b) die Vision ändern, sagen, welche Schicht sich ändert und was das kostet.
3. Auf die Entscheidung warten. Nicht stillschweigend eine auswählen.

**NICHT auslösen für:** Fehlerbehebungen, Refactorings, Abhängigkeitsarbeiten, Tests, Dokumentation oder alles ohne benutzersichtbare Oberfläche. Eine Visionsprüfung bei einem Tippfehler ist, wie ein Team lernt, die Prüfung zu überspringen, die zählt.

Schritt 5 – die README darauf verweisen lassen

Eine Zeile unter der Projektübersicht, die auf docs/ux/vision.md verlinkt. Eine Vision, die von der Eingangstür aus niemand finden kann, ist eine Vision, die niemand liest.

Häufige Fehler

Fehler	Warum er kaputt geht
Essenz nennt die Technologie	sie hört auf, beim ersten Rewrite wahr zu sein
Prinzipien ohne abgelehnte Seite	„Wir legen Wert auf Qualität“ beilegt keinen Streit
Keine Anti-Vision	die eine Schicht, die über den Umfang entscheidet, fehlt
Horizont als Roadmap geschrieben	alt in einem Quartal, und dann liest sich das gesamte Dokument als veraltet
Vision widerspricht foundation.md	zwei Quellen der Wahrheit, und Teams folgen der, die sie zuletzt gelesen haben
Die Regel unter einem hartcodierten Pfad eines Agenten installiert	unsichtbar für den tatsächlich laufenden Agenten; niemand bemerkt es, weil Abwesenheit genauso aussieht wie Einhaltung
Aus der README geschrieben	beschreibt die README