[epic·design] How we ask, how we collect, how we distill — one view over the question layer

[atomchung]

Umbrella for the product-experience half of the 2026-07-25 review. #395 and #396 are the two concrete pieces; this issue holds the frame they answer to, and the owner constraint that reshapes both.

The owner constraint (2026-07-25) — options over typing

Prefer options. Do not make the user type. The cost of typing is high enough that a free-text field is a worse question even when it captures a better answer. Lightweight interaction is the binding constraint, not a preference.

This does not conflict with #395's shift from backward motive to forward condition. It changes how that condition is captured:

The options can be concrete conditions the engine generates from this user's own numbers — not abstract categories.

Today (abstract, uncheckable):

Why did you buy NVDA?
  A. I had a planned thesis      B. I chased the momentum
  C. Someone recommended it      D. No clear thesis

Proposed (concrete, mechanically checkable, still one click):

What would make you sell NVDA?
  A. It falls back to $150 (your cost basis)
  B. It passes 40% of the portfolio (32% today)
  C. Quarterly revenue growth drops under 30%
  D. Haven't thought about it

Every option is generated from this user's actual position, so every one is a condition the next review can reconcile mechanically. The click cost is identical to today's. What changes is that the stored answer means something a quarter later.

Two properties worth naming: the option set is itself teaching — a user who has never written a falsifiable condition sees four examples drawn from their own portfolio. And "haven't thought about it" stays a first-class answer, not a hidden skip; it is often the most diagnostic one.

The three questions this epic holds

1. How do we ask? — #395. Forward conditions instead of backward motives, because a backward motive is contaminated by memory decay, hindsight bias, and self-serving attribution. Now constrained to option form per above.

2. How do we collect? — #396. Dynamically generated options break an assumption the delivery contract was built on: answers.json stores one canonical value per question, but a generated option has no stable enum behind it. ux_receipt's surface_digest can still prove the options were presented verbatim (good — that mechanism survives), but what gets written needs a design. Also unresolved: whether an "Other / let me say it myself" escape hatch exists at all, given the constraint above.

3. How do we distill a decision from the answers? — not yet opened. Given a stored condition ("sells if it passes 40% of the portfolio"), the next review must decide: did it trigger, did the user act, and what does the gap mean? The engine already has the machinery for the mechanical half (problems.py, the 30/60/90 due_revisit checkpoints). The judgment half — what a broken condition means, and when it is worth saying — is undesigned. This is where #54's rationalization concern resurfaces: a user who broke their own stated condition will have a reason ready.

What is decided

