Understand the Book

What this chapter does

The sharpest chapter in the loop. A user can read a regime brief anywhere; only Jawz tells them what their regime brief means for their actual positions, with live data, composed into attribution.

The goal is not to tell the user what to do — the goal is to make visible what's true about their portfolio that they probably can't see from a brokerage dashboard. Concentration they didn't realize. Factor tilts they've drifted into. Vulnerabilities that the current world state creates.

Every mode in this chapter produces questions, not instructions. The user decides what to do with the attribution.

Shared preamble — priced book

Before any mode runs, execute this common preamble:

1. Load the user's portfolio (from context, jawz_portfolio.json, or explicit list).
2. Call get_prices for all positions. Convert to common currency (USD). Compute weights.
3. Handle failures explicitly:
   • Known misresolutions — prompt user for manual USD value or exclude with flag.
   • International tickers failing — flag, exclude, list in output.
   • Never compute portfolio-level metrics on a partial book without disclosing coverage.
4. Cache the priced book for the session so subsequent modes don't re-fetch.

Mode 2.1 — Regime Fit

When to use: User asks about portfolio regime fit, risk, vulnerability, "how is my book positioned for the current environment." Also called after Chapter 1 Mode 1.1 when the user wants to go from world-state to book-state.

Prerequisites:

• Priced book (from shared preamble)
• Regime read (from Chapter 1 Mode 1.1)

Procedure:

Step 1 — Classify each position on three axes:

Classification discipline — read before you tag anything. Two failure modes, both seen in practice:

• Holdings-up, regime-last. Derive a position's factor (Axis B) from what it actually is — its business and earnings driver; for a fund, its underlying holdings — before you consult the regime. The regime-fit score (Step 2) is computed after the factor is set and must never feed back into it. Choosing the tag that makes a position look good under the current regime is motivated reasoning, not analysis — and it is invisible now and ruinous later: two factors can score identically in today's quadrant and diverge sharply in the one you are trying to hedge. (commodities-broad and equities-cyclical both score well in an inflationary boom, then split hard in stagflation — the commodity holds as an inflation hedge, the capex-cyclical gets its backlog cut.)
• Identity first. Resolve what the instrument is before classifying it. For an ETF, look through to its holdings (Mode 2.2 / get_etf_profile) — a "wire" or "infrastructure" fund of switchgear, cable, and grid-services names is equities-cyclical capital-goods, not commodities-broad, even though it touches copper as a pass-through input. For tickers known to collide on resolution (e.g. WIRE, AIPO resolve to look-alike crypto coins unless qualified NYSE:WIRE / NASDAQ:AIPO), confirm the security before tagging — a mis-resolved instrument yields a confidently-wrong factor.

Axis A — Regime Sensitivity:

Classify each holding as Helped, Hurt, or Neutral.

Axis B — Factor Exposure: the position's primary factor, in the canonical vocabulary below. These are the exact values score_position_drift and get_drift_alerts accept — classify in these terms and there is no translation between classification and scoring.

A theme (electrification, AI-infrastructure) is not a factor — it spans factors and can't be scored against a regime quadrant. Carry it as a secondary overlay (below), never as the primary tag. Speculative is a role (Axis C, small size) and/or crypto-speculative — not a standalone factor.

Crypto tokens and crypto-beta. crypto-beta is reserved for direct token exposure — the coins themselves (BTC, ETH, SOL) and spot crypto ETPs that hold coins. The framework does not yet resolve tokens into sub-factors, so all token positions take crypto-beta. In Step 4, do not score crypto-beta against the regime as a resolved factor. Report it explicitly as unresolved: state its weight, and state that the framework cannot yet differentiate these positions or assess them against the regime. Do not imply the positions behave alike; do not imply they are diversified. Scope the factor verdict to the non-crypto sleeve. This is a known resolution gap tracked for future work — not a risk judgment about crypto.

Crypto-related operating equities are NOT crypto-beta. Listed companies whose business is levered to crypto — miners, exchanges, treasury-holders, blockchain firms (e.g. DAVV.DE, COIN, MARA, MSTR) — are equities, not tokens. They carry equity beta, idiosyncratic business risk, dilution, financing, and can fail independent of crypto. Classify each by its dominant equity factor as the business stands today — most are equities-growth (high-beta, rate-sensitive, risk-on), some equities-cyclical. Record the crypto-price correlation as a secondary overlay in the factor-tilt commentary, never as the primary factor. The overlay is not permanent: a Bitcoin miner reallocating capacity to AI/HPC compute re-rates — its dominant factor stays equities-growth while the overlay shifts from crypto-correlation toward an AI-infrastructure theme. When the dominant factor or the overlay has shifted since entry, that is a thesis-Evolved signal — surface it for Chapter 4 Mode 4.3 (Thesis Status Sweep) and a Mode 2.4 conviction re-check. Unlike crypto-beta, these names are scored against the regime as the equities they are, and priced as stocks.

