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.
Scanned 2/12/2026
Install via CLI
Skills Directoryopenskills install majiayu000/claude-skill-registry---
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](#quick-reference)
2. [Arguments](#arguments)
3. [Workflow](#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](#guidance-types-to-capture)
5. [Period Types](#period-types)
6. [10 Critical Capture Items](#10-critical-capture-items-must-have)
7. [Citation Requirements](#citation-requirements-non-negotiable)
8. [Supersession Tracking](#supersession-tracking)
9. [File Lifecycle](#file-lifecycle)
10. [Integration with Other Skills](#integration-with-other-skills)
11. [What This Is NOT](#what-this-is-not)
12. [Invocation Examples](#invocation-examples)
13. [Error Handling](#error-handling)
14. [Reference Files](#reference-files)
15. [Requirements Checklist](#requirements-checklist)
16. [Data Model Reference](#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:
```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](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](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:
```
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](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):
```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
```
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](QUERIES.md) — Neo4j and Perplexity queries
- [OUTPUT_TEMPLATE.md](OUTPUT_TEMPLATE.md) — File format template
- [FISCAL_CALENDAR.md](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
```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*
No comments yet. Be the first to comment!
