Vision, Derived

Why this is the hard call, and why it moves rather than dies

This section describes the system being replaced — the Flutter app under legacy/, still deployed. Its table, route and function names are legacy names and do not appear in the rebuild. Everything under What frame B changes is the rebuild.

Frame A is the most load-bearing screen in the current flow. Those sixteen tiles write project_vision_values, which pre-selects up to three strategy_priorities on a seeded decision wherever a priority crosswalks to a ranked value, and which powers the vision gate, the revisit digest, the vision digest and the Journey card.

It is also silently skippable. Select nothing, tap Continue, and no PUT fires at all. Every decision then ships with zero pre-selected priorities and the user is never told. The most consequential input in onboarding has no floor.

And there is no back button anywhere in post-creation onboarding (onBack: null), so those picks are unrevisable the moment you advance.

What frame B changes, and what it does not

• The data model barely changes, and what it did gain is exactly what this frame needs. Same rank, same deal-breaker flag, same replace-set write — ReplaceVisionValues deletes the project's set and re-inserts it whole (postgres.go:3376). What moved is the naming: the rebuild's table is vision_values, a value is its label rather than a value_key, the flag is spelled is_dealbreaker, and the route is PUT /projects/{p}/vision (vision.go:37) — not the legacy /api one. And the table carries answer_id (0001_init.sql:1511), a nullable pointer to the answer a value was drawn from. That column is the evidence line, already in the schema and waiting for this screen. An earlier revision of this bullet said the model does not change at all and named value_key, is_deal_breaker and PUT /api/projects/:id/vision; none of the three exists anywhere in the rebuild.
• Every line cites its source. That is the reflect-back pattern from the conversation applied to priorities. It is also the correction mechanism: a wrong inference is visible and one tap from gone.
• Rank comes from evidence, not tap order. Today rank is literally the sequence you happened to tap in.
• "Not heard yet" is stated out loud. Three values the kitchen conversation gave no signal on, plus a door to all sixteen. Silence is shown rather than hidden, which is the same rule as declining to record a vague word.
• Aging in place is the argument. It surfaced from an offhand complaint about bending into cabinets, and from the homeowner saying they wanted that to hold outside the kitchen. On a tile wall, before anyone has thought about a single room, almost nobody picks it. Your own viewer research has it as the thing that is hardest to retrofit and easiest to skip.
• Every line frames B and C cite is a line the homeowner actually said. The transcript on mockup 02, frame D, is the only source of their words, and the evidence lines here quote it — the kids do homework there while I cook, I want the sink in it so I am facing everybody instead of the wall, I hate bending down into cabinets. Two earlier revisions broke that rule in different ways: one pointed at mockup 01, which is the front door and holds no transcript; one had the coach citing "your knees are done", which appears in no conversation anywhere in the set. A fabricated quote inside a screen whose whole argument is provenance is the one error this page cannot afford.

What happens when it is wrong, or incomplete

Legacy again, and this is the one place where that changes what has to be built. reseedProjectVisionPriorities, strategy_priorities and hand_set have no equivalent in the rebuild — zero occurrences across packages/, services/ and apps/. The four guarantees below are what frames C and D promise the homeowner out loud. Nothing implements them yet, and that is Q103's to settle, not this page's.

In the legacy app the backend already makes editing safe, which is why frames C and D need no modals or confirmations. reseedProjectVisionPriorities does four things that matter here:

• It skips hand_set rows. If you adjusted a priority on one decision by hand, a vision edit never stomps it. That is what lets the coach say "take one off and I stop guessing at it."
• It skips decided decisions. A committed option freezes a decision, so nothing you already settled can move under you.
• It is delta-only. A row whose selection already matches is not touched.
• It is idempotent by construction. The code comment calls it "a pure function of (current vision, current rows), so a later vision edit reconciles any partial run." A failed sweep self-heals on the next edit.

So the honest answer to "what if it is wrong" is: change it, and the blast radius is exactly the open decisions you have not touched. Frame C says that out loud rather than making the user guess, and it names the real number: twenty-one open across the nine spaces, per _ds/FICTION.md. An earlier revision said fourteen, which matched nothing.

That answer is honest about the legacy app. It is a promise about the rebuild, and the four guarantees it rests on are the work — not a property the screen inherits by being drawn.

Provenance is the other half

A derived value carries its evidence. A value you add carries "you added this, I had nothing to go on." Those are different claims and the UI should not blur them. It is the same rule as the extractor declining to record a vague word. It also means the "not heard yet" list is a real statement about our ignorance, not a leftover.

And priorities keep arriving

The kitchen is one room of nine. The primary bath will turn up something the kitchen could not, and so will the garage. The answer is not to re-show this screen. A new signal surfaces as one line at the end of that room's conversation, "you said grout is a nightmare to keep clean, that sounds like low upkeep, add it?", with a yes and a no. Frame D shows it.

Once you have answered that once, for that value, it does not come back. Combined with the hand_set protection, the rule is simple: the coach guesses until you touch something, then it stops guessing at that thing.

The trade-off, stated plainly

The first batch of decisions seeds unopinionated, because vision now arrives after the first conversation rather than before it. I think that is fine: nobody sees ranked options until after their first conversation anyway, and today's alternative is a set of priorities picked blind, which produces confident ranking on a bad signal.

If that is wrong, the fallback is three values in onboarding, not a return to sixteen. Ask for the deal-breakers only, and let the rest derive.

Notes on the drawing

• No frame carries the nav bar. Frame A is the onboarding wizard, which has no nav bar today and is drawn verbatim. Frames B, C and D are one guided moment after the first conversation: an eyebrow, a close, and a terminal action. They are a flow the homeowner passes through rather than a destination they stand in, and a dock on any of them would claim otherwise. Mockups 13 and 15 are where the bar belongs.
• Ranks are ordinals, never fractions. A rank is a position in a list of three or four. There is no bar, no percentage and no "3 of 16" anywhere on these frames. Frame A's "eight more below" is a count of what is off screen and nothing else.
• Three rules stay page-scoped, and only three. .tile is frame A's sixteen-up picker, .rank is the ordinal dot and .why is the evidence line under a derived priority. None of them exists in _ds/hc.css. The three that also used to sit here did nothing but shave .card, .callout and .section-header back below the shared rhythm, and they are gone. All four frames now run past the bottom of the phone, which is correct.