[feat·M1] First-review value preview — show the engine finding before required questions

[atomchung]

Status

Owner-approved implementation — M1 UX hardening from owner-live evidence.

This is the implementation leaf for #507’s first-review friction finding. It is not a broad lifecycle rewrite and does not replace #291’s question-density contract in the first slice.

The current #610 candidate is frozen for the separate card-free consider walk. Development may proceed on an isolated branch, but merging product changes requires an explicitly re-frozen candidate after that walk begins.

Milestone

M1 acceptance hardening — transaction-history first-review experience.

This is a product-value defect, not an arithmetic, privacy, or state-integrity defect. It owns the first visible value before the existing required-question sequence.

User outcome

After supplying transaction history, the user sees a short, engine-grounded preliminary finding before answering the first motive/thesis question.

The opening tells them:

1. what the engine has already found;
2. what the current record can support now;
3. how many questions remain;
4. why the next question is needed;
5. which conclusion or durable follow-up that answer can change.

The user no longer has to complete an unexplained interview before discovering whether FOMO Kernel found anything useful.

Target journey:

transaction history accepted
→ preliminary engine finding and value preview
→ one grounded question at a time, each stating what its answer changes
→ complete private review card
→ rule choice / skip in the existing card beat
→ finalize and deliver

Current behavior / evidence

Verified on main@8825e5e2bf9844e9181ce2b13ae65e595d3d7b27:

• QUESTION_POLICY requires first_review to ask three to five questions when eligible.
• flows/first-review.md step 1 gives only generic expectations, then step 2 asks every required question before preview.
• references/interaction-delivery.md requires each question to occupy its own visible turn.
• The full pending Review Plan contains engine_card and engine_state, but _plan_for_agent deliberately removes both. The agent may not inspect a raw card and invent a summary; preview/finalize reload those facts from canonical pending state.
• Question rows may carry asked_because, but that explains selection basis, not the user-visible result that answering will change.
• Owner-live feedback, 2026-08-01: “产品问我一堆问题，但我根本不知道我最后能拿到什么。现在体验起来，没有办法很直观地感受到产品价值。” Recorded on [research·UX] 定义交易流程中的必要摩擦：何时必须追问、预览、承诺，何时应快速结束 #507 as comment 5150675212.

Problem and consequence

The current route optimizes durable information gain before proving immediate value.

Consequences:

• the user experiences a form or interview instead of a diagnosis;
• the value of each answer is hidden until the final card;
• a first-time user may abandon before seeing differentiated engine output;
• README/onboarding can explain the product promise, but runtime does not visibly earn the questions;
• adding better controls or more options does not solve the missing value bargain.

This is stronger than the earlier redundant card/rule-choice wait fixed under #507: that second wait was removed, but the entire pre-card question sequence still precedes visible product value.

Decision

1. Add one engine-owned opening_value surface to the projected Review Plan

The first slice adds a small, versioned, localized block that survives _plan_for_agent and is safe to display before questions.

It is derived only from facts and rankings already computed for the pending review, for example:

• the top supported behavioral/portfolio finding already selected by the engine;
• one or two engine-owned grounding facts;
• the current data boundary that materially qualifies the finding;
• required-question count.

It is preliminary, not a pre-rendered final card. It must not state a motive, user-confirmed thesis, final verdict, or rule that depends on unanswered questions.

Do not expose raw engine_card or engine_state to the agent. Do not ask the agent to calculate or independently choose the top numeric fact.

2. Present opening_value before the first question

flows/first-review.md and references/interaction-delivery.md must require this order:

opening value → question 1 → … → preview/card beat

The opening is one concise beat, not a second card or a long metrics summary.

3. Every required question states what the answer changes

Add an engine-owned/localized answer_effect (name may change during implementation, semantics may not) beside the existing asked_because.

The two fields answer different user questions:

• asked_because: why this candidate ranked into the queue;
• answer_effect: what visible conclusion, classification, reconciliation, or future reader can change after the answer.

Examples of allowed effects:

• distinguishes a deliberate add from an emotional reaction in the final interpretation;
• confirms/corrects an entry thesis used by later review reconciliation;
• records the exit reason that a future revisit will compare;
• settles whether a crossed condition was valid or misleading.

Do not promise a changed card when two answers genuinely lead to the same output; that question would violate #429 and should not be required.

4. Keep the existing question count in the first slice

Do not immediately repeal #291’s three-to-five question band. First prove that visible value and explicit answer effects materially improve the journey.

A later cut may classify questions into:

• truth-critical blocking questions;
• optional memory enrichment after first result.

That decision requires owner-live evidence from this slice; it is not bundled here.

5. Preserve every truth and lifecycle gate

• Required answers remain required for the final verdict/card where the engine says so.
• Preview validation, user-owned rule choice/skip, finalize, delivery receipts, interruption recovery, idempotency, privacy, and canonical state remain unchanged.
• No new recommendation, price target, market forecast, persistence stream, profile object, or rule ontology.

Scope

• one projected opening_value contract;
• deterministic/localized renderer or builder using existing ranked engine facts;
• one answer_effect contract for selected question kinds;
• first-review flow and interaction-delivery changes;
• production-shaped synthetic trajectory and cross-host text presentation;
• owner-live verdict and timing evidence.

