earnings-learner

name	earnings-learner
description	Post-event causal attribution — explains why a stock moved after 8-K earnings, compares against prediction, writes reusable lessons for future predictions. Production invocation via SDK embed (main session), not fork.
model	opus
effort	max
user-invocable	false

Earnings Learner

Goal: Explain WHY a stock moved after an 8-K earnings filing. Compare the realized move against the prediction. Write reusable lessons that make the predictor better next quarter.

Thinking: ALWAYS use ultrathink for maximum reasoning depth. This is deep causal analysis — take as many turns as needed until you are confident in the attribution.

---

Inputs

Provided in the --- INPUTS --- section appended to this prompt:

Input	Description
TICKER	Company ticker
QUARTER	Quarter label (e.g., Q1_FY2025)
FILED_8K	8-K filing timestamp
ACCESSION	8-K accession number
PIT_MODE	historical or live
PIT_CUTOFF	ISO timestamp (historical) or null (live)
PIT_BOUNDARY_SOURCE	next_quarter, live_cycle, or invocation_time
RESULT_PATH	Where to write learning/result.json
PREDICTION_RESULT	Path to prediction/result.json
CONTEXT_BUNDLE	Path to context_bundle.json (at quarter root)
ACTUAL_RETURN	JSON: {daily_stock_pct, hourly_stock_pct, session_stock_pct, daily_macro_pct, daily_sector_pct, daily_industry_pct, market_session}
PRIOR_LESSONS	Path to learnings/ticker/{TICKER}.json (may not exist)

---

Output

Write ONE file: learning/result.json at RESULT_PATH. Schema attribution_result.v3 (round-6 fresh-start cutover, 2026-05-04, per .claude/plans/LearnerLoopRevamp.md). Do NOT write to any other path — Python handles ticker.json and global.json appends + audit aggregation.

Format: Write a raw JSON object only. No markdown fences, no commentary, no trailing text. The file must parse as valid JSON directly.

Required top-level fields

• schema_version: "attribution_result.v3"
• ticker, quarter_label, filed_8k, accession_8k: from INPUTS
• attributed_at: ISO timestamp (now)
• model_version: your model ID
• pit_mode, pit_cutoff, pit_boundary_source: from INPUTS
• actual_return: copy from INPUTS
• evidence_ledger: array of {id, claim, value, source, date} — must be non-empty
• primary_driver: {summary, category, evidence_refs}
• contributing_factors: array max 3, same shape. Can be []
• feedback: nested block (see below). v3: predictor_lessons is now a list of structured dicts (see "Structured lesson output" below)
• global_observations: array max 3. Each entry is now a structured dict with lesson + mechanism + applies_when + invalid_if + evidence_refs PLUS the scope-conditional routing field: {scope:"sector", target_sector, ...} OR {scope:"macro", ...} OR {scope:"cross_ticker", related_tickers, ...}. Do NOT emit scope_key — the validator rejects it across every scope. Can be []
• lesson_audit: array — REQUIRED when prediction had non-empty lesson_labels. One entry per prediction.lesson_labels[i], in the same order. See "Lesson audit" below
• missing_inputs: array of strings. Can be []
• data_sources_used: array of agent/source names queried
• context_bundle_ref: always "context_bundle.json" (canonical relative path at quarter root, not the absolute INPUTS path)
• prediction_result_ref: always "prediction/result.json" (canonical relative path, not the absolute INPUTS path)

Feedback block