Secondary overlays (general). The crypto-correlation pattern above is one case of a general rule: a position can have a dominant factor (its primary regime-fit driver) and a named secondary overlay worth tracking separately — a secular theme, an input-price correlation, a policy tailwind. Tag and score the dominant factor; record the overlay in the factor-tilt commentary, never as the primary. Example: an electrification / grid-capex ETF is equities-cyclical (earnings move with the capex cycle) carrying a secular electrification overlay — score it equities-cyclical, and watch the overlay; a secular theme that strengthens enough to start overriding the cyclicality is a thesis-Evolved signal for Mode 4.3. An overlay never silently changes the score — it changes what you monitor.

Hybrid holdings (split exposure). Some positions are genuinely two factors at once — e.g. a fund that is ~half AI-semiconductors (equities-growth) and ~half power-infrastructure (equities-cyclical). Tag the primary by dominant weight and name the secondary explicitly. When the split is near 50/50, say so plainly: the single-factor model under-describes the position. For the Step 2 score, score each sleeve against the regime separately and weight-blend, rather than forcing one tag to carry the whole position. A native weighted multi-factor tag is future work (schema backlog) — until then, dominant-primary + named-secondary + an honest "hybrid" note is the discipline, never a silent single tag.

Axis C — Role in Portfolio:

• core (>10% weight), satellite (3–10%), speculative (<3%), hedge, cash-buffer

Step 2 — Assign regime fit score 1–5:

• 5 — Regime Champion: Helped + factor matches regime's favored factors + appropriate size
• 4 — Regime Aligned: Helped or Neutral + consistent factor + reasonable size
• 3 — Regime Neutral: Neutral OR (Helped but oversized) OR (Hurt but small)
• 2 — Regime Mismatch: Hurt + fights regime + oversized for the headwind
• 1 — Regime Liability: Strongly Hurt + actively fights the regime's dominant risk factor + concentrated

If borderline, round to the more cautious score.

Step 3 — Compute portfolio fit score (weighted average across priced positions).

Interpretation bands:

• 4.0–5.0: Strongly aligned
• 3.5–4.0: Aligned with some drag
• 3.0–3.5: Neutral
• 2.5–3.0: Meaningful mismatch
• <2.5: Significant mismatch — portfolio is fighting the macro

Step 4 — Aggregate factor tilts. Group positions by Axis B, sum weights. Report top tilts with verdicts against current regime.

Step 5 — Generate questions. 3–5 portfolio-specific questions. Each must:

• Reference specific holdings by name/ticker
• Connect to a factor tilt or vulnerability from Step 4
• Be answerable (yes/no/maybe)
• Avoid generic risk platitudes

Output contract:

## Portfolio Regime Fit — [DATE]

**Regime:** [COLOR] — [signal]
**Portfolio Fit Score:** [X.X / 5.0] — [band]
**Coverage:** [X% priced and scored]

### Regime Champions (Score 4-5)
| Position | Weight | Score | Factor | Why it fits |
|---|---|---|---|---|

### Regime Liabilities (Score 1-2)
| Position | Weight | Score | Factor | Specific risk |
|---|---|---|---|---|

### Middle of the Book (Score 3)
[Prose summary — weight in this band, dominant factor]

### Factor Tilts
| Factor | Weight | Verdict |
|---|---|---|

### Questions to Sit With
1. [Portfolio-specific question referencing a specific holding]
2. [Portfolio-specific question referencing a specific holding]
3. [Portfolio-specific question referencing a specific holding]

### Positions Not Scored
[Excluded + reason]

Mode 2.2 — Concentration Check

When to use: User asks about diversification, concentration, overlap, "am I too exposed to X," or "what do I actually own."

What this mode does that Mode 2.1 does not: Mode 2.1 aggregates the book by factor. Mode 2.2 looks through ETFs to the underlying names — surfacing single-name exposure the user carries without seeing it, because it is buried inside funds. A user can hold NVDA directly, inside QQQ, and inside VGT: three line items on the dashboard, one concentrated bet in reality.

Prerequisites:

• Priced book (from shared preamble) — direct positions and ETF positions, each with a book weight.

Procedure:

Step 1 — Separate the book. Split holdings into (a) direct single-name positions (individual stocks, crypto) and (b) ETFs and funds.

Step 2 — Look through the ETFs. Call get_etf_profile with every ETF ticker in the book. For each returned profile note:

• source: live (fresh from the issuer) or catalog (a dated snapshot — note its as_of).
• top_holdings: the fund's largest positions, each with a weight (percent of the fund).
• unknown_tickers: ETFs the catalog could not resolve — these cannot be looked through.
• Bond and commodity ETFs return no holdings — they carry no single-name overlap. Treat them as factor exposure only and exclude them from the name-level math.

Step 3 — Compute true single-name exposure. For each underlying name, sum:

• its direct weight in the book (zero if not held directly), plus
• for every ETF that holds it: the ETF's weight in the book multiplied by the name's weight inside that ETF.

Worked example: 8 percent of the book sits in QQQ, and NVDA is 9 percent of QQQ — that contributes 0.72 percent of NVDA exposure. Add that to any direct NVDA position, and to NVDA's contribution from every other fund in the book.

Step 4 — Flag concentration. Surface any name whose true exposure is materially larger than its visible (direct-only) exposure, or whose true exposure crosses a concentration line. Useful default thresholds: any single name above 10 percent of the book, or any name whose hidden ETF-derived exposure exceeds its direct exposure. The hidden cases are the core finding — they are what the user cannot see from a brokerage dashboard.

Step 5 — State coverage honestly. Look-through produces a floor, not an exact figure:

• get_etf_profile returns each ETF's top holdings only — a name outside a fund's top holdings is not counted.
• catalog-sourced profiles are dated snapshots; weights drift after the as_of date.
• unknown_tickers are not looked through at all — report their combined book weight as un-resolved. Never present a true-exposure number as precise. Always state what share of the book was and was not looked through.

Step 6 — Generate questions. 3–5 portfolio-specific questions. Each must name a specific concentrated holding and connect to the gap between visible and true exposure. Questions, not instructions — you never say "trim NVDA."

Output contract:

## Concentration Check — [DATE]

**Look-through coverage:** [X% of book looked through] — [N ETFs live, M ETFs from catalog, K un-resolved]

### True Single-Name Exposure
| Name | Direct | Via ETFs | True total | Flag |
|---|---|---|---|---|
[One row per name with material true exposure. "Via ETFs" names the contributing funds.]

### Hidden Concentration
[Names whose true exposure materially exceeds the direct-only weight a brokerage dashboard shows — the core finding of this mode. If none, say so plainly.]

### Not Looked Through
[Un-resolved ETF tickers + combined weight + reason. Bond/commodity ETFs listed here as factor-only, not a coverage failure.]

### Questions to Sit With
1. [Question naming a specific concentrated holding]
2. [Question naming a specific concentrated holding]
3. [Question naming a specific concentrated holding]

Scope note (v1): This mode resolves single-name concentration. Sector- and theme-level concentration across the whole book is not computed here yet — Mode 2.1's factor-tilt aggregation is the current proxy for that. Sector look-through is planned.

Mode 2.3 — Stress Test

When to use: "What if the market crashes," "how would my book handle a 2022-style rates shock," "how bad could a drawdown be," "where's my hidden risk if X happens." Also the natural follow-on when Mode 2.1 surfaces a heavy factor tilt worth pressure-testing.

Prerequisites:

• Priced book (from shared preamble).
• Factor classifications (Mode 2.1, Axis B) — reuse; if 2.1 hasn't run, run its Step 1 classification first.
• Regime + dominant risk factor (Chapter 1 Mode 1.1) — to rank which scenarios are most live now.
• get_financial_conditions — credit spreads, VIX, liquidity show how much fragility is already in the tape.

Procedure:

Step 1 — Choose scenarios. Use the user's if given. Otherwise three defaults: a rates shock (2022-style, real yields spike), a liquidity/risk-off crisis (2020-style, funding stress), and a credit event (2008-style, spreads blow out). Rank by today's dominant_risk_factor — lead with the most live one and say why.

Step 2 — Get transmission per scenario. For each, run Chapter 1 Mode 1.3 (Shock Scenario) for primary transmission channels and historical base-rate asset-class responses. Anchor magnitudes to those analogues — do not invent drawdown numbers.

Step 3 — Map the book onto each scenario. Using Mode 2.1 factor tags, apply each scenario's per-asset-class historical move to each position, weight by book weight, sum to a portfolio drawdown range (a range, never a point estimate). Treat the crypto-beta sleeve as one high-beta risk-on cluster (per Mode 2.1's resolution gap) — in risk-off/credit scenarios it draws down with high-beta equity or worse.

Step 4 — Name the loss drivers. Per scenario, the 3–5 positions contributing most to the projected loss (where size × sensitivity concentrates).

Step 5 — Find the correlated cluster. The core finding. Positions that all transmit through the same channel — a book that looks diversified across line items but is one bet under a given shock (long-duration growth + crypto + unprofitable tech = one rates/liquidity bet). Crises compress correlations toward 1; ignoring this understates the loss.

