Financial Research

Financial Research Skill v0.33

Every report must embed the disclaimer from assets/disclaimer.md verbatim (front and back). v0.3 = risk-aware consensus, confidence-penalised quality, central-bank-anchored macro appendix, conservative-by-design. v0.31 adds the coherence overlay (macro factors + sector logic + ETF divergence) — demotion-only, capped at one tier, never touches rank or the composite. v0.32 is a defect patch: currency becomes a required Stage 1a field and only USD-reporting funds enter the days-to-liquidate aggregate (excluded, never FX-converted), plus two input-review warnings (thin US exposure, Stage 0 regional advisory). v0.33 adds the Important Notice — a per-stock section on the two factors the framework structurally cannot measure (the expectations bar and the sentiment cycle), evidenced at sector level and attributed per stock. It sits outside every scoring layer: no score, no rank, no tier. Safety-first: when in doubt, say less and rank lower.

Pipeline orchestration

Stage 2c (multi-source resolution): Runs implicitly inside Stage 2b. For each ticker EDGAR and yfinance are consulted; overlapping fields are merged via providers/resolver.py (first source wins on agreement; higher-confidence wins on disagreement, confidence halved when diff > 20%). Conflicts → data_provenance.json.

Stage 0 email gate (B1): SEC requires a contact email in the EDGAR User-Agent; without it EDGAR returns 403. In-conversation, ask the user for a usable email and tell them why (403 without it) and the privacy position (placed ONLY in the SEC request header; not stored or sent anywhere else). Pass it via --email to validate_uploads.py and fetch_fundamentals.py (or set EDGAR_CONTACT_EMAIL). No valid email → halt.

Stage 1a required fields (v0.32 G1.1): fund_name, asof, the holdings table and currency — the fund's reporting currency for total_aum, normalised to an ISO-4217 code (USD, HKD, EUR, JPY, …). If the factsheet does not state one, write currency: null — do not guess and never default to USD. A bare $ or ¥ is ambiguous and counts as unstated. Only USD-reporting funds enter the days-to-liquidate aggregate; the rest are excluded (never FX-converted) and fall through the existing NAV-only path.

Stage 0 regional advisory (v0.32 G3): a title matching a regional marker (Asia / Europe / Japan / China / EM / Latin America / India / ASEAN, plus bilingual equivalents) raises an advisory only. It never halts, never rejects, never enters errors, and never changes the exit code or the 7–11 file-count logic — Stage 1c remains the sole authority on rejection. Relay it to the user so they can swap the upload before the expensive Stage 1a parse.

Stage 1a fund-style inference (A3 / Appendix 3): infer a coarse style per fund — one or more of {value, growth, blend, income_dividend, sector_specific, small_mid_cap, region_tilt_non_us} — from name keywords, stated benchmark, and top-holdings profile. Persist on each fund record. Build it once; it feeds both A3 and Appendix 3. See references/macro_appendix.md.

Stages M1–M3 (macro subsystem): primary-first directed-fetch, cross-source corroboration hard gate (≥2 primary-tier sources per fact), per-sentence attribution. v0.31: M1 runs after 2d (was after 3a) and is scoped to the post-screen universe's industries — tiering depends on macro, so macro must exist before ranking; the top-15 anchor would be circular. M1's internal logic, sources and the C2 gate are unchanged — only its position moved. Full spec: references/macro_appendix.md. These stages add web retrieval and token load — the .md checkpoints let a long run survive context pressure.

Stage H1 (v0.33 Important Notice): a per-stock section on the two factors the framework structurally cannot measure — the expectations bar (the quality axis is entirely backward-looking, so a name that has beaten for eight quarters and one nobody expects anything from score identically on Q) and the sentiment cycle (no regime detection exists, by design). It sits outside every layer: it enters no score, no rank and no tier, and removing it leaves the report's numbers bit-for-bit identical. Evidence is retrieved and corroborated at sector/theme level and narrated by attributing the stock to its group — a single-stock sentiment assertion is the highest-fabrication-risk sentence this skill could write, and the C2 two-source hard gate is never relaxed here. Written constructively, not defensively: it is not a second disclaimer. Full spec: references/important_notice.md.

Stage 3a-bis (v0.31 coherence overlay): asks whether the macro read, the sector operating logic and the sector-relative price action tell the same story. A contradiction in any pair demotes the stock exactly one display tier and must be named on its card. Demotion-only, one tier maximum, rankings.json read-only, and deleting the stage returns the v0.3 report. Missing data → "insufficient data", tier unchanged. Full spec: references/coherence_overlay.md.

Error decision tree

Output contract

/home/claude/work/                 (EPHEMERAL — resets between sessions)
  layer1_extraction.md  layer2_screening.md  layer3_ranked_advice.md
  macro_checkpoint.md   expectations_checkpoint.md  appendix3_consensus_warning.md
  important_notice_checkpoint.md                                                      (v0.33)
  holdings.json  overlap.json  fundamentals.json  unscored_tickers.json
  data_provenance.json  screen_results.json  scores_per_stock.json
  crowding_signals.json  rankings.json
  macro_factors.json  sector_logic.json  etf_relative_strength.json  coherence.json   (v0.31)
  stage0_validation.json                                                              (v0.32)

