Guidance Inventory

Builds cumulative guidance state per company. This is a DATA skill (pure collection) — analysis happens in attribution.

Thinking: ALWAYS use

ultrathink

Input:

{ticker} {accession_no} {quarter}

AAPL 0001193125-24-000001 2

Critical: Every guidance entry has TWO dates — must track BOTH:

• Given Date: When management issued the guidance (citation timestamp)
• Period Covered: What fiscal period the guidance is FOR (Q2 FY25, FY25, etc.)

Table of Contents

1. Quick Reference
2. Arguments
3. Workflow
   • Step 1: Determine Scope
   • Step 2: Get Company Fiscal Profile
   • Step 3: Gather Guidance
   • Step 4: Extract Guidance Entries
   • Step 5: Classify Action
   • Step 6: Write Output
4. Guidance Types to Capture
5. Period Types
6. 10 Critical Capture Items
7. Citation Requirements
8. Supersession Tracking
9. File Lifecycle
10. Integration with Other Skills
11. What This Is NOT
12. Invocation Examples
13. Error Handling
14. Reference Files
15. Requirements Checklist
16. Data Model Reference

Quick Reference

earnings-analysis/Companies/{TICKER}/guidance-inventory.md

Arguments

$ARGUMENTS = "{ticker} {accession_no} {quarter}"

• ticker

  : Company symbol (e.g., AAPL)

• accession_no

  : 8-K accession being processed

• quarter

  : Which quarter (1, 2, 3, 4) — determines historical depth

Workflow

Step 1: DETERMINE SCOPE

IF quarter = 1:
    depth = "all"        # All available historical guidance
    action = "BUILD"     # Create new inventory
ELSE:
    depth = "3 months"   # From previous r.created to current r.created
    action = "UPDATE"    # Append to existing inventory

Step 2: GET COMPANY FISCAL PROFILE

Query Neo4j for fiscal year end:

MATCH (c:Company {ticker: $ticker})<-[:PRIMARY_FILER]-(r:Report {formType: '10-K'})
RETURN r.periodOfReport
ORDER BY r.created DESC LIMIT 1

The

periodOfReport

2024-09-30

Build fiscal calendar — see FISCAL_CALENDAR.md.

Step 3: GATHER GUIDANCE

Source Priority (query in order):

/neo4j-report

/neo4j-transcript

/alphavantage-earnings

/neo4j-news

/perplexity-search

WebSearch

See QUERIES.md for specific queries.

Step 4: EXTRACT GUIDANCE ENTRIES

For each guidance found, capture ALL of these fields:

- period_type: quarter | annual | half | long-range
  fiscal_year: 2025
  fiscal_quarter: 2              # null for annual
  calendar_start: "2025-01-01"   # Derived from FYE
  calendar_end: "2025-03-31"     # Derived from FYE
  status: future | current | past

  metric: "EPS"
  value_low: 1.50
  value_high: 1.70
  value_mid: 1.60
  unit: "USD"
  basis: "non-GAAP adjusted"     # CRITICAL: track definition

  given_date: "2025-02-05"       # When guidance was issued
  source_type: "8-K"
  source_id: "0001234567-25-000001"
  quote: "We expect Q2 EPS of $1.50 to $1.70"
  page_or_section: "Page 2, Outlook"

  action: INITIAL | RAISED | LOWERED | MAINTAINED | NARROWED | WIDENED | WITHDRAWN
  prior_value_mid: 1.55          # If action != INITIAL
  revision_pct: +3.2%            # (new_mid - prior_mid) / prior_mid

Step 5: CLASSIFY ACTION

Compare to prior guidance for same metric/period:

Anchor Tracking & Revision Math

Q1 establishes the "anchor" for annual guidance. Track cumulative revision:

Q1 FY25 call: "FY25 EPS $12.00-$13.50" (anchor midpoint: $12.75)
Q2 FY25 call: "FY25 EPS $12.50-$13.50" (revision: +$0.25 midpoint, +2.0% from anchor)
Q3 FY25 call: "FY25 EPS $13.00-$14.00" (cumulative: +$0.75 from anchor, +5.9%)

Revision calculation:

((new_mid - anchor_mid) / anchor_mid) × 100

One Call → Multiple Periods

Each earnings call typically addresses MULTIPLE periods — track separately:

Q1 FY25 Earnings Call (Feb 2025):
├── Q1 FY25 (Oct-Dec 2024): ACTUALS REPORTED      ← past period
├── Q2 FY25 (Jan-Mar 2025): NEW GUIDANCE          ← future (quarterly)
├── FY25 Full Year:         GUIDANCE UPDATED      ← current (annual)
└── Sometimes: FY26:        PRELIMINARY OUTLOOK   ← future (next year preview)

Step 6: WRITE OUTPUT

Use template in OUTPUT_TEMPLATE.md.

Critical Rules:

• Never overwrite existing content — always APPEND
• Each update gets a timestamped section header
• Include evidence ledger entry for every data point

Guidance Types to Capture

Financial - Hard Numbers

Financial - Soft/Qualitative

• "Double-digit growth"
• "Margin expansion of 50-100 bps"
• "Flat year-over-year"
• "Modest improvement"

Operational (Non-Financial)- few examples only, non exhasutive

• Units / Subscribers / DAUs / MAUs
• Store openings / closings
• Headcount changes
• Market share targets
• Product launch timing

Period Types

10 Critical Capture Items (MUST-HAVE)

A. Guidance vs Consensus Gap

Company Guidance: "FY25 EPS $12.00-$13.50" (mid: $12.75)
Street Consensus: "$13.22"
Gap: -3.6% (company below street) → bearish signal

Track BOTH separately.

B. Metric Definition Drift

Q1: "Adjusted EPS excluding stock comp: $3.50"
Q2: "Adjusted EPS: $3.40"  ← Did definition change?

Note basis in every entry.

C. Segment-Level Guidance

Total Revenue: $10B
  - Cloud: $4B (guidance given)
  - Hardware: $6B (no guidance)

Capture both consolidated AND segment if available.

D. FX / Constant Currency

"Revenue growth 8-10% constant currency"
"Revenue growth 5-7% as reported"

Note which basis. FX assumption is a condition.

E. Conditional Guidance

"Guidance assumes no further Fed rate increases"
"Contingent on closing the Acme acquisition in Q3"

Track assumptions — they can invalidate guidance.

F. Pre-Announcements (Mid-Quarter Updates)

8-K filed mid-quarter: "Lowering Q2 guidance due to..."

These are often most market-moving. Query for 8-K Item 7.01 between earnings.

G. Guidance Policy

"Company does not provide quarterly guidance"

Track if company guides at all — absence is informative.

H. Historical Accuracy (Beat/Miss Pattern)

Last 8 quarters: Beat guidance 7/8 times
Average beat: +3.2%
Pattern: "Sandbagger" - guides low, beats high

This is predictive signal. Track in company profile section.

I. Comparable Periods

FY25 Q2 guidance vs FY24 Q2 actual (YoY)
FY25 Q2 guidance vs FY25 Q1 actual (Sequential)

Link guidance to historical actuals for context.

J. Range Asymmetry

Range: $12.00-$14.00, Midpoint: $13.00
Low end = -8% from mid, High end = +8% from mid → symmetric
Low end = -2%, High end = +14% → asymmetric bullish

Range shape signals management confidence.

Citation Requirements (Non-Negotiable)

Every guidance entry MUST have:

• source_type

  : 8-K, Transcript, News, Perplexity

• source_id

  : Accession number or URL

• given_date

  : When guidance was issued (ISO format)

• quote

  : Exact quote or close paraphrase

• page_or_section

  : Where in source (if applicable)

No citation = No entry

Supersession Tracking

When guidance is updated, the old entry is superseded (not deleted):

# Entry 1 (superseded)
entry_id: "FY25-EPS-001"
value: "$6.60-$7.30"
given_date: "2024-11-01"
status: superseded
superseded_by: "FY25-EPS-002"

# Entry 2 (current)
entry_id: "FY25-EPS-002"
value: "$6.80-$7.40"
given_date: "2025-02-05"
status: active
superseded_by: null

This preserves the revision history chain.

File Lifecycle

Q1 (First Report for Company):
    earnings-orchestrator
        ↓
    /guidance-inventory BUILD
        ↓
    Creates: {TICKER}/guidance-inventory.md (from all historical)

Q2-Q4 (Subsequent Reports):
    earnings-orchestrator
        ↓
    /guidance-inventory UPDATE
        ↓
    Appends: new guidance from current filing

