---
name: forecast-variance-analysis
version: 1.0.0
deployment_target: plugin
status: PROPOSED
description: "Compares submitted forecast to actual closed/won outcomes. Classifies variance by root cause: rep-level, deal-size band, stage-entry, seasonal, or product/segment. Surfaces systemic patterns — not one-off explanations. Minimum: 3 deals or 2 consecutive quarters before a pattern is surfaced. Triggers: 'why did we miss', 'forecast variance', 'call accuracy', 'forecast accuracy by rep', 'what caused the miss'."
---
[PROPOSED]
# Forecast Variance Analysis
Traces the gap between what was called and what closed to its root cause.
Patterns require ≥3 deals or ≥2 consecutive quarters before surfacing.
One-off variance is noted but not classified as a pattern.
**Reference:** Variance classification taxonomy → `../../../shared/revops-domain-model.md §4`
**Config reads:** `current_arr`, `primary_segment`, `crm_system`
---
## Pre-flight
Read `~/.claude/plugins/config/claude-for-customer-success/rev-ops/CLAUDE.md` and
`~/.claude/plugins/config/claude-for-customer-success/company-profile.md`.
If either is missing or contains `[PLACEHOLDER]` markers, stop and prompt for
`/rev-ops:cold-start-interview`.
Note from config: `current_arr`, `primary_segment`, `crm_system`
**G-code dependency:** All G-code guardrails referenced in this skill (G1–G9) are defined in the CLAUDE.md config loaded above. If Pre-flight halts or config is missing, G-codes are undefined — do not proceed with partial config.
---
## Use when
- Actual results deviate from forecast and root cause analysis is needed
- Post-quarter variance review requires structured decomposition
- Forecast accuracy trending needs to be assessed across periods
## Do NOT use for
- Forward-looking scenario modeling (use scenario-modeling)
- Pipeline coverage adequacy (use pipeline-coverage-analysis)
- Individual deal health (use deal-health-scoring)
## Typical Activation
"Forecast variance analysis", "why did we miss forecast", "actuals vs forecast for Q[N]", "variance decomposition", "forecast accuracy review"
---
## Reasoning Protocol
Before generating output, apply these primers:
1. **CLASSIFY**: What type of forecast variance request is this?
- Single-quarter variance analysis (one period — total miss + root cause classification)
- Multi-quarter trend analysis (≥2Q — pattern detection across periods, rep accuracy trending)
- Rep call accuracy review (rep-level scorecard — submitted vs. actual by rep, trailing quarters)
- Root cause classification (pattern identification against taxonomy: rep-level, deal-size, stage-entry, seasonal, product/segment)
2. **CONSTRAINTS**: What limits the solution space?
1. Confirm activation — user asking about forecast accuracy, miss analysis, or call quality
2. Check HubSpot connector — multi-quarter history required; declare fallback if unavailable
3. Confirm the period being analyzed (default: most recently closed quarter)
4. Apply G6 — state data-as-of for all historical pipeline pulls
5. Apply G1 — any forward-looking variance projection requires forecast language qualification
6. Apply G5 — rep call accuracy scorecard is analytical input; manager owns the coaching response
7. Apply pattern confidence gate: ≥3 deals or ≥2 consecutive quarters before surfacing a classification
3. **EXPERT CHECK**: What would a veteran RevOps forecast analyst verify first?
- Is the data-as-of timestamp declared before surfacing any variance pattern? Stale historical
reads may exclude deals that closed or slipped after the pull — declare data age upfront.
- Is the pattern confidence gate enforced before classifying variance? Below-threshold
observations are noise, not patterns — surfacing them as classifications misleads coaching.
- Is the rep accuracy scorecard framed as analytical input, not a performance directive?
Variance analysis surfaces what happened; the manager decides what to do about it.
- Is the submitted forecast source confirmed (HubSpot vs. user-provided spreadsheet)?
Mixed sources produce phantom variance that doesn't reflect actual call accuracy.
4. **ANTI-PATTERNS**: Common mistakes to avoid:
- Surfacing HubSpot reads without data-as-of timestamp (G6 violation)
- Classifying variance as a systemic pattern below the ≥3-deal / ≥2Q confidence threshold
- Presenting rep accuracy scorecard as a performance directive rather than analytical input (G5 violation)
- Applying forward-looking language to variance projections without G1 qualification
**After execution**, verify:
- G6 data-as-of label applied to all HubSpot historical reads
- G1 qualification present on any forward-looking projection derived from variance analysis
- G5 qualifier present: rep scorecard is analytical input; manager owns the coaching response
- Confidence: High when HubSpot is connected and multi-quarter data is current; Moderate when data is stale or connector is unavailable
- Confidence: [High] when HubSpot is connected and multi-quarter data is current / [Medium] when data is stale or connector is unavailable / [Low] if all inputs are manual or unverified
---
## Inputs
**Connector error categorization:** When a connector call fails, distinguish the error type before proceeding:
- **Rate-limited (transient):** Connector returns HTTP 429 or equivalent throttle signal. Note the rate limit explicitly in output ("CRM data temporarily rate-limited — retry in 60 seconds recommended") and offer to retry rather than proceeding with degraded output.
- **Unavailable (permanent for this session):** Connector is not configured, authentication has expired, or service is down. Fall back to user-provided data and label all affected sections as "connector unavailable — manual input used."
Do not conflate these — a rate-limited connector will return data shortly; an unavailable connector will not.
Required:
- Period to analyze (default: most recently closed quarter)
- Submitted forecast at quarter-start (from HubSpot or user-provided)
- Actual closed/won (from HubSpot)
Optional:
- Rep filter, segment filter
- Number of prior quarters for trend analysis (default: 4)
---
## Workflow
**Step 1 — Calculate total variance**
```
Variance Amount = Submitted Forecast − Actual Closed/Won
Variance % = Variance Amount ÷ Submitted Forecast
```
**Step 2 — Classify variance** `[revops-domain-model.md §4]`
For each deal that was in the submitted forecast but did not close, or closed at
a different amount, classify the contributing factor:
- **Rep-level** — specific rep consistently over/under-calling (≥3 deals, ≥2Q)
- **Deal-size band** — ACV range systematically slipping
- **Stage-entry** — deals entering a stage that historically don't close from there
- **Seasonal** — quarter-end compression patterns
- **Product/segment** — structural close-rate issue in specific product or segment
**Step 3 — Pattern confidence gate**
Only surface a pattern classification when:
- Rep-level: ≥3 deals from same rep, or same rep in ≥2 consecutive quarters
- All other categories: ≥3 deals matching the pattern
If below threshold: "Insufficient data to classify as systemic — noted as isolated."
**Step 4 — Rep call accuracy scorecard** (if rep data available)
```
Rep Submitted Actual Variance Accuracy
[name] $XXXk $XXXk −$XXk XX%
```
---
## Output
```
FORECAST VARIANCE ANALYSIS — [Quarter/Period]
[HubSpot ✓ live — as of YYYY-MM-DD] [Confidence: High/Moderate]
Total variance: −$XXXk (−XX% of submitted forecast)
Root cause classification:
Primary: [Rep-level / Deal-size / Stage-entry / Seasonal / Product]
Secondary: [if applicable]
Pattern evidence:
"[Pattern description]" — observed in [N] deals over [N] quarters
[Confidence: High/Moderate/Low — based on sample size]
Rep accuracy scorecard:
[table if rep data available]
One-off variances (not classified as patterns):
[Deal name, amount, what happened — 1 line each]
[DRAFT — RevOps internal] [Confidence: High/Moderate]
```
---
## Reference Files
| File | Purpose |
|------|---------|
| `references/reasoning-blueprint.md` | Problem classification taxonomy, domain heuristics, common failure modes, and expert judgment patterns for this skill |
## Security & Permissions
**Network access:** None direct — all external data access is mediated by host-provided MCP connector tools (HubSpot, CS platform, Slack, Linear). This skill makes no direct outbound HTTP calls.
**Filesystem scope:** None — this skill does not read or write local files. All data is provided at runtime via parameters or MCP connector responses.
**Subprocess execution:** None.
**Dynamic code execution:** None — pseudocode in this skill represents the logic contract and is not executed at runtime.
**Data sensitivity:** Inputs may contain confidential deal and pipeline data. Handle with RevOps-level confidentiality.
## Trust & Verification
**Input trust model:** All user-provided parameters are treated as untrusted at intake. Numeric inputs are validated for plausible range before use in calculations. String inputs are not evaluated as code.
**Output trust model:** All outputs are proposals or analytical inputs — no outputs constitute approved decisions, revenue commitments, or system actions without explicit human confirmation.
**Connector data:** Data retrieved via MCP connectors is treated as read-only observed state. Timestamps and data-as-of labels are applied to all connector-sourced values per G6.
**Write-tier confirmation:** Any proposed write to HubSpot, Linear, or Slack is surfaced as a draft requiring explicit user confirmation before execution.
## Guardrails
- G1: Forward-looking projections from variance analysis require qualification
- G5: Rep accuracy scorecard is analytical input — manager owns the coaching response
- G6: State data-as-of for all historical pulls