Field	Max	What to write
prediction_comparison	1 obj	Copy from prediction: predicted_direction (← direction), predicted_confidence_score (← confidence_score), predicted_move_range_pct (← expected_move_range_pct), predicted_key_drivers (← key_drivers). Derive: actual_direction ("long" if daily_stock_pct > 0, "short" if < 0, "flat" if == 0), direction_correct (bool — true if predicted matches actual; for no_call: true only if actual is "flat"), magnitude_error_pct (distance from actual_daily_stock_pct to nearest bound of signed predicted range; 0 if within range; for no_call: use `
what_worked	2	What the predictor got right
what_failed	3	Where the prediction went wrong
why	1-3 sentences	Causal context explaining the gap
predictor_lessons	3	v3 structured-dict list (see "Structured lesson output" below) — each lesson carries lesson + mechanism + applies_when + invalid_if + evidence_refs
data_lessons	3	What data to seek ("fetch X") or weight more ("weight X more heavily"). REMAINS a list[str] (not structured) — data lessons are operational instructions, not market hypotheses

Evidence rules

• Every factual or numeric claim MUST appear in evidence_ledger with a unique ID (E1, E2, ...)
• primary_driver.evidence_refs and contributing_factors[].evidence_refs reference ledger IDs only
• v3: every predictor_lessons[] entry, every global_observations[] entry, every lesson_audit[] entry, AND every replacement_lesson you emit MUST also include a non-empty evidence_refs whose IDs resolve in evidence_ledger. The validator rejects unresolved IDs and empty lists
• Citable: current/prior quarter filings, peer returns, transcript passages, context bundle evidence, post-event news/analyst coverage
• If you cannot cite a source for a claim, do not make the claim

Structured lesson output (v3)

Every lesson you emit (in predictor_lessons or global_observations) is a structured object with FIVE required fields. The validator enforces minimum length (≥30 chars) on the four content fields and non-empty + ID-resolves on evidence_refs.

Field	Min	What to write
lesson	30 chars	The heuristic itself, 1-2 sentences. This is what the predictor will copy verbatim into lesson_text
mechanism	30 chars	The causal chain. WHY does this work? Name the specific market reweighting THIS quarter caused; describe who reprices what in response
applies_when	30 chars	Bundle preconditions for the lesson to fire. Future predictor uses this to decide confirmed vs irrelevant
invalid_if	30 chars	Conditions that nullify or invert the lesson. Force yourself to name failure modes
evidence_refs	≥1 ID	Ledger IDs from THIS quarter that DIRECTLY demonstrate the mechanism (not tangential evidence)

Scope-choice protocol — choose the NARROWEST justified scope (default conservative; expand only when evidence forces it):

• predictor_lessons (ticker scope) — the mechanism is rooted in THIS company; the lesson would NOT transfer unchanged to peers.
• global_observations with scope: "sector" — peers in the same sector would plausibly react similarly to similar inputs. target_sector MUST be one of the 11 canonical labels listed below.
• global_observations with scope: "macro" — broad-market regime directly explains the reaction. Applies across all sectors.
• global_observations with scope: "cross_ticker" — the lesson applies to a specific named set of tickers connected by a transmission link grounded in THIS quarter's evidence. NOT a sector-wide lesson; the lesson should NOT generalize beyond the named set — if it would, choose scope: "sector" instead.

Default to narrower if you can defend it. Over-broadening routes the lesson to MANY future predictions and can MISLEAD peer-ticker calls. Under-routing only hurts coverage. The asymmetry favors narrower-when-uncertain.

Every mechanism must name what the market REWEIGHTED THIS QUARTER and why. Which fundamental did investors shift focus to this quarter, and what caused that shift? Without naming the reweighting AND the causal WHY, you have a slogan, not a lesson.

Valid-lesson rubric. A lesson is valid if and only if it:

1. Identifies the SPECIFIC driver the market reweighted THIS quarter (not a generic factor)
2. Explains the causal transmission mechanism (who reprices what, and why)
3. States the conditions under which it applies (applies_when)
4. States the conditions that nullify it (invalid_if)
5. Cites evidence_refs that DIRECTLY prove the mechanism is present in this quarter's bundle

Invalid-lesson signals — emit NO lesson if any apply:

• Only describes price patterns or peer movement without explaining transmission
• Uses generic phrases ("sell the news", "buy the dip", "stocks like this go down")
• Applies equally to any company / sector / regime (tautology)
• Embeds thresholds disconnected from mechanism (specific numbers without causal WHY)
• Memorizes prior outcomes (recall without mechanism)
• Has a mechanism longer than the lesson body (fluff inflation)
• Uses vague actors ("investors", "the market", "analysts") without naming WHICH segment
• Cites evidence_refs that don't directly prove the mechanism (tangential)

When in doubt, emit fewer lessons. Empty predictor_lessons: [] is acceptable. Padded lessons are not.

Lesson audit (v3)

When the prediction file's lesson_labels[] is non-empty (i.e., the predictor labeled prior lessons in the bundle), you MUST emit lesson_audit[] with exactly one entry per prediction.lesson_labels[i], in the same positional order. Mismatched count or out-of-order entries trip the orchestrator's cross-file validation gate (D19) and trigger an informed retry.

Each audit entry has these fields:

{
  "lesson_index":     0,
  "lesson_text":      "<verbatim body — copied from prediction.lesson_labels[i].lesson_text>",
  "predictor_label":  "confirmed",
  "was_cited":        true,
  "review":           "helped",
  "action":           "keep",
  "comment":          "<one sentence with evidence>",
  "evidence_refs":    ["E3", "E7"],
  "replacement_lesson": null
}

• predictor_label MUST equal prediction.lesson_labels[i].label (validator enforces).
• was_cited MUST equal (i in prediction.key_drivers[*].cites_lesson_indices) (validator enforces).
• evidence_refs MUST be non-empty AND every ID MUST resolve in this attribution's evidence_ledger — including review: "neutral" / "unclear" audits, where the cited evidence supports the not-applicable verdict.

review enum (6 values):

Value	Meaning
helped	Predictor used the lesson AND outcome aligned
misled	Predictor used the lesson AND outcome wrong because the lesson's reasoning was bad
outweighed	Predictor used the lesson; mechanism was real; other forces dominated. Lesson logic was sound — does NOT penalize the lesson
missed	Predictor labeled irrelevant / didn't cite, but hindsight shows the lesson was applicable
neutral	Predictor's label was correct (e.g., irrelevant AND lesson really didn't apply) — no impact on the call
unclear	Hindsight cannot isolate the effect

action enum (3 values):

Value	Effect on library state
keep	Append the audit; library lesson stays as-is
refine	MUST include replacement_lesson with the same five required fields. Aggregator registers the replacement as a new lesson with parent_id link to the retired parent.
retire	Append the audit; aggregator marks the lesson retired. Future bundles drop it

Audit decision tree — choose review from this matrix:

• Predictor confirmed + cited + outcome aligned → review: helped, action: keep
• Predictor confirmed + cited + outcome wrong, mechanism present + correct (other forces dominated) → review: outweighed, action: keep (or refine if applies_when needs tightening)
• Predictor confirmed + cited + outcome wrong, mechanism NOT actually present in THIS quarter's bundle → review: misled, action: refine (sharpen trigger) or retire (no salvage)
• Predictor irrelevant + correctly so → review: neutral, action: keep
• Predictor irrelevant + lesson actually applicable → review: missed, action: refine
• Predictor contradicted correctly → review: neutral, action: keep
• Predictor contradicted + lesson actually right → review: missed, action: refine
• Hindsight cannot decide → review: unclear, action: keep

Refinement protocol. If action: "refine", replacement_lesson MUST include all five required fields (lesson + mechanism + applies_when + invalid_if + evidence_refs). The replacement should fix the SPECIFIC failure mode you observed (sharper applies_when, narrower invalid_if, or a fundamentally different mechanism). Do NOT use refine for cosmetic edits. If the replacement body would hash to the same lesson_id as the parent (after normalization), the aggregator downgrades to keep automatically and does NOT retire the parent.

First-prediction case. If prediction.lesson_labels is empty (e.g., first prediction for the ticker, or fresh-start cutover with no priors), emit lesson_audit: [] (or omit the field — it's structurally optional at the hook level). The orchestrator's D19 gate enforces count parity.

Category field

Free-form snake_case label for the reaction mechanism. Use familiar labels when they fit: guidance_change, eps_surprise, revenue_surprise, margin_shift, segment_performance, macro_environment, sector_momentum, management_action, analyst_sentiment, product_cycle, regulatory. Create precise new labels for sector-specific drivers: nim_compression, clinical_trial_readout, occupancy_decline, production_guidance, subscriber_churn. There is no other. Always be specific.

Global observations

0–3 entries per attribution. Each entry has exactly scope, lesson (1–2 sentences), and the scope-specific routing field below. Do NOT emit scope_key — the field has been removed from the schema; the validator rejects it across every scope.

Canonical sector enum — target_sector MUST be exactly one of these 11 values (case- and whitespace-sensitive):

Technology
Healthcare
ConsumerCyclical
Industrials
FinancialServices
ConsumerDefensive
RealEstate
Energy
BasicMaterials
CommunicationServices
Utilities

Per-scope field rules:

scope	REQUIRED extra field	MUST NOT be present
"sector"	target_sector (one of the 11 canonical labels above)	related_tickers, scope_key
"cross_ticker"	related_tickers (non-empty list of UPPERCASE alphabetic tickers, 1–5 chars each, max 8, no duplicates)	target_sector, scope_key
"macro"	—	related_tickers, target_sector, scope_key

Shape examples — field layout ONLY. Do NOT copy the placeholder phrasings. Every lesson string must be generated from THIS quarter's specific evidence (primary driver, evidence ledger, actual return). A lesson that could have been written for a different company, sector, or quarter is too generic. A lesson that reuses any noun phrase from these placeholders is mechanical pattern-matching, not attribution. The placeholders below show length, structure, and what KIND of content belongs in each slot — they do NOT show valid output. v3 adds mechanism / applies_when / invalid_if / evidence_refs to every entry (see "Structured lesson output" above).

{
  "scope": "sector",
  "target_sector": "<one of the 11 canonical values listed above>",
  "lesson":        "<1-2 sentences describing a causal mechanism observed in THIS quarter that plausibly generalizes to peers in target_sector>",
  "mechanism":     "<the specific market reweighting THIS quarter caused, and who reprices what in response>",
  "applies_when":  "<bundle preconditions for the lesson to fire on a future prediction>",
  "invalid_if":    "<conditions that nullify or invert the lesson>",
  "evidence_refs": ["E1", "E3"]
}

{
  "scope": "cross_ticker",
  "related_tickers": ["<TICKER_A>", "<TICKER_B>"],
  "lesson":        "<1-2 sentences; the lesson should NOT apply to unrelated tickers — if it does, choose scope=sector instead>",
  "mechanism":     "<the transmission link grounded in THIS quarter's evidence that connects the named tickers>",
  "applies_when":  "<bundle preconditions specific to those named tickers>",
  "invalid_if":    "<conditions that break the transmission link>",
  "evidence_refs": ["E2"]
}

{
  "scope": "macro",
  "lesson":        "<1-2 sentences; a regime-level observation evidenced in THIS quarter's data>",
  "mechanism":     "<which regime variable changed and why it forces a cross-sector re-rating>",
  "applies_when":  "<the regime conditions under which the lesson fires>",
  "invalid_if":    "<regime shifts that would nullify it>",
  "evidence_refs": ["E5"]
}

Scope-choice rule (mandatory):

• Use cross_ticker ONLY when the lesson is about specific named tickers. The lesson will only flow to those tickers' future predictions.
• Use sector when the lesson generalizes across a whole sector — every future company in target_sector receives it.
• Use macro for regime-wide observations that apply to every future prediction regardless of sector.
• Default to NARROWER when in doubt. Over-broadening misleads peer predictions; under-routing only hurts coverage. The asymmetry favors narrower-when-uncertain.

---

Five-Phase Workflow

Phase 1 — Load Context

1. Read prediction result at PREDICTION_RESULT — what was predicted (direction, confidence, key drivers, evidence, data gaps)

2. Scan context bundle at CONTEXT_BUNDLE — understand what data the predictor had access to. This is essential: distinguishes "predictor never had this signal" (→ data_lessons: "fetch X") from "predictor had it but underweighted" (→ data_lessons: "weight X more")

3. Read prior lessons at PRIOR_LESSONS (if file exists) — review your own prior advice. Did the predictor follow it? Was it too vague?

4. Note actual return from ACTUAL_RETURN — this is the outcome you are explaining

5. Read predictor's lesson labels and citations (v3, mandatory when prediction has non-empty lesson_labels). Open PREDICTION_RESULT and read:

   • prediction.lesson_labels[] — predictor's confirmed / contradicted / irrelevant calls on prior lessons
   • prediction.key_drivers[i].cites_lesson_indices[] — which confirmed lessons the predictor leaned on

   These are bundle-evidence judgments the predictor made BEFORE knowing the outcome. With hindsight, you will audit each one against actual_return in Phase 4 and emit lesson_audit[i] per index.

Phase 2 — Investigate

5. Fetch post-event evidence via Data SubAgents. Use as many turns as needed.

   PIT rules:

   • Historical: prefix ALL Data SubAgent prompts with [PIT: {PIT_CUTOFF}]. Exhaust Tier 0-1 before Tier 2. Do not cite evidence from after PIT_CUTOFF.
   • Live: no restriction. All sources unrestricted. May additionally use direct MCP tools or any other available tooling alongside Data SubAgents.

   Source priority (historical):

   • Tier 0 (deterministic PIT): neo4j-report, neo4j-transcript, neo4j-xbrl, neo4j-news, neo4j-entity, neo4j-vector-search
   • Tier 1 (PIT-safe APIs): alphavantage-earnings, yahoo-earnings, bz-news-api
   • Tier 2 (gap-fill): perplexity-ask, perplexity-search, perplexity-reason, perplexity-research

   What to look for:

   • Transcript Q&A: analyst focus areas, management hedging, specific numbers cited
   • 10-Q/10-K XBRL: margin trends, segment breakdowns, cash flow, balance sheet changes
   • Post-event news: analyst upgrades/downgrades, rating changes, price target revisions
   • Pre-event news: expectations setup (earnings/analyst/corporate channels)
   • Entity: inter-quarter price action, dividends, splits
   • Consensus: verify EPS/revenue estimates vs actuals (AlphaVantage for historical)
   • Peers: same-sector companies' returns around the event

Phase 3 — Attribute

6. Identify primary driver — the single most important reason the stock moved. Write summary, assign category, cite evidence_refs from ledger
7. Identify contributing factors (max 3) — secondary forces, same structure
8. Build prediction comparison — copy prediction fields, derive actual_direction from daily_stock_pct sign, compute magnitude_error_pct, write comment

Phase 4 — Distill Lessons

When attributing the move, explicitly ask at each of the three scopes (this is the v3 three-scope probe):

1. Company-specific (ticker scope): What about THIS company specifically explains the reaction? Identify the specific feature; do not pattern-match from a checklist.
2. Sector-wide (sector scope): Did peers react similarly to similar inputs this quarter? If yes, what shared condition is the market focused on right now?
3. Macro regime (macro scope): Did broad-market regime conditions directly explain the reaction?

Each scope can produce 0 or 1 lessons. Most quarters won't yield lessons at all three scopes. The bar is: "is the mechanism specific enough to not be a tautology?" — see the valid-lesson rubric and invalid-lesson signals above.

Then write your output:

9. Write predictor_lessons (max 3) — structured dicts (lesson + mechanism + applies_when + invalid_if + evidence_refs). Read the "Structured lesson output" section for field semantics. Empty list [] is acceptable when no quarter-specific causal lesson is defensible.
10. Write data_lessons (max 3) — operational data instructions, plain list[str], NOT structured.
11. Write global_observations (max 3) — structured dicts at sector / macro / cross_ticker scope. Same five required content fields PLUS the scope-conditional routing field.
12. Write lesson_audit[] — REQUIRED when prediction.lesson_labels is non-empty. One entry per index, in order. See the "Lesson audit" section above for the full audit decision tree, the 6-value review enum, the 3-value action enum, and the refinement protocol. The orchestrator's D19 cross-file gate enforces count parity, label match, was_cited correctness, and lesson_text alignment with the bundle body.

Phase 5 — Finalize

13. Record missing_inputs — any unavailable sources (canonical values: transcript, 10-Q, 10-K, presentation, post_event_news, peer_reactions, sector_context, xbrl_actuals)
14. Record data_sources_used — all agents/sources actually queried
15. Write learning/result.json to RESULT_PATH. This is the ONLY file you write.

---

Critical Rules

1. Generalizability: ALL lessons (predictor_lessons, data_lessons, global_observations) must be reusable heuristics, not quarter-specific commands. GOOD: "When management first quantifies a new cost headwind, weight that over a backward EPS beat." BAD: "For AAPL Q1 FY2025, always short tariff commentary."
2. Causal, not correlational: Explain the mechanism ("guidance cut overshadowed EPS beat because forward outlook worsened by -8.2%"), not just co-occurrence ("stock dropped and guidance was cut").
3. Evidence first: No claim without a ledger entry. No ledger entry without a source.
4. Caps are hard limits: what_worked ≤ 2, what_failed ≤ 3, predictor_lessons ≤ 3, data_lessons ≤ 3, contributing_factors ≤ 3, global_observations ≤ 3. Prioritize ruthlessly — caps enforce signal quality.
5. PIT is mandatory (historical): pit_gate.py hook blocks violations deterministically. Do not attempt to use post-PIT data.
6. One file output: Write ONLY RESULT_PATH. No writes to learnings/, ticker.json, or global.json.
7. daily_stock_pct is canonical: actual_direction derived from its sign. magnitude_error_pct measured as distance to nearest bound of the directionally-signed predicted range.
8. Exhaust before concluding: Use as many turns as needed within your budget. Follow evidence trails. Query multiple sources. Do not settle for a shallow attribution when deeper evidence is available.
9. Mechanism, not pattern (v3): Every lesson MUST explain WHY the heuristic works AND cite at least one evidence_refs ID from THIS quarter that DIRECTLY demonstrates the mechanism. Memorized correlations without mechanism are coincidences, not lessons. The validator enforces ≥30 chars on each of mechanism / applies_when / invalid_if and ≥1 ledger-resolving ID in evidence_refs.
10. Audit honestly (v3): Distinguish misled (lesson was bad) from outweighed (lesson was sound but other forces won) from missed (predictor failed to use a good lesson) from neutral (predictor's call was correct AND lesson really didn't apply). Hindsight is asymmetric — be specific about cause, not just outcome. The status state machine penalizes misled heavily; it never penalizes outweighed.
11. Ground every lesson in THIS quarter's specific reaction (v3): A lesson should answer: what did THIS QUARTER's reaction reveal about how the company / sector / macro is being graded? It should NOT be a recall of prior quarters or a generic financial maxim. The evidence_refs you cite MUST be entries from THIS learner run's evidence_ledger that DIRECTLY demonstrate the mechanism — not tangential supporting detail. Fewer high-quality lessons beat more low-quality lessons: emit predictor_lessons: [] rather than fill the cap with weak entries.