• Backward motive questions are replaced by forward conditions ([design·P1] Capture forward conditions, not backward motives — the entry-motive question is unfixable as asked #395).
• Options over free text; conditions generated from the user's own numbers.
• All three position states get a forward question: still-held → what would make you sell; already-sold → what would make you buy back; added-to → same reason as the first buy?
• Engine-side facts replace recalled context: show the market conditions frozen at the buy date rather than asking the user to remember them.

What is not decided

• Whether an escape hatch for free text exists (constraint says lean no; [design·P1] An open question has no options — the interaction contract validates a thing #395 removes #396 Q1).
• What answers.json stores for a generated option ([design·P1] An open question has no options — the interaction contract validates a thing #395 removes #396 Q3).
• Whether a clarification turn is allowed ([design·P1] An open question has no options — the interaction contract validates a thing #395 removes #396 Q1) — likely moot under option form.
• How many conditions per review, and which position earns the question.
• The whole of question 3 above.

The problem none of this solves

Ostrich effect: investors check portfolios 9.5% less after market declines (Karlsson, Loewenstein & Seppi 2009; Sicherman, Loewenstein, Seppi & Utkus). The review is most valuable exactly when the user is least likely to open it.

Better questions do not make someone show up during a drawdown. This is a plausible primary cause of why trading journals fail in practice, and it sits upstream of everything above. Not folded in here because it is a different layer — product cadence, not question design.

Pieces

• [design·P1] Capture forward conditions, not backward motives — the entry-motive question is unfixable as asked #395 — how we ask (forward conditions)
• [design·P1] An open question has no options — the interaction contract validates a thing #395 removes #396 — how we collect (delivery contract under generated options)
• (unopened) — how we distill (reconciling a stored condition into a judgment)
• [P2·可信度] Step 2 從「自我定性」改「舉證制」,堵 thesis 洗白器(BACKLOG ISSUE-3 升級追蹤) #54 — rationalization; still live, now applying to question 3 rather than question 1
• Product discovery: define a concrete thesis-reconciliation user flow #199 — thesis-reconciliation user flow; [design·P1] Capture forward conditions, not backward motives — the entry-motive question is unfixable as asked #395's three-state table is that flow

[atomchung]

Persona test: can the engine generate the options? (2026-07-25)

Owner asked whether generated options are feasible, and suggested testing against personas. Run across all 12 committed mock personas, reading candidate_rules and top_holes from each first-review card.

The engine already generates per-ticker checkable conditions. candidate_rules carries params (ticker, actual weight) and a verify field naming how the next review checks it. This is not a new mechanism to build — it is an existing one to re-point.

But the template library is tiny:

Generatable condition	Persona coverage
cut_oversize (single-position weight cap, with ticker + measured weight)	8/12 — all receive the same sentence, differing only in ticker and pct
cut_averaging_down (count of adds into losers)	2/12
no parameterized condition at all	3/12 (day_trader, fundamental, swing get prose principles only)

The real constraint is verifiability, not generation

An LLM can generate an attractive option — "quarterly revenue growth drops below 30%" — trivially. The engine has no revenue data source, so it cannot check whether that condition triggered at the next review.

A condition the engine cannot check later is not a commitment that can be reconciled. It is a nicer-sounding version of the category answer we are replacing.

So: option quality is capped by the engine's verifiable-condition vocabulary. Improving the prompt does nothing. Extending this list does:

	Condition type	Data available
have	single-position weight cap, adds-into-losers count	yes
addable	holding period exceeded, drawdown from peak, lag vs benchmark, distance from cost basis	yes — all already in the card
not addable	revenue, margin, valuation, customer counts	no source

Extending from 2 to ~6 templates resolves most of the 8/12 homogeneity. The bottom row is permanently out of reach, which is exactly why the Other escape hatch below is required.

Owner rulings (2026-07-25)

1. Keep "Other" / let-me-say-it-myself. "We can always guess wrong." This settles [design·P1] An open question has no options — the interaction contract validates a thing #395 removes #396 Q1 — the escape hatch exists. It is also the only route to the un-generatable bottom row above.
2. Do not ask the premortem as its own turn. Rationale: top_holes already computes the structural vulnerabilities, and the vulnerability that only the user knows (their thesis's weak point) is one the engine cannot verify later anyway. Marginal value of the extra turn is ~zero. Generate the options from top_holes instead. This removes a step from [design·P1] Capture forward conditions, not backward motives — the entry-motive question is unfixable as asked #395's tiering — the 80-pt tier is now one turn, not two.
3. Ostrich effect is out of scope. Owner: if the claim is that users avoid opening the app while losing money, there is no fix available and it is not worth solving now. Removed from this epic; not opening an issue for it.

What this makes concrete

The next engineering step is no longer "design a question" — it is extend candidate_rules with four more parameterized templates (holding period, drawdown, benchmark lag, distance from cost), then re-point them from end-of-card rule suggestions to in-question exit-condition options. Both halves are engine work against data already on the card.

[atomchung]

Correction (2026-07-25): fundamentals ARE reachable — owner was right

The comment above claimed revenue/margin/valuation conditions have "no source". That is wrong. Verified against the live API:

NVDA quarterly_income_stmt -> 81.6B / 68.1B / 57.0B / 46.7B  (period ends 2026-04-30, 01-31, 2025-10-31, 07-31)
info.revenueGrowth  0.852      info.grossMargins  0.741
info.trailingPE     31.6       info.forwardPE     16.1

yfinance is already a runtime dependency and already used by market_context.py for daily closes. Fundamentals are the same library, same dependency — an unconnected pipeline, not a missing source.

What this changes

The verifiable-condition vocabulary is materially larger than stated above:

	Condition type	Status
have	weight cap, adds-into-losers count	shipped
addable (price/position)	holding period, drawdown from peak, benchmark lag, distance from cost	data on the card
addable (fundamental)	revenue growth, gross margin, P/E vs entry	yfinance, dependency already present
genuinely unreachable	the user's own research, industry knowledge, who told them	permanent — this is what Other is for

The third row matters most: a fundamental condition is the only kind that expresses "my thesis was wrong" rather than "the price moved". Without it, every generated option is a stop-loss in disguise — which is precisely the degeneration the adversarial review warned about.

Implementation caveats (not blockers)

1. Quarterly cadence — revenue updates once a quarter; most weekly reviews will see no change. The condition is still checkable, just rarely triggered. Do not let that read as "nothing happened".
2. Restatements — reported figures get revised. A condition evaluated against a since-restated number needs a stance.
3. Coverage gaps — ETFs have no revenue; TW listings may be thin. Must degrade through the existing honesty_ledger rather than silently omitting the option.
4. Fiscal ≠ calendar — NVDA's quarters end 4/30, 1/31. Comparing "last quarter" across holdings without normalizing is a real error source.
5. Data quality — scraped fundamentals are less reliable than prices. They gate a user's stated condition, so a wrong number produces a wrong verdict about the user's own discipline. Fail closed.

Owner note

Users may hold trade information we have no way of obtaining.

Correct, and it is the standing argument for the Other escape hatch: no data source reaches what the user knows from their own research or from whoever told them. Extending the pipeline raises the ceiling on generated options; it never removes the need for the manual path.

[atomchung]

Full review of the open rulings (2026-07-25)

Four of the five resolve against constraints already in the code. Only one is a genuine product call.

---

1. What does "Other" look like? → Nothing new to build.

Both delivery modes already accept free text. plain_text presents lettered options and the user types whatever they want; the native-control path carries its own custom-text escape. There is no button to design.

What does need doing is one line in the contract: the answer to a condition question may be any offered option OR a free sentence. Today the engine rejects an answer outside the enum (unsupported initial thesis decision: {choice}). That rejection is the only thing standing in the way — the presentation layer needs no change at all.

2. What does answers.json store for a generated option? → The candidate_rules shape, unchanged.

A generated option already has the right structure — {code, params, rule (rendered text), verify}. Store both halves, for two different consumers:

• code + params — how the next review mechanically checks whether the condition triggered. Without it there is no reconciliation, only prose.
• the frozen rendered text — what the card quotes back. It must be frozen, not re-rendered: copy changes between reviews, and the grounding rules require a commitment to be quoted verbatim as the user saw it.

An "Other" answer is the same shape degraded honestly: {code: "user_stated", text: "…", verify: null}. A null verify is the engine saying I cannot check this one, which the honesty ledger already knows how to disclose. That is the correct outcome — not a gap.

3. How many conditions per review? → One. The budget already decided this.

QUESTION_POLICY["weekly_review"] = {"min": 1, "max": 3}
RULE_BREACH_LIMIT   = 2
INITIAL_THESIS_LIMIT = 2

A weekly review carries at most three questions total (#291's ruling, still in force), and rule-breach questions can already claim two of them. There is room for exactly one condition question, and only if it displaces something.

This is not a preference — arithmetic. It also happens to match the product principle in BACKLOG.md: one card converges on one behavioral leak and at most one rule. A condition per position would be five commitments a user did not think about, which is how you get five conditions nobody meant.

4. Which position earns the question? → top_holes[0]. No new ranking.

The engine already ranks the largest behavioral leak, and #400's Phase 1 generates conditions from top_holes. Asking about the position that ranking points at needs no new logic, and keeps one ranking rather than two that can disagree.

The existing asked_because ranking (largest P&L impact) stays where it is — it answers a different question and the two usually coincide anyway.

5. How do we distill a decision from the answers? → Already built. Do not design it again.

This is the part of the epic marked "unopened", and it turns out not to need opening. _rule_breach_questions is a complete reconciliation loop:

• reads problem_stats.rules_check[].last_breach
• asks once per breach, recording keep_tracking / exception / revise_rule with required notes
• suppresses the repeat unless the same problem worsened (worsened compares trend, count, and amount against the prior decision)

That last property is the hard part of this problem and it is already solved — it is what stops a reconciliation loop from nagging.

The four outcomes a stored condition produces map onto it directly:

Triggered	User acted	Meaning
no	—	nothing to say
yes	yes	kept their own rule — the positive signal the card currently cannot give
yes	no	broke their own commitment — highest diagnostic value
no	yes	acted on something other than the stated condition — worth one question

So question 3 is not a new mechanism. It is extending rule_breach from portfolio-level rules down to per-position conditions, which is the same work as #400 Phase 3. Folding it there rather than opening a separate issue.

#54's concern (the user will have a reason ready for breaking their own rule) applies at exactly this point — and rule_breach already handles it by requiring a note and offering revise_rule only when a deterministic engine metric backs the same problem key.

---

The one genuine product call left

Everything above assumes the condition question displaces an existing question rather than adding to the budget. Two ways to do that, and this one is the owner's:

• A — replace initial_thesis entirely. [design·P1] Capture forward conditions, not backward motives — the entry-motive question is unfixable as asked #395's argument says the backward motive question is unfixable, so stop asking it. First review becomes: structural check + condition questions. Cleanest, and consistent with the design; but it removes a question that has shipped and been dogfooded.
• B — keep one motive question, add one condition. Softer, keeps the entry-motive signal that headline_motive and the behavior tags feed on. Costs one of the three weekly slots and leaves the contaminated-answer problem in place, just smaller.

Not a call the code can make.

[atomchung]

Owner ruling + a correction to the design (2026-07-25)

Ruling: remove the proactive ask, keep the write path

initial_thesis stops being asked proactively. If the user volunteers an entry reason in conversation, the agent still records it to initial_theses.jsonl. (Option C of the three offered.)

The reasoning that changed the design — recency

Owner:

A thing with a long history — you don't know what the reason was. But something recent, you probably remember.

This is the variable the design was missing. Everything written above treats "backward-looking questions are contaminated" as uniform, and it is not: memory decay is a function of elapsed time. A buy from this week is recallable. A buy from two years ago is not.

The current implementation uses none of this. Measured:

• initial_thesis is generated only when route == "first_review"; a weekly review never asks about a position opened during that week.
• Candidates rank by _importance — position size, with no recency term.
• light-capture (the one recency-aware path) fires only when the span since the last review is short, and it degrades the entire review rather than adding one question to a full one.

So today the engine asks about the largest position, not the most recent one. A two-year-old core holding gets the question; a position opened three days ago does not.

What this means for the design

The fix is not "ask fewer motive questions". It is ask about a different position:

• Gate initial_thesis on recency (days since the cycle opened) rather than ranking it by cost basis.
• Positions past the threshold are not asked at all — their motive is inferred from behavior tags (fomo_entry, momentum_follow are computed from price action, never asked) and, going forward, reverse-derived from the exit condition the user states.
• The question count falls out of this naturally instead of being capped. On a portfolio with no recent opens, zero motive questions is the correct answer, not a shortfall to backfill.

Second correction: buy and sell are NOT symmetric

Owner: "it may be fundamentally a bit different from the sell side." Correct, and it falls out of the same variable:

	Typical elapsed time	Emotional salience	Backward question viable?
Entry on a long-held position	months to years	low (a decision among many)	no — infer it, or reverse-derive from the exit condition
Entry this period	days	moderate	yes
Exit this period	days	high — exits are stressed events, and stressed events are recalled better	yes

The three-state table posted earlier in this epic presented buy and sell as mirror images. They are not. An exit is usually recent and emotionally marked, which makes "why did you sell" a materially more reliable question than "why did you buy" — as long as the exit is from this period.

What the owner also flagged

In principle these are two pieces of information, only differing in confidence level. Where information is incomplete, preserving the user's context is worth more.

An exit condition reverse-derives the thesis ("sell if revenue growth drops under 30%" implies the position was bought for revenue growth) but not the state of mind (planned / chased / recommended). Those are genuinely two signals. The state-of-mind half is partly recoverable from behavior tags, which is why removing the proactive ask is acceptable — but it is a real loss, not a free one, and the write path stays open for exactly that reason.

Follow-through

• [design·P1] Capture forward conditions, not backward motives — the entry-motive question is unfixable as asked #395 — add the recency gate; correct the symmetric three-state table.
• [feat·P1] Extend candidate_rules' verifiable-condition vocabulary — 8 of 12 personas get the identical rule today #400 — unchanged; conditions are still the primary capture.
• INITIAL_THESIS_LIMIT becomes a recency threshold rather than a count cap.

[atomchung]

Cross-reference from the 2026-07-25 multilingual session — the language layer and this epic now share one load-bearing decision.

Where they meet: #396 Q3 (what answers.json stores for a generated option). Reconciliation and multilingual arrive at the same answer independently — store the structured condition, not the rendered label — because a stored label is both unreconcilable without re-parsing and locale-bound. Argument posted on #396.

Owner rulings this session, both affecting question 3 of this epic ("how we distill"):

1. User-authored text is stored verbatim and displayed verbatim, never translated, even when the review's language differs from the capture language. Low complexity is the tie-breaker.
2. Multilingual direction: single canonical English catalog, LLM translates outward, per-locale copy files become a cache rather than a prerequisite. Revised proposal on rfc(i18n): Adopt LLM-driven dynamic runtime translation with single canonical English schema #390 (my earlier recommendation to reject that RFC is withdrawn).

One finding from this epic that the language work depended on: #395's observation that why and exit_trigger are required_from_agent (review.py:1975) means there is currently no verbatim user text in durable state at all — the user clicks an enum and the agent writes the sentence. That is why ruling 1 above is written for the post-#395 world rather than for today's.