Non-goals

• No raw engine_card exposure to the agent.
• No agent-side arithmetic or parallel ranking truth.
• No new behavioral score or generic DecisionCommunicationPlan domain object.
• No immediate reduction of the three-to-five question band.
• No card redesign, new memory stream, M2 rationale work, rule-learning work, market/news expansion, or graphical application.
• No claim that the preliminary finding is the final verdict.

Acceptance criteria

• A production-shaped first_review emits a schema-valid, localized opening_value in the agent projection before any answer exists.
• The opening cites at least one engine-owned ranked fact and is visibly labelled preliminary/pending motive clarification.
• The opening contains no user motive or thesis claim that has not been confirmed.
• The agent never receives raw engine_card/engine_state as the mechanism for producing the opening.
• Removing or suppressing opening_value makes a first-review interaction test fail.
• Every selected required question carries a non-empty answer_effect whose stated consumer/branch is real.
• asked_because and answer_effect remain semantically distinct and both are shown without internal schema language.
• Plain-text Claude/Codex trajectories show the opening before question 1 and preserve one-question-per-turn afterward.
• Existing preview/finalize, required-answer, provenance, delivery, recovery, idempotency, privacy, and card tests remain green.
• Public fixtures and receipts use only fictional/generic data.
• Owner-live acceptance: before answering the first question, the owner can state what useful finding already exists and what the next answer will change.
• Timing evidence records input accepted → opening value visible and input accepted → preview delivered under [design·perf] Response-time budget by route — separate real-user latency from QA/test overhead #603.

Dependencies

• [research·UX] 定义交易流程中的必要摩擦：何时必须追问、预览、承诺，何时应快速结束 #507 — UX authority and owner-live failure evidence.
• [product·P1] Route-specific question density: first review three to five, weekly one to three #291 — current question-density contract; unchanged in this first slice.
• [P0·cross-client UX] Codex 無法完成選項互動與卡片交付；artifact 綠不等於 review 完成 #230 / references/interaction-delivery.md — cross-host presentation and actual delivery.
• [design·P1] Two questions collect an answer nothing reads: initial_thesis and exit_consistency (proved by a byte-identical card) #429 — every question needs a real reader/branch.
• [design·perf] Response-time budget by route — separate real-user latency from QA/test overhead #603 — route timing evidence.
• [QA·dogfood] Judgment-quality dogfood — does a real consider answer now carry a supported insight? #610 / tracking: current context index — milestone, critical path, what an agent may pick up #27 — separate frozen consider acceptance lane and candidate-freeze discipline.
• PR docs(readme): present the end-to-end product experience #701 / [docs·GTM] Rebuild README around the user's decision moment and current product routes #699 — README should describe the current runtime honestly but does not fix this defect.

Privacy boundary

Real transaction history, holdings, motives, preliminary findings, answers and cards remain local. GitHub issues, tests, PRs and receipts use only fictional, synthetic, generic or de-identified evidence. No private-repository content enters this issue.

Rollout / compatibility / recovery

The new block is derived presentation state inside the pending plan. It creates no new canonical user-memory source and requires no legacy migration.

Older pending sessions without opening_value remain resumable through a documented compatibility fallback. A failed opening render must not mutate the session or bypass the existing question/card lifecycle. The change is reversible without touching finalized sessions or projections.

Stop condition

Stop after one reviewable vertical slice proves:

1. value is visible before question 1;
2. each question explains what it changes;
3. the final card remains honest and recoverable;
4. owner-live feedback decides whether question reclassification/reduction is warranted.

Do not continue automatically into reducing all questions, redesigning the card, or adding memory architecture.

[atomchung]

Owner sequencing update — highest-value remaining QA UX leaf, but do not bundle into #727

Today's owner feedback still makes this the largest unresolved first-review experience problem: the product asks several questions before proving that it found anything useful.

Implementation remains authorized, but sequence it after the smaller tonight cuts (#727 narrowing, #666, #681, and preferably #682) rather than mixing it into them. If capacity remains, open one isolated PR implementing only opening_value and real answer_effect contracts with backward-compatible pending-session fallback. Do not reduce the question band, expose raw engine_card, redesign cards, or add memory.

This is not a safe “copy-only” merge: it touches the first-review projected plan and ordering, so require focused lifecycle/recovery tests, full CI and independent review. Owner-live acceptance stays tomorrow. If it cannot reach that evidence boundary tonight, leave it as the first next implementation rather than rushing a partially verified merge.

This comment is the current owner sequencing authority for #714; the issue body remains the product contract.

[atomchung]

CLAIM — Claude Code session — branch claude/issue-714-opening-value, from main@9751ced (post-#730).

Owner routing on 2026-08-02: the owner-live acceptance walk runs in parallel, so this develops on an isolated branch and does not merge into the frozen candidate. Per #713, development may be parallel; merge and acceptance stay serial.

Scope is this issue's first vertical slice only: one projected opening_value before question 1, and one answer_effect per required question. No question-band reduction, no card redesign, no memory architecture.