/mnt/user-data/outputs/            (USER-VISIBLE — downloadable)
  financial_research_report.pdf
  <all checkpoint .md files + coherence.json, copied by build_report.py — D5>

The closing chat message points the user to /mnt/user-data/outputs for the PDF and the checkpoint .md files; it must NOT claim the work dir persists.

Key constraints (non-negotiable)

• US-listed equities only. ADRs in scope. Non-US primary listings dropped at Stage 1b.
• English-only in all output files. Chat may be bilingual.
• One ranking (top 15), three display tiers. No parallel strategies. No backtest.
• The coherence overlay may only DEMOTE, by at most one tier per stock, no matter how many pairs contradict. It never promotes, never changes rank, never touches the composite, Q'' or C. rankings.json is read-only to it; its only output is coherence.json. Removing Stage 3a-bis must leave a runnable pipeline producing the v0.3 report.
• The overlay is not a third scoring axis. Weights stay 50/50; a macro weight cannot be calibrated (no backtest exists), so none is written.
• ETF checks are divergence detection, never confirmation: relative strength vs SPY over fixed 3M/6M/12M windows. Divergence yields a flag plus a required explanation, not an automatic penalty.
• Sector logic uses the three universal questions (inputs / pricing power / return on capital), instantiated per industry — never blank-filled physical-supply-chain fields on software, financial or consumer names.
• No industry-policy or company-level supply-chain claims anywhere in the output (deferred; company supplier relationships are not in EDGAR's structured data and are the highest fabrication risk in the proposal).
• Do not fabricate data. If EDGAR and yfinance both fail, mark unscored.
• Composite weights fixed at 50/50. Quality half is low-anchor shrunk: Q'' = c·Q + (1−c)·Q_low, Q_low = 10 and must stay > 0; applied to Q only, never re-percentiled.
• Crowding = exit-crowdedness (days-to-liquidate, simultaneous-exit assumption); each figure labelled liquidity-inclusive / NAV-only.
• currency is required at Stage 1a and never defaulted. Only currency == "USD" funds contribute AUM to aggregate_position_usd; non-USD and null are excluded, never converted. No FX conversion may exist anywhere in the codebase — the units are either identical or the input is set aside and labelled. There is no third path.
• Thin US exposure (20–35% of AUM) is a warning, never a re-weighting. Such funds are accepted in full and their consensus contribution is unchanged — C's definition is locked, and exposure-weighting it belongs to a signal iteration, not a defect patch. Viability thresholds (≥5 holdings, ≥20% weight) are unchanged.
• Stage 0 regional advisories are non-blocking: never in errors, never affecting ok, the exit code, or the file-count logic.
• The Important Notice changes nothing it is placed after. It never enters Q'', C, the composite, rankings.json or coherence.json, and is not a fourth coherence input. Deleting important_notice_checkpoint.md must leave every rank, tier and score bit-for-bit identical.
• Notice evidence is sector-level; notice wording must not exceed it. Corroborate at sector/theme level, narrate by attributing the stock to its group. No stock-level sentiment or valuation assertion anywhere — "this group is in an elevated-expectations environment", never "this stock is overpriced". The defect in the second is not that it resembles advice, it is that it exceeds the granularity of the evidence.
• The C2 hard gate is never relaxed for the notice. ≥2 primary-tier sources per claim, or an explicit statement that no corroborating evidence was found. Admitting single-source claims here would make it the one low-standard region in the report — and the one most easily fabricated.
• The notice is written constructively, not defensively. It is not a second disclaimer; the standing verbatim disclaimer already covers that. Its argument — Tier A means highest-ranked on the measurable dimensions, and precisely for that reason such a name is more likely already fully priced — is stated ONCE at the section head, not per stock (same discipline as the HK-bias note).
• Presenting sentiment evidence does not create a regime detector. The notice must say plainly that the tool still has none.
• No new retrieval scope for v0.33. M1's existing post-screen sector scope gains a facet; per-stock retrieval is out of scope.
• Consensus is style-diversity-weighted; stratified sampling is abandoned (sample too small; token budget) — disclose both reasons.
• Macro/expectations facts: ≥2 primary-tier sources (HARD gate), per-sentence attribution, no blacklist.
• Stage 3b: cards in 3 batches of 5, never all 15 at once.
• HK-bias note stated ONCE in the framing section — NOT on every card. High-crowding cards keep their per-card warning; front/back disclaimer intact.
• A valid SEC contact email is required before any EDGAR fetch (B1).
• Copyright: paraphrase fetched content, never reproduce; per-sentence attribution in the macro appendices.

See references/ for methodology, crowding signal (incl. the v0.32 currency gate), providers, quality screen, honest framing, the macro/expectations appendices, the v0.31 coherence overlay, and the v0.33 important notice. No formulas live in this file.