Real-time (Future - Deferred):
    Background process monitors mid-quarter 8-Ks
        ↓
    Auto-triggers UPDATE

Integration with Other Skills

Note: This skill is called from orchestrator (Layer 1, forked). Task tool is BLOCKED.

What This Is NOT

• NOT consensus estimates storage — consensus lives in prediction/attribution reports
• NOT met/missed analysis — that's attribution's job
• NOT forward guidance interpretation — just data collection
• Pure inventory only — no analysis, no recommendations

Invocation Examples

BUILD mode (Q1 - Initial)

/guidance-inventory AAPL 0001193125-24-000001 1

Creates full historical inventory from all available 8-Ks and transcripts.

UPDATE mode (Q2-Q4)

/guidance-inventory AAPL 0001193125-24-000123 2

Appends only new guidance from the current quarter's filing.

From orchestrator

Skill: guidance-inventory
Args: "GBX 0001193125-23-002899 1"

Called automatically by earnings-orchestrator for each 8-K.

Error Handling

Principle: Never fabricate guidance. If not found, document absence.

Reference Files

• QUERIES.md — Neo4j and Perplexity queries
• OUTPUT_TEMPLATE.md — File format template
• FISCAL_CALENDAR.md — FYE handling and calendar mapping

Input from guidance-extract (guidance.csv)

The

guidance-extract

earnings-analysis/Companies/{TICKER}/guidance.csv

Field Mapping from guidance.csv

period.period_type

period.fiscal_year

.

period.fiscal_quarter

.

metric

.

value_low

.

value_mid

.

value_high

unit

basis

explicit

calculated

point

implied

.

source_type

source_id

EX-99.1

full

given_date

page_or_section

quote

Derived Fields (computed by guidance-inventory)

calendar_start

fiscal_year

fiscal_quarter

fiscal_year_end_month

calendar_end

fiscal_year

fiscal_quarter

fiscal_year_end_month

status

calendar_end

future

current

past

action

INITIAL

RAISED

LOWERED

entry_id

{metric}-{period_type}-{fiscal_year}-{sequence}

Derivation Field Interpretation

explicit

calculated

point

implied

.

Handling Qualitative Guidance

When

derivation=implied

qualitative

• "double-digit" → Growth expectation without specific number
• "low to mid single digits" → Range expressed qualitatively

These entries should be captured in guidance-inventory with the qualitative text preserved in the

quote

Requirements Checklist

period_type

fiscal_year

fiscal_year_end_month

calendar_start

calendar_end

status

superseded_by

given_date

Data Model Reference

@dataclass
class GuidancePeriod:
    """Represents a fiscal period that guidance covers."""
    period_type: Literal["quarter", "annual", "half", "long-range", "other"]
    fiscal_year: int                    # e.g., 2025
    fiscal_quarter: Optional[int]       # 1-4 for quarters, None for annual
    calendar_start: date                # Derived from company FYE
    calendar_end: date                  # Derived from company FYE

    def status(self, as_of: date) -> Literal["future", "current", "past"]:
        if self.calendar_end < as_of:
            return "past"
        elif self.calendar_start <= as_of <= self.calendar_end:
            return "current"
        else:
            return "future"

@dataclass
class GuidanceEntry:
    """A single guidance data point."""
    entry_id: str                       # e.g., "FY25-EPS-001"
    period: GuidancePeriod
    metric: str                         # "EPS", "Revenue", etc.
    value_low: Optional[float]
    value_mid: Optional[float]
    value_high: Optional[float]
    unit: str                           # "USD", "%", "B USD"
    basis: str                          # "GAAP", "non-GAAP adjusted"

    # Citation (required)
    source_type: str                    # "8-K", "Transcript", "News"
    source_id: str                      # accession or URL
    given_date: date                    # When guidance was issued
    quote: str                          # Exact quote
    page_or_section: Optional[str]      # Where in source

    # State
    action: Literal["INITIAL", "RAISED", "LOWERED", "MAINTAINED", "NARROWED", "WIDENED", "WITHDRAWN"]
    status: Literal["active", "superseded", "withdrawn"]
    superseded_by: Optional[str]        # Entry ID of newer guidance

Version 1.6 | 2026-01-17 | Added Input line for quick reference