Scan to join WeChat groupGuidance 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
- 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
$ARGUMENTS = "{ticker} {accession_no} {quarter}"
ticker: Company symbol (e.g., AAPL)accession_no: 8-K accession being processedquarter: 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 | 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:
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, Perplexitysource_id: Accession number or URLgiven_date: When guidance was issued (ISO format)quote: Exact quote or close paraphrasepage_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: 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