Vision

vision — what the product is, and what it refuses to become

Part of super-ux — see system-map.md for the whole pipeline. After writing the document, run python3 docs/ux/lint.py.

The layer above ux-foundation. Foundation answers who uses the product and why; vision answers what the product is and what it refuses to become. Without it, "should we build this?" has no answer that outlives the person who last had an opinion.

Do not confuse it with scenarios.md, the other layer whose name starts with "what": scenarios say what the product does, step by step. A feature can be perfectly scenario'd and still violate the anti-vision.

This skill produces two things, and the second is the point.

1. docs/ux/vision.md — the document.
2. A vision-alignment rule in the project's own instruction file, so every later feature gets checked against the vision instead of the vision being written once and never read.

A vision nothing reads is a document, not a constraint.

Fits the chain: vision → foundation (personas, JTBD, journeys, stories) → flows → scenarios → audit. Each layer traces up to the one above it. The chain has a spoken opt-out: the operator declines it by saying "no scenarios" / «без сценариев» — proceed without those layers and say so.

Step 0 — read the project, not its README

Before writing a word:

1. README.md, ARCHITECTURE.md, ROADMAP.md, CHANGELOG.md, everything in docs/.
2. Key source: entry points, main services, the schema, the routing table.
3. Marketing surfaces if they exist — landing, pricing, features.
4. package.json / pyproject.toml / Cargo.toml for what it actually depends on.
5. The live UI. What the product does, not what it says it does.
6. If docs/ux/foundation.md exists, read it — the vision must not contradict the personas and jobs already agreed.

A vision written from the README alone describes the README. The gap between what a project says it is and what its code does is usually where the real vision is hiding, and naming that gap out loud is often the most valuable thing this skill does.

Step 1 — the transformation

Answer internally before writing:

User BEFORE this product exists →  [chaos / complexity / pain]
User AFTER  this product exists →  [clarity / simplicity / power]

Everything below flows from this. If you cannot state it, you do not yet know the product well enough to write its vision — go back to step 0.

Step 2 — write docs/ux/vision.md in nine layers

Every layer is mandatory. Write in the project's documentation language — and the vision's nine sections are identified by their NUMBER, not their English title: write ## 6. <title in your language>, never translate the number away. The section contract is ux-scenarios/references/scenario-format.md → docs/ux/vision.md — read it before writing the vision, because the linter keys on the number and a missing section (e.g. anti-vision) FAILs regardless of language.

1. Essence. One sentence. [Product] is [type of system] that changes how [user] [does X]. No feature names, no UI, no technology. The test: if the product were rebuilt from scratch on a different stack, would this sentence still be true? If not, it names an implementation, not an essence.

2. Core idea. Not a problem statement — an observation about the world.

[X] is abundant.
[Y] is scarce.
→ this product bridges the gap.

One observation, not a list. "Information is abundant, clarity is scarce."

3. What the system does. Continuous behaviour, verbs not nouns: observes … understands … transforms … surfaces …. No feature names. "Has a dashboard" is not behaviour; "surfaces contradictions between sources" is.

4. The user's role. What the user becomes when using it. Not "the user clicks" — the user directs, judges, decides. If the user's role is indistinguishable from operating any other tool, the vision is not yet specific.

5. Principles. Three to five, each in the form we do X, not Y, where Y is something a reasonable team would actually choose. A principle with no rejected alternative is a slogan.

6. Anti-vision. What this product refuses to become, explicitly. This is the layer teams skip and the only one that ever settles an argument. Name the adjacent products it could drift into and say no to each.

7. Horizon. Where this goes in two to three years, as a direction, not a roadmap. Roadmaps belong in the tracker and go stale in a quarter.

8. The one sentence. If someone remembers exactly one thing, this is it.

9. The alignment test. Three to five questions any proposed feature must pass. These are what the rule in step 4 will actually run.

Step 3 — validate before you ship it

Check every one, and fix rather than rationalize:

• Essence survives a total rewrite on different technology
• No layer names a feature, a screen, or a vendor
• The anti-vision names real alternatives, not strawmen
• Principles have a rejected side that someone might genuinely have picked
• Nothing contradicts docs/ux/foundation.md — and if something does, that is a finding to raise, not to quietly smooth over
• A stranger could use the alignment test to reject a plausible feature

Step 4 — install the alignment rule

Write the rule into the file the running HOST actually reads — decide the target by host capability FIRST: CLAUDE.md for Claude Code, AGENTS.md for Codex and opencode, GEMINI.md for Gemini. Detect the active host by its marker directory (.claude/, .codex/, .gemini/); an explicit project target (a file already carrying the rule) takes priority over the default. When NONE exists, create the one THIS host reads — AGENTS.md on a Codex project, GEMINI.md on a Gemini one, CLAUDE.md only when the host is Claude or undetectable. Never hardcode CLAUDE.md — a rule installed where the running agent cannot see it is worse than no rule, because everyone believes it is covered.

A mixed-host project (more than one marker present) gets the rule in EACH active host's file, every target marked explicitly, so no host is left uncovered.

Idempotent: if the heading is already present in a host's file, update the block in place rather than appending a second copy; a repeat run writes nothing new.

## Vision alignment — hard rule (super-ux)

Before planning any new feature, capability or significant change, check it
against `docs/ux/vision.md` — specifically the **anti-vision** and the
**alignment test**.

**Aligned** → proceed, and say in one line which part of the vision it serves.

**Misaligned** → stop and say so before writing code:
1. Name the conflict — which layer it contradicts, quoting that layer.
2. Offer two paths: (a) reshape the feature to fit, with the specific change;
   (b) amend the vision, saying which layer changes and what that costs.
3. Wait for the decision. Do not pick one silently.

**Do NOT trigger for:** bug fixes, refactors, dependency work, tests,
documentation, or anything with no user-facing surface. A vision check on a
typo fix is how a team learns to skip the check that matters.

Step 5 — point the README at it

One line under the project's overview linking docs/ux/vision.md. A vision nobody can find from the front door is a vision nobody reads.

Common mistakes