guidance-inventory

name	guidance-inventory
description	Builds and maintains cumulative guidance inventory for a company. Use when collecting historical guidance, updating guidance after earnings, preparing context for prediction/attribution workflows, or when user asks about company outlook, earnings guidance, management expectations, forward forecasts, or FY/quarterly targets.
allowed-tools	Read, Write, Grep, Glob, Skill, mcp__neo4j-cypher__read_neo4j_cypher, mcp__perplexity__perplexity_search, mcp__alphavantage__EARNINGS_ESTIMATES
model	claude-opus-4-5-20251101
permissionMode	dontAsk

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

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

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

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

- 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          
             
               

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:

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

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

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

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)

/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

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

---

Input from guidance-extract (guidance.csv)

The guidance-extract agent outputs to earnings-analysis/Companies/{TICKER}/guidance.csv. This file uses an 18-field pipe-delimited format (+ quarter context = 19 fields).

Field Mapping from guidance.csv

guidance.csv Field	Type	Maps to GuidanceEntry
quarter	string	Context (which earnings call)
period_type	enum	period.period_type
fiscal_year	int	period.fiscal_year
fiscal_quarter	int/.	period.fiscal_quarter (. = null for annual)
segment	string	Additional context for segment-level guidance
metric	string	metric
low	float/.	value_low
mid	float/.	value_mid
high	float/.	value_high
unit	string	unit
basis	string	basis
derivation	enum	New field: explicit, calculated, point, implied
qualitative	string/.	Soft guidance text when numeric not available
source_type	string	source_type
source_id	string	source_id
source_key	string	Which content in source (e.g., EX-99.1, full)
given_date	date	given_date
section	string	page_or_section
quote	string	quote (pipes replaced with ¦)

Derived Fields (computed by guidance-inventory)

Field	How Derived
calendar_start	From fiscal_year + fiscal_quarter + company's fiscal_year_end_month
calendar_end	From fiscal_year + fiscal_quarter + company's fiscal_year_end_month
status	Compare calendar_end vs current date: future, current, past
action	Compare to prior guidance for same metric/period: INITIAL, RAISED, LOWERED, etc.
entry_id	Generate unique ID: {metric}-{period_type}-{fiscal_year}-{sequence}

Derivation Field Interpretation

derivation	Meaning	Numeric Fields
explicit	All three values stated by management	low, mid, high populated
calculated	mid = (low+high)/2 computed by agent	low, high from source; mid calculated
point	Single value: "around $15B"	low = mid = high (same value)
implied	Qualitative only, no numbers	low, mid, high = .; qualitative populated

Handling Qualitative Guidance

When derivation=implied, the qualitative field contains non-numeric guidance:

• "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 field and noted in analysis context.

---

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

@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: []
    value_high: []
    unit:                            
    basis:                           

    
    source_type:                     
    source_id:                       
    given_date: date                    
    quote:                           
    page_or_section: []      

    
    action: [, , , , , , ]
    status: [, , ]
    superseded_by: []        

---

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