[design·M1] Snapshot-native Portfolio Risk Brief — make holdings-only cold start answer what matters now

[atomchung]

Status

Design candidate / next product module — not an active implementation front.

Current execution authority remains #27. The only active fronts are #579 (deterministic trade consequence / visible decision outcome) and #718 (QA trace and accounting truth). Do not start a competing product PR from this issue until one of those fronts reaches a safe review/merge boundary and the owner explicitly promotes this module.

This issue exists because the accumulated snapshot, market-context, continuity and copy findings now describe one missing product outcome rather than a collection of independent small defects.

User outcome

A user who supplies only a current holdings snapshot or an already-recorded current book receives one compact, route-native Portfolio Risk Brief that answers, in this order:

1. What is the most important exposure or rule tension now?
2. How much can that exposure matter in the user's own money?
3. What dated, published catalyst or standing sensitivity should the user watch next?
4. What is the nearest concrete decision check or user-owned action?
5. What would transaction history unlock, and exactly how can the user provide it?

The result is not a transaction-history Review Card with unsupported fields zeroed out. It is the first useful outcome for a holdings-only user.

Current repository truth / evidence

Verified against main@a33f31576bc5284887e0c68943f6eb251e23f2ca and the current #27 execution index.

The route currently reuses the wrong product shape

#771 shows that snapshot_adapter.py disables the transaction-review card wholesale instead of projecting the subset a snapshot supports. The route accepts or computes cash, maximum-position weight, market value, average cost and a concentration diagnosis, but the finished card withholds declared cash, money stress, distance to the position cap, point-in-time unrealized P&L and a useful per-position ranking. It also renders an empty transaction section.

This is not five unrelated omissions. The adapter asks, “which transaction-card fields must be turned off?” rather than, “what decision outcome does a holdings-only user need?”

The card skips the two steps that turn concentration into a decision

The user chain recorded on #772 is:

How concentrated am I?
→ How much can that hurt in money?
→ What would move or break this exposure / what should I watch?
→ What do I change or check next?

The current snapshot card answers the first and jumps to the last. #771 owns the missing money impact. #772 owns the missing standing / forward-looking watch.

The product's definition of risk has changed

The owner ruling on #781 is now explicit:

Current structure alone is an incomplete risk answer. Dated forward-looking catalysts are a core concern; history remains a baseline against which the agent judges whether an upcoming event is surprising or already reflected.

The division remains bounded:

• deterministic code owns dated facts and current-book facts;
• the agent may judge relevance/surprise only as labelled judgment anchored to those facts;
• forecasts, targets and event-outcome predictions remain out.

A snapshot card that reports only weights and concentration therefore cannot be described as a complete risk product.

Snapshot-only users have no continuity or conversion path

• [design] A snapshot-only book (no transaction history) never reaches weekly_review's memory-continuity check #736: a snapshot-only book can never enter weekly_review; a prior user-chosen rule may be stored but is never actively reconciled.
• [design·UX·P2] Light entry routes (test drive, snapshot) end with no stated path to real transaction data — the funnel's conversion sentence is unowned #760: test-drive and snapshot routes end without a concrete instruction for providing real transaction data.

Current labels can actively reduce trust

• [bug·copy·P1] Snapshot diversification line hard-codes “one and the same driver” over top-3 weights whose members carry no driver classification #754 can claim the top three positions are “one and the same driver” when some members have no driver classification.
• [bug·copy·P2] roughly_neutral is the no-tag fallback but its copy asserts the position is neutral — everything between deep-underwater and disciplined-hold is told it is roughly flat #779 renders the no-tag fallback as “roughly neutral,” asserting a return state that was never classified.
• [design·data·P2] The driver taxonomy has one level, so several holdings riding the same sub-driver inside one sector read as ordinary sector exposure #780 shows that one broad driver level can miss several holdings that are effectively the same sub-driver bet.

These defects matter more on snapshot cold start because the visible card has little other differentiated content to offset a wrong or vague headline.

Earlier-value copy is necessary but insufficient

#714 / PR #732 now exposes one engine finding before first-review questions. That improves the bargain of the transaction-review journey, but it does not change the holdings-only route's final outcome. A teaser before the same subtractive card cannot supply the missing money → catalyst → action chain.

Problem and consequence

The product currently treats the Review Card as the universal output and models snapshot_review as a degraded version of it.

Consequences:

1. The first-time user gives valuable current-book data and receives mostly percentages, limits and empty historical surfaces.
2. The route can truthfully diagnose concentration but cannot explain its monetary importance or what upcoming fact makes it urgent.
3. The user is asked to choose a rule before the product has completed the reasoning that would justify that rule.
4. A snapshot-only user has no natural re-entry loop; every later snapshot is another cold structural check rather than a current-risk update.
5. More copy fixes increase local correctness but do not change the perceived product value.
6. README/onboarding can promise a decision partner, while runtime still behaves like a report generator with missing sections.

Without a route-native outcome, the project will continue accumulating field, copy and gate fixes while owner-live value changes only marginally.

Decision candidate

1. Add a route-native PortfolioRiskBrief projection

Use a transient, engine-owned projection name such as PortfolioRiskBrief (exact identifier may change). It is not new canonical memory and not a generic communication framework.

The projection owns the supported content and ordering for the holdings/current-book user moment:

primary risk
→ money consequence
→ next dated catalyst / standing sensitivity
→ one decision check
→ optional continuity / transaction-history unlock

Unsupported sections are omitted. Do not render transaction-history headings with apologies or substitute generic educational prose.

2. Engine owns selection, facts and omission

Deterministic code owns at least:

• recorded-book basis and freshness;
• maximum position / concentration / driver group used as the focal risk;
• rule limit and distance/direction where applicable;
• declared cash when present;
• one bounded money-stress consequence using already-supported book facts;
• the exact holdings contributing to the selected exposure;
• dated published catalyst facts when the first approved source supports them;
• source, as_of, coverage, stable omission reason and localization-ready semantic state.

The agent does not independently rank the focal risk, calculate a loss amount, infer a driver intersection or invent a catalyst.

3. First catalyst slice stays narrow and deterministic

The first implementation candidate should support at most one deterministic catalyst class for the focal risk, preferably the next scheduled earnings date for the selected holding(s), or another single class justified by provider evidence.

• A dated published fact is enough; no outcome forecast is needed.
• Missing catalyst coverage omits the line or states one bounded limitation; it never triggers a generic news recap.
• Researched L1/L2 evidence remains blocked on the live delivered-answer gate/ruling under [process·voice·P2] A live consider answer passes through no voice check — three output-voice violations shipped in one owner-live session with a fully green trace #782.
• Reuse [research·architecture] One route-scoped market-context capability — shared observations, bounded research, no background news system #776's route-scoped market-context ownership and the deferred L0 standing-packet idea from [feat·P1] A weekly review should read the week's market against the user's own holdings — prices, turning points, not only an index delta #683/[design·P1] The market read is bound to weekly_review, so the holdings-only cold-start user — the one its gate was written for — can never receive it #772; do not create a second market-data path.

4. Give snapshot-only users a bounded re-entry

A later invocation against the already-recorded book or a newer snapshot may regenerate the brief and, when a prior rule exists, reconcile only the part that the current book can prove.

It must not pretend that a snapshot proves trade motives, averaging behavior, exits or execution history. This is a narrow current-risk continuity loop, not a snapshot-shaped weekly_review clone.

5. Make the next data step explicit

The closing surface names the concrete transaction-history action only when it would unlock a meaningful unanswered question. It must say how to provide the CSV/table in the current host, not merely that “history would help.”

6. Keep consider separate

#579 remains the owner for the proposed-trade decision outcome. This issue does not create a cross-route DecisionCommunicationPlan or reimplement rule_effect.

The two product outcomes may share deterministic facts, but they answer different user moments:

• consider: What does this proposed transaction change?
• PortfolioRiskBrief: What matters most in my current book now?

Minimum vertical slice

One snapshot/current-book route, one focal risk, one money consequence, at most one deterministic dated catalyst, one concrete next check and one explicit transaction-history unlock.

Do not begin with a dashboard, multiple cards, all catalyst types, a news feed, per-position research packets or a new persistent memory object.

User before / after

Before

Upload holdings
→ see concentration percentages and several unavailable/empty historical surfaces
→ choose a rule
→ no answer to what can hurt in money or what to watch next
→ no periodic snapshot-only continuity

After

Upload holdings / use recorded book
→ see one current-book risk
→ see its bounded money consequence
→ see the next dated fact or standing sensitivity that matters to that risk
→ take one concrete check / choose or skip one rule
→ know exactly what additional transaction data would unlock

Best-practice assessment

This is justified by an observed product-shape failure, not by architectural neatness.

It removes the negative inheritance between two user moments with different evidence:

• a transaction-history review diagnoses past behavior and may justify motive questions, preview and commitment;
• a holdings-only check diagnoses current structure and near-term exposure, and should not impersonate historical analysis.

The minimum implementation is one route-specific projection and renderer/answer contract. A universal response-plan abstraction, dashboard schema, catalyst ontology, background monitor or research database would be over-design.

Scope

• route-native snapshot/current-book decision outcome;
• supported current-book fact projection and ordering;
• reuse/fix of the facts exposed by [bug·snapshot·P1] The snapshot card withholds five facts the route already supports — the adapter zeroes every card field instead of filling the subset it can #771;
• one bounded deterministic forward catalyst or explicit omission;
• snapshot-only re-entry and bounded prior-rule reconciliation;
• concrete transaction-history unlock;
• exact delivery, timing and owner-value evidence;
• migration of the snapshot-specific findings below into one coherent acceptance journey.

Existing issue map

• current-book facts and money impact: [bug·snapshot·P1] The snapshot card withholds five facts the route already supports — the adapter zeroes every card field instead of filling the subset it can #771;
• standing / forward-looking watch: [design·P1] The market read is bound to weekly_review, so the holdings-only cold-start user — the one its gate was written for — can never receive it #772;
• product risk definition: [design·P1] What does this product mean by risk? Structure at one instant is the whole current answer, and the owner's definition includes what is about to happen to it #781;
• route-scoped market-context architecture: [research·architecture] One route-scoped market-context capability — shared observations, bounded research, no background news system #776;
• snapshot-only continuity: [design] A snapshot-only book (no transaction history) never reaches weekly_review's memory-continuity check #736;
• conversion to transaction history: [design·UX·P2] Light entry routes (test drive, snapshot) end with no stated path to real transaction data — the funnel's conversion sentence is unowned #760;
• false same-driver claim: [bug·copy·P1] Snapshot diversification line hard-codes “one and the same driver” over top-3 weights whose members carry no driver classification #754;
• unsupported neutral fallback: [bug·copy·P2] roughly_neutral is the no-tag fallback but its copy asserts the position is neutral — everything between deep-underwater and disciplined-hold is told it is roughly flat #779;
• driver granularity decision: [design·data·P2] The driver taxonomy has one level, so several holdings riding the same sub-driver inside one sector read as ordinary sector exposure #780;
• weekly delta prototype and deferred standing packet: [feat·P1] A weekly review should read the week's market against the user's own holdings — prices, turning points, not only an index delta #683;
• live delivered-answer voice gate: [process·voice·P2] A live consider answer passes through no voice check — three output-voice violations shipped in one owner-live session with a fully green trace #782.

These issues remain the evidence and implementation leaves. This issue owns the combined user outcome and prevents them from being fixed as unrelated card patches.

Non-goals

• No full investment dashboard or wealth-management surface.
• No market-wide news feed, filing warehouse, KOL crawler, scheduler, notifications or email.
• No price target, event-outcome forecast, security ranking or buy/sell recommendation.
• No full transaction-review card redesign.
• No generic DecisionCommunicationPlan framework.
• No new durable catalyst/evidence graph or profile object.
• No automatic thesis, motive, execution or rule inference from holdings alone.
• No M2 rationale/memory merge solely to make this brief look richer.

Acceptance criteria

• A finalized production-shaped snapshot_review delivers a route-native brief rather than an empty/degraded transaction-history card.
• The first visible result names one engine-selected focal risk and its current-book basis.
• The brief renders declared cash, maximum-position/rule distance and one money-stress consequence when their inputs are supported; unsupported facts are omitted with a stable reason.
• No transaction-history-only section or behavior claim appears on the snapshot route.
• A same-driver statement is emitted only when the contributing holdings actually satisfy the declared classification contract.
• The no-tag fallback never asserts a neutral return.
• At most one dated catalyst class is supported in the first slice; it carries source and date and makes no prediction.
• The agent's relevance/surprise statement is labelled judgment and anchored to engine facts; deterministic/voice gates reject process leakage and unsupported claims.
• A later snapshot/current-book invocation can surface and reconcile a prior user-chosen rule only where current-book facts prove it, without requiring transaction history.
• The closing instruction tells the user exactly how to supply transaction history when it would unlock a named unanswered question.
• Public fixtures and receipts use only fictional/generic holdings and events.
• Full Python 3.11/3.12 offline suite, focused mutation evidence and merge-tree CI pass.
• Owner-live acceptance: from the first surface, the owner can answer “what matters, how much, what should I watch and what do I do next?” without reading metadata or asking a rescue question.
• Timing evidence under [design·perf] Response-time budget by route — separate real-user latency from QA/test overhead #603 records snapshot accepted → first brief visible and total route time.
• Same-fixture comparison against current snapshot_review shows fewer empty/limitation beats and materially higher owner-rated decision value.

