Earnings Orchestrator

Goal: Predict stock direction post 8-K earnings release & refine predictions methodology using 10-Q/10-K filing, news & analysis, transcripts, presentations, web search and actual return outcomes.

Two phases per quarter:

1. Prediction (after 8-K): Predict direction/magnitude before market reacts
2. Attribution (after 10-Q/10-K): Analyze actual outcome, score prediction accuracy, learn

Triggers

Invoke when user asks about:

• "Run earnings prediction for {TICKER}"
• "Predict {TICKER} earnings reaction"

Workflow (8 Steps)

Step 1: Discovery

Run discovery script:

get_quarterly_filings {TICKER}

Output columns: accession8k|filed8k|marketsession8k|accession10q|filed10q|marketsession10q|formtype|fiscalyear|fiscal_quarter|lag

Events manifest is built automatically at: earnings-analysis/Companies/{TICKER}/events/event.json

Each row becomes:

• quarterlabel: {fiscalquarter}FY{fiscalyear}
• accessionno: accession8k
• filingdatetime: filed8k

Step 2: Filter Events

Read earnings-analysis/Companies/{TICKER}/events/event.json and process events in the order listed.

Filter logic (minimal):

for event in event.json.events:
  q = event.quarter_label
  result = earnings-analysis/Companies/{TICKER}/events/{q}/prediction/result.json
  if result exists: skip
  else: enqueue event for prediction

Output: list of queued events (at least quarterlabel, accession8k, filed8k, marketsession_8k).

Step 3: Task Creation

Placeholder (later): create deterministic task graph / resume-safe plan per event.

Step 4: Run Predictions

For each queued event (same order as event.json):

1. Ensure earnings-analysis/Companies/{TICKER}/events/{quarter_label}/prediction/ exists.

1. If prediction/context.json is missing, write it ONCE (do not overwrite if it exists):

Context file (written only if missing):

{
  "schema_version": 1,
  "ticker": "{TICKER}",
  "quarter_label": "{quarter_label}",
  "accession_8k": "{accession_8k}",
  "filed_8k": "{filed_8k}",
  "market_session_8k": "{market_session_8k}",
  "pit_datetime": "{filed_8k}"
}

1. Run the prediction skill:

Skill: earnings-prediction
Args (minimal): ticker={TICKER} quarter_label={quarter_label} accession_no={accession_8k} filing_datetime={filed_8k}

Completion signal: earnings-analysis/Companies/{TICKER}/events/{quarter_label}/prediction/result.json exists.

Step 5: Cross-Tier Polling

Placeholder (later): poll tasks / spawn downstream work when unblocked.

Step 6: Validation Gate

Placeholder (later): validate all per-event outputs are present + schema-valid before marking complete.

Step 7: Aggregation

Placeholder (later): build cumulative CSVs / indices from per-event outputs.

Step 8: Completion

Echo ORCHESTRATOR_COMPLETE {TICKER}.

Scripts

Canonical discovery script:

• .claude/skills/earnings-orchestrator/scripts/getquarterlyfilings.py - Get 8-K earnings events with matched 10-Q/10-K filings

Exposed on PATH as:

• getquarterlyfilings

Hooks

• Skill hook (PostToolUse Bash): python3 $CLAUDEPROJECTDIR/.claude/hooks/buildorchestratorevent_json.py → rebuilds events/event.json after discovery

Data Guardrails

See .claude/filters/rules.json for:

• Forbidden patterns (lookahead bias blockers)
• PIT date fields per data source

Output

Events manifest: earnings-analysis/Companies/{TICKER}/events/event.json (rebuilt every run) Context bundle (shared by predictor + learner): earnings-analysis/Companies/{TICKER}/events/{quarterlabel}/contextbundle.{json,txt} (promoted to quarter root per obsidianthinking.md 2026-04-17) Prediction: earnings-analysis/Companies/{TICKER}/events/{quarterlabel}/prediction/result.json Learning (renamed from attribution/ per obsidianthinking.md 2026-04-17): earnings-analysis/Companies/{TICKER}/events/{quarterlabel}/learning/result.json

Invariants (Must Always Hold)

• If prediction/result.json exists, prediction is skipped.
• context_bundle.json (quarter root) is written only if missing (never overwritten by orchestrator).
• If learning/result.json exists and is valid, derived-write recovery runs (ticker/global lesson appends) then learning analysis is skipped. If the existing file is invalid or corrupt, it is deleted and the learner re-runs.

Version 1.0 | 2026-02-04 | Initial structured format