Guidance Inventory

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

Thinking: ALWAYS use ultrathink for maximum reasoning depth when extracting and classifying guidance.

Input: {ticker} {accession_no} {quarter} (e.g., 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.)

•Quick Reference
•Arguments
•
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
•Guidance Types to Capture
•Period Types
•10 Critical Capture Items
•Citation Requirements
•Supersession Tracking
•File Lifecycle
•Integration with Other Skills
•What This Is NOT
•Invocation Examples
•Error Handling
•Reference Files
•Requirements Checklist
•Data Model Reference

Quick Reference

Field	Value
Output	`earnings-analysis/Companies/{TICKER}/guidance-inventory.md`
Mode	Cumulative (grows over time, never overwrites)
Trigger	Q1 = full historical build; Q>=2 = updated by attribution

Arguments

code

$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

code

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:

cypher

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

The periodOfReport reveals FYE (e.g., 2024-09-30 = September FYE).

Build fiscal calendar — see FISCAL_CALENDAR.md.

Step 3: GATHER GUIDANCE

Source Priority (query in order):

Priority	Source	Skill	Reliability	Best For
1	8-K EX-99.1 press release	`/neo4j-report`	Highest	Official numbers
2	Earnings transcript	`/neo4j-transcript`	High	Context, nuance, Q&A
3	Alpha Vantage	`/alphavantage-earnings`	High	Consensus estimates
4	News	`/neo4j-news`	Medium	Reactions, analyst commentary
5	Perplexity	`/perplexity-search`	Medium	Gap filling, historical
6	WebSearch	`WebSearch`	Medium	SEC filings, IR pages

See QUERIES.md for specific queries.

Step 4: EXTRACT GUIDANCE ENTRIES

For each guidance found, capture ALL of these fields:

yaml

- 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:

Condition	Action	Signal
No prior guidance exists	INITIAL	Sets anchor
Midpoint increased	RAISED	Bullish
Midpoint decreased	LOWERED	Bearish
Midpoint same, range narrower	NARROWED	More certainty
Midpoint same, range wider	WIDENED	More uncertainty
Explicitly reiterated unchanged	MAINTAINED	Neutral (can disappoint if beat expected)
Guidance removed	WITHDRAWN	Usually very bearish

Anchor Tracking & Revision Math

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

code

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:

code

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

Metric	Common Variants
EPS	GAAP, Non-GAAP, Adjusted, Diluted
Revenue	Total, By Segment, Organic vs Reported
Gross Margin	%
Operating Margin	GAAP, Non-GAAP
Net Income	GAAP, Adjusted
Free Cash Flow	Operating CF minus CapEx
CapEx	Total, By Category

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

Period Type	Covers	Typical Pattern
Quarterly	Single quarter (3 months)	Given for next quarter only
Annual	Full fiscal year	Given in Q1, updated each quarter
Half-Year	H1 or H2 (6 months)	Some international companies
Long-Range	Multi-year targets	"2027 targets", analyst days

10 Critical Capture Items (MUST-HAVE)

A. Guidance vs Consensus Gap

code

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

code

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

code

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

Capture both consolidated AND segment if available.

D. FX / Constant Currency

code

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

Note which basis. FX assumption is a condition.

E. Conditional Guidance

code

"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)

code

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

code

"Company does not provide quarterly guidance"

Track if company guides at all — absence is informative.

H. Historical Accuracy (Beat/Miss Pattern)

code

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

code

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

code

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):

yaml

# 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

code

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

Skill	Relationship
earnings-orchestrator	CALLS this skill for both BUILD (q=1) and UPDATE (q>=2)
earnings-prediction	READS guidance-inventory to know prior expectations
earnings-attribution	READS guidance-inventory for surprise calculation

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)

code

/guidance-inventory AAPL 0001193125-24-000001 1

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

UPDATE mode (Q2-Q4)

code

/guidance-inventory AAPL 0001193125-24-000123 2

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

From orchestrator

code

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

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

Error Handling

Scenario	Action
No 8-K found	Log warning, return empty inventory section
No EX-99.1 exhibit	Try transcript, then Perplexity fallback
No guidance in filing	Note "No forward guidance provided" in inventory
Neo4j query fails	Retry once, then log error and continue with other sources
Company doesn't provide guidance	Record in Guidance Policy field, don't fabricate
FYE not determinable	Query Perplexity, assume December if no data
Ambiguous period reference	Note ambiguity in quote, use best interpretation

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

Requirements Checklist

Requirement	How Addressed
Period association	Every entry has period_type, fiscal_year, fiscal_quarter
Quarter vs Annual	`period_type` field distinguishes
Fiscal year tracking	`fiscal_year` + company `fiscal_year_end_month`
Calendar mapping	`calendar_start` / `calendar_end` derived from FYE
Future vs Past	`status` field: future / current / past
Supersession	`superseded_by` links to newer guidance entry
Anchor tracking	Q1 annual guidance marked, revisions calc'd vs anchor
Both dates tracked	`given_date` (citation) + period fields (target)

Data Model Reference

python

@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

Guidance Inventory

Table of Contents

Quick Reference

Arguments

Workflow

Step 1: DETERMINE SCOPE

Step 2: GET COMPANY FISCAL PROFILE

Step 3: GATHER GUIDANCE

Step 4: EXTRACT GUIDANCE ENTRIES

Step 5: CLASSIFY ACTION

Anchor Tracking & Revision Math

One Call → Multiple Periods

Step 6: WRITE OUTPUT

Guidance Types to Capture

Financial - Hard Numbers

Financial - Soft/Qualitative

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

Period Types

10 Critical Capture Items (MUST-HAVE)

A. Guidance vs Consensus Gap

B. Metric Definition Drift

C. Segment-Level Guidance

D. FX / Constant Currency

E. Conditional Guidance

F. Pre-Announcements (Mid-Quarter Updates)

G. Guidance Policy

H. Historical Accuracy (Beat/Miss Pattern)

I. Comparable Periods

J. Range Asymmetry

Citation Requirements (Non-Negotiable)

Supersession Tracking

File Lifecycle

Integration with Other Skills

What This Is NOT

Invocation Examples

BUILD mode (Q1 - Initial)

UPDATE mode (Q2-Q4)

From orchestrator

Error Handling

Reference Files

Requirements Checklist

Data Model Reference