Dependencies / sequencing

1. [design·M1] Decision-first TradeEvaluation answer — one supported judgment, not a disclosure dump #579 and [qa] Add an LLM-driven synthetic FOMO QA walkthrough #718 reach a safe review/merge boundary under tracking: current context index — milestone, critical path, what an agent may pick up #27.
2. The owner promotes this issue as the single next product module; do not activate all leaves independently.
3. Resolve the narrow deterministic catalyst source/semantics under [research·architecture] One route-scoped market-context capability — shared observations, bounded research, no background news system #776 and respect [feat·P1] A weekly review should read the week's market against the user's own holdings — prices, turning points, not only an index delta #683's owner-live disposition unless explicitly superseded.
4. Land or rule the delivered-answer gate under [process·voice·P2] A live consider answer passes through no voice check — three output-voice violations shipped in one owner-live session with a fully green trace #782 before any researched L1/L2 prose enters the route.
5. Implement one vertical slice and stop for owner-live acceptance before expanding catalyst types, per-position packets or persistence.

Privacy boundary

The brief is local-first and may contain sensitive holdings-derived facts. Real holdings, amounts, tickers, rules, catalysts selected for a real book and delivered answers remain local.

Public issues, tests, PRs, QA receipts and external model calls use only fictional, synthetic, generic or de-identified evidence. No private investment-note content is read or copied.

Rollout / compatibility / recovery

Prefer a transient projection over new canonical state. Existing snapshot sessions and recorded books remain readable. Legacy sessions without the projection may render through the current compatibility path; no historical session is rewritten.

A failed catalyst lookup omits only the dependent line and leaves the current-book brief usable. A failed brief render must not mutate the book, rule or session. Removing the module later requires no canonical-state migration.

Stop condition

Stop after one snapshot/current-book vertical slice proves that a holdings-only user receives differentiated decision value in the first interaction. Do not automatically continue into a dashboard, full research capability, M2 memory, multiple catalyst types or a background monitor.

[atomchung]

Sequencing update after main@528d955

The two dependencies named in this issue have reached a safe merge boundary:

• [design·M1] Decision-first TradeEvaluation answer — one supported judgment, not a disclosure dump #579 deterministic rule-effect implementation merged through PR fix(consider): a trade that reduces an over-cap position is no longer delivered as a breach (refs #579, refs #674, refs #676) #791;
• [qa] Add an LLM-driven synthetic FOMO QA walkthrough #718's first honest trace/accounting slice merged through PR feat(qa): keep a failed multi-turn walk in the trace and in the denominator (refs #718) #785.

This does not yet promote the full Portfolio Risk Brief design into implementation. One nearer leaf remains: #771's adapter half merged through PR #788, but the renderer still discards the supplied cash, stress, per-position ranking and related current-book facts. A branch exists (claude/issue-771-snapshot-card-fields), with no PR open yet.

Updated evidence-first gate

1. Finish [bug·snapshot·P1] The snapshot card withholds five facts the route already supports — the adapter zeroes every card field instead of filling the subset it can #771 renderer only; no catalyst or continuity expansion.
2. Run one same-fixture owner comparison on the delivered snapshot surface.
3. Promote this issue only if the owner still cannot answer the four intended questions after the already-computed facts become visible:
   • what matters;
   • how much;
   • what should I watch;
   • what do I do next.

If “what matters / how much” are solved by #771 and only the forward watch remains missing, narrow the first #783 slice to the smallest standing/catalyst connection rather than rebuilding the whole snapshot result. If the current card shape still obscures the decision despite the facts being present, retain the route-native brief projection as written.

This keeps the architecture change tied to an observed residual failure rather than assuming the pre-#788 experience survives unchanged.