Step 6 — Name the cushions. What actually offsets in each scenario (cash, gold, short-duration; long-duration treasuries help in risk-off but not in a rates shock) — and how much of the book truly cushions vs. just sounds defensive.

Step 7 — Generate questions. 3–5, each naming specific holdings and a scenario. Questions, not instructions.

Output contract:

## Stress Test — [DATE]

**Book coverage:** [X% priced and mapped]
**Most-live scenario now:** [which, given the dominant risk factor]

### Scenario 1 — [name]  (lead if most live)
**Transmission:** [primary channels, from Mode 1.3]
**Projected portfolio drawdown:** [−X% to −Y%] — base-rate range, not a forecast
**Top loss drivers:** [position — approx contribution]
**Correlated cluster:** [positions sharing the channel — the hidden single bet]
**Cushions:** [what actually offsets, and roughly how much]

### Scenario 2 — [name]
[same structure]

### Scenario 3 — [name]
[same structure]

### Cross-scenario read
[Positions fragile across all three — universal-risk names. Cushions that hold in some scenarios but not others.]

### Questions to Sit With
1. [Question naming a specific holding + scenario]
2. …

### Coverage & method
[Share of book mapped; exclusions; plain statement of method limits — see scope note.]

Scope note (v1): Base-rate scenario analysis, not a quant risk model. No covariance matrix, factor model, or Monte Carlo — drawdown ranges are directional, anchored to historical analogues (via Mode 1.3) applied to the book's factor mix. Two known limits: correlations spike toward 1 in real crises (Step 5 is the partial correction), and crypto-beta is one undifferentiated cluster. Position-level historical betas and a correlation engine are future work.

Mode 2.4 — Position Conviction Audit

When to use: "Are my positions still right," "walk me through my book," "which positions should I reconsider." Also the natural backfill when Chapter 4 modes hit thin memory — this is how undocumented holdings get a thesis on record.

Prerequisites:

• Priced book (from shared preamble) — to rank positions by weight.
• Optional: Mode 2.1 fit scores / Mode 2.3 loss drivers — if available, start the walk with the positions those flagged.

Procedure:

Step 1 — Order the walk. Rank positions by book weight; walk the top holdings first. If Mode 2.1 flagged regime liabilities or Mode 2.3 named loss drivers, surface those first regardless of size — a low-conviction position you are also overweight or fragile in is the priority.

Step 2 — Three questions per position. For each, ask the three a conviction-holder can answer:

1. Thesis: What's the reason for holding this today — not the reason you bought it?
2. Exit condition: What specific development would make you sell?
3. Invalidation: What would prove the thesis wrong?

Step 3 — Classify conviction. Per position:

• Articulated — answers all three with specifics.
• Partial — has a thesis but no exit or no invalidation (holding without a sell discipline).
• Hollow — can't state a current thesis. This is the signal — held on inertia, sunk cost, or vibes.

Do not coach the user into an answer. If they can't answer, that is the finding — record it plainly.

Step 4 — Offer a Decision Record per position. The three answers ARE the Chapter 3 Decision Record core block (thesis / what confirms / what breaks). Offer to emit one for each position walked — especially previously-undocumented names. This is how the audit backfills the breadcrumbs Chapter 4 depends on. Jawz does not store these; the user's AI saves them.

Step 5 — Route the gaps. For Hollow and Partial positions, name the natural next step — a Chapter 3 Mode 3.3 (Hold / Trim / Exit) walkthrough. Never prescribe the action; route to the framework that structures it.

Output contract:

## Position Conviction Audit — [DATE]

**Walked:** [N positions, X% of book]

### Conviction Map
| Position | Weight | Thesis | Exit defined? | Invalidation defined? | Conviction |
|---|---|---|---|---|---|
[One row per position. Conviction = Articulated / Partial / Hollow.]

### Conviction Gaps
[The Hollow and Partial positions — the core finding. For each: what's missing, and its weight. A hollow position you are overweight in is the sharpest line.]

### Decision Records offered
[Which positions the user can now put on record — especially previously-undocumented names.]

### Questions to Sit With
1. [Question naming a Hollow position — would the user open it today, at this size, with no thesis?]
2. …

### Routing
[Positions worth a Ch3 Mode 3.3 Hold / Trim / Exit walkthrough.]

Relationship to other modes: 2.4 audits conviction qualitatively, in the user's own words — distinct from Mode 2.1 (regime fit, scored) and Ch4 Mode 4.2 (single-position retrospective with price history). It is the book-wide conviction sweep and the primary on-ramp for getting undocumented holdings into the Decision Record system.

Source: The Jawz Loop, by Mako · Chapter 2 v0.3.0.