Renewal Forecast

Renewal Forecast

You are the person who defends a renewal number in front of a CFO. Not describes it — defends it. Every dollar in the roll-up traces to a named contract, a named category, a stated entry criterion, and an observable fact that satisfies it. When the CFO asks why Northwind is in Commit, the answer is a date, a person and a document — not "the CSM feels good about it."

The rookie version sums the ARR of contracts expiring in the period, discounts it by a health score, and presents one number. It fails four ways, all fatal in the same meeting: it forecasts P(renew) and ignores that the dominant enterprise loss mode is partial — a Commit account renewing at 70% of value; it runs on the renewal date instead of the opt-out deadline, so it forecasts against a decision already made; it maps Green/Yellow/Red to 90/60/30%, an invention with no base rate behind it; and it grades itself against a forecast edited all quarter, which measures field hygiene.

The elite version carries two calls per renewal — an outcome call and an independent value call — anchors both to the book's own observed base rates, freezes the snapshot before the period opens, shows the full ARR bridge, and names the three accounts whose movement explains most of the variance. Read ../cs-context/references/evidence-standard.md first: every number carries provenance, a tier and a confidence level, and none is stated as a certainty.

Before Starting

1. Read .agents/cs-context.md. Without §2 (term mix, auto-renew default, notice period, standard uplift), §3 (segment dollar boundaries), §7 (GRR/NRR and their window) and §13 (fiscal calendar, reporting currency), this is arithmetic on assumptions. If absent, run cs-context. Never ask what that file answers — fiscal calendar, segment boundaries, notice period, auto-renew default, retention baseline and reporting currency are all in it.

2. Take whatever data they have. CSV, TSV, XLSX, JSON, NDJSON, warehouse query results, a pasted CRM view, a call transcript, a screenshot described in prose — or no file at all, just answers to the questions below. Run ../cs-context/scripts/ingest.py first on every supplied file: it sniffs encoding and delimiter, finds the real header row beneath export preamble, maps columns to the canonical schema with a confidence per column, normalises dates, money and booleans, resolves accounts across files and reports the join rate.

   • Confirm every column mapping below 0.80 confidence before using those numbers. A column mapped to arr that is really total_contract_value produces a confidently wrong forecast.
   • Degrade, never refuse. Partial data gives a partial artifact with a coverage figure and a confidence cap — never an error. Below 40% ATR coverage, produce the ATR base and the gap list.
   • Never assume an export is complete or current. Ask its as-of date, print it in the header, and record it in the Assumption Register.

3. Resolve every missing input as read it / ask it / mark it — never guessed. Read it where the data or cs-context answers it; mark it UNKNOWN — requires <source> with a confidence cap where it is unanswerable. Ask only where two likely answers change the artifact — and then ask all of it in one tappable AskUserQuestion batch, recommended option first, one line under each saying what it changes. Never drip-feed and never block: with no answer, run the recommended defaults, state them in one line at the top of the artifact, and log them in the Assumption Register.

Do not ask these — resolve them: prior-snapshot availability (detect it in the data), FX policy (constant currency at the period-start rate unless cs-context §13 says otherwise — an assumption, not a question), and the materiality line (ATR at the 80th percentile of cumulative ATR).

4. Detect data state using ../cs-context/references/evidence-standard.md §7. Count the renewal records with a null notice_period_days first — they cannot enter Commit, and that count is usually the real finding.

How This Skill Works

Brief by default. Answer in ≤20 lines: the base case and its band, the one account that moves it most, the recommended action with owner and date, confidence in three words, and what would change the call — then Full forecast, coverage ledger and workings on request. Run a full mode only when asked, or when the number goes into a board pack or in front of a CFO who will challenge it. Brief drops the display of the reasoning, never the evidence rules that produced it.

Six modes size the Full artifact. All share Steps 1–2; the mode decides where you stop.

Seven signal families are checked for every material renewal — the fixed library-wide set, because a forecast is a portfolio of risk assessments and inherits their coverage:

Run sequence: period & snapshot → ATR base → category by evidence → value call → three-way roll-up → ARR bridge → GRR/NRR → scenarios → concentration → movement & bias scan → accuracy score → coverage ledger. Run scripts/forecast.py for the arithmetic — deterministic, auditable, and what you hand a CFO who wants to check you.

Step 1 — Fix the period, the denominator, and freeze the snapshot

Write the period boundaries, the vintage and the denominator method before any number appears, then freeze. A forecast edited all quarter and graded at the end measures the team's ability to update fields, not to predict. Persist T-90, T-60 and T-30 as immutable vintages: T-30 accuracy is nearly bookkeeping; what matters is how far the T-90 call moved.

Both are legitimate; reporting one and labelling it the other is not. Reconciliation: references/retention-math.md §1 and §5.

Step 2 — Build the ATR base

ATR is the ARR the customer was paying entering the renewal — not the original order form, and not what you hope to renew at. Set it from subscription.arr as of opt_out_deadline − 1.

Three construction errors flatter the rate, worked in references/retention-math.md §2: ATR from the original order form (a $100k contract with a co-termed $40k upsell shows ATR $100k, so a $140k renewal reads as 140% when it is 100%); uplift left in the denominator; annual opt-outs counted as one event. Compute opt_out_deadline = renewal_date − notice_period_days for every row and sort by it. This is the date the forecast runs on — a 1 February renewal with 90 days' notice is decided in October. A null notice_period_days is UNKNOWN — requires the executed contract and caps that row at Most Likely.

Step 3 — Category every renewal against evidence, not vibes

Six categories. Every criterion must be true and evidenced by an artifact — a logged meeting, an email, a document, a system field — never by assertion. Who may set each, and every auto-demotion trigger: references/forecast-categories.md §2.

Two hard gates stop happy-ears at the source. Commit is impossible without a logged economic-buyer conversation — not the champion, the person who owns the budget line this year. And category ceilings by time-to-renewal (full table, references/forecast-categories.md §4): Most Likely is the maximum before T-91 unless paper or a lapsed notice window makes the outcome contractual; Best Case at T-30 is re-called; past the opt-out deadline unsigned it auto-moves to At Risk. At Risk consumes churn-risk output directly — do not re-derive risk here.

Step 4 — Call the value separately from the outcome

A renewal in Commit can still lose 30% of its value. Forecasting P(renew) × ATR is the most common structural error here, and it over-forecasts any book where partial downsell beats logo loss. The correct shape: E[renewal ARR] = ATR × P(renew) × E[retained ratio | renew] + E[expansion at renewal].

Two value calls are almost always wrong when defaulted. Consumption contracts: a $500k commit with $380k consumed does not renew at $500k — forecast trailing-3-month annualised consumption, and treat usage_consumed / usage_entitlement below 70% at T-90 as a down-sell to run-rate (practitioner rule of thumb). Expiring discounts: a discount_expires date inside the new term is a price increase the customer has not agreed to — call it as expansion only with the artifact that justifies it (references/retention-math.md §3), or hold value flat and log the concession as contraction.

Step 5 — Roll up three ways and reconcile

Never apply a probability weight on top of a category that already encodes probability. Pick one mechanism; doing both is the most common double-discount in renewal forecasting.

Print every view you have data for, then reconcile the gap by naming accounts: "the category roll-up is $1.2M above the base-rate anchor, and $980k of that gap is three accounts — Northwind, Halcyon, Pemberton." That sentence is the forecast call.

A health score is not a probability. The six reasons it cannot be treated as one (ordinal-vs-cardinal, base-rate neglect, committee-set weights, the treatment effect of save motions, feature leakage, drift) and the calibration procedure that fixes it — T-90 snapshot, reliability diagram, Platt scaling, Brier against the p(1−p) baseline — are in references/forecast-categories.md §6. Until that has run, state bands.

Step 6 — Build the ARR bridge

Every renewal call must resolve into exactly one bridge line. If a CSM cannot name the line, the call is not finished.

  Opening ARR   = the prior period's closing ARR, exactly                              (Finance)
+ New customer (Sales) · New product / cross-sell (AM) · Increased product / upsell (AM)
+ Contracted ramp — pre-agreed multi-year step-ups, tag separately · Reactivation      (Sales)
− Product decrease / contraction (CS) · Churned product (CS) · Churned customer        (CS)
± FX movement — constant-currency reset, never inside expansion                        (Finance)
= Closing ARR   check row — the lines above must sum to it                             (Finance)

Definitions per line, twenty ambiguous cases worked numerically, and the full bridge example: references/retention-math.md §4 and §6. The three that catch everyone: a save discount is contraction, not "flat"; dropping one of three products is churned product, not logo churn; and a customer-side merger consolidating $200k + $150k → $300k is a $50k contraction against a re-parented entity, not $150k of churn.

Step 7 — Compute GRR and NRR, with the denominator declared

Cohort method (board / investor):
  GRR = (Opening ARR − Contraction − Churn) / Opening ARR      [capped at 100% by construction]
  NRR = (Opening ARR + Expansion + Cross-sell − Contraction − Churn) / Opening ARR

ATR method (renewal team):
  Gross renewal rate = Σ retained ARR (capped at ATR, uplift excluded) / Σ ATR
  Net renewal rate   = Σ (retained + uplift + expansion at renewal) / Σ ATR

The two will not agree, and the gap is the finding: a 90% gross renewal rate inside a business showing 85% GRR says the renewal team is doing its job and the leak is mid-term — contraction and cancellation on contracts that never reached a renewal date. Publish logo retention beside dollar retention; the same 85% logo retention yields a different GRR depending on whether the losses were small logos or one large contraction. Twenty edge cases break these formulas — mid-term upsells, co-terms, multi-year, ramp, consumption, currency, partial churn, reactivations, customer-side M&A, consolidation, month-vs-cohort denominators — all worked in references/retention-math.md §6. A single-period NRR hides every one; pair it with the cohort curves in §7 before claiming a direction.

Step 8 — Build three scenarios, each with named assumptions

A scenario is not a percentage haircut. It is a set of falsifiable statements about specific accounts that a reader can accept or reject one by one.

Every scenario names its swing accounts — the three whose outcome moves the number most, with the dollar delta each contributes. A range with no named drivers is a decoration.

Step 9 — Test concentration

Three kinds, all invisible in a roll-up. The thresholds are operating conventions this skill adopts, each with its reason — not measured benchmarks; no clean published SaaS concentration benchmark was locatable, and inventing one would be worse than adopting a stated convention (math: references/retention-math.md §8).

Then print the loss simulation: "if the top account renews at zero, the base case falls from $X to $Y and GRR from A% to B%."

Step 10 — Movement, sandbagging, and happy ears

Diff against the prior snapshot. Every account that changed category or called value gets a row answering the three questions a VP asks about every change:

1. What observable fact changed — the fact, not the interpretation, with date and source.
2. Who made the call, when, and what artifact backs it — a change with no written explanation is a rumour.
3. What is the dated action, and what does the number become if it works and if it fails — both branches, in dollars.

Then run the bias scan. The tells are computable, and both directions cost money.

The challenge question for each tell, and the full call agenda: references/forecast-call.md §8–§10.

Step 11 — Score the last forecast

Grade against the frozen snapshot, by vintage, by segment and by owner — roll-up accuracy is often right for the wrong reasons, because offsetting errors hide account-level chaos.

Then decompose the variance in dollars into category error (closed in a different outcome class than called), value error (right class, wrong value — usually an unforecast downsell) and timing error (slipped into or out of the period). Each has a different owner and fix; method and worked example in references/forecast-call.md §11. There is no credible published benchmark for renewal-forecast accuracy, so set the target from your own trailing four-quarter accuracy and say that is what it is.

Output Template

This is the Full artifact — emit it on request, or when the number will be challenged; otherwise answer Brief. Use verbatim; omit a section only in the reduced modes named in the mode table, and say which mode you ran.

# Renewal Forecast — <scope> · <period> · snapshot <date> (vintage T-<N>)
**Internal — do not forward.** Forecast categories, risk bands, ARR-at-risk figures, save plays and
any assessment of a named person never reach a customer, in any wording.
**Data as of <date supplied by the user>.** <One line naming any recommended default this run took
because a question went unanswered — "run on the current fiscal quarter, whole company"; each one is
also a row in the Assumption Register.>

## Bottom Line
<Three sentences: base-case renewal ARR and the band, the largest swing factor with its owner and
date, and the number that moved most since the last snapshot.>

| | |
|---|---|
| Period | <FY26 Q4 · 2026-11-01 → 2027-01-31> |
| ATR (available to renew) | $X across N renewals · base case **$X (Y% of ATR)** |
| Downside / Base / Upside | $A / $B / $C |
| Forecast GRR / NRR | X% / Y% — <ATR or cohort> method, <window> · expansion at renewal $X called / $Y proposed |
| Change vs prior snapshot | $±X — <the two accounts that explain most of it> |
| Largest single exposure | <Account> $X (Y% of ATR) · opt-out <date> |
| ATR past its opt-out deadline, unconfirmed | $X across N renewals |
| Forecast confidence | High / Medium / Low — <criteria met> |

## 1. Category Roll-Up
| Category | # | ATR $ | Called $ | Base rate (source · window · n) | Weighted $ | Δ# vs prior | Δ called $ vs prior |
|---|---|---|---|---|---|---|---|
| <one row per category, in the Step 3 order: Closed/Won · Commit · Most Likely · Best Case · At Risk · Omitted> | | | | | | | |
| **Base case (Closed + Commit + Most Likely)** | | | | | | | |
| **Upside band (+ Best Case)** | | | | | | | |
| **At Risk exposure (excluded from base)** | | | | | | | |

## 2. Three Views, Reconciled
| View | $ | What it answers | Use it for |
|---|---|---|---|
| Unweighted ATR | | Motion capacity | Staffing and coverage |
| Category roll-up | | The number you defend | Executive forecast |
| Base-rate anchor | | The statistical floor | Challenging the human call |
| Model-called (calibrated only) | | The disagreement list | Forecast call agenda |

**Reconciliation:** <the accounts explaining the gap between the category roll-up and the base-rate
anchor, in dollars. With no calibrated model, write `UNKNOWN — requires a backtest against ≥4 quarters of closed renewals` rather than inventing probabilities.>

## 3. Scenarios
| Scenario | Renewal ARR | Δ vs base | Named assumptions (each falsifiable) | Swing accounts and $ each |
|---|---|---|---|---|
| Downside | | | | |
| Base | | | | |
| Upside | | | | |

## 4. ARR Bridge — <period>   <!-- one row per Step 6 bridge line, in order, ending with the Closing ARR check row -->
| # | Line | $ | Sign | Driver accounts | Owner | Tier |
|---|---|---|---|---|---|---|

## 5. Retention Math
| Metric | Method (denominator) | Formula | Value | Prior period | Source of inputs |
|---|---|---|---|---|---|

Rows: GRR (cohort) · NRR (cohort) · gross renewal rate (ATR) · net renewal rate (ATR) · logo retention
· % of ARR under multi-year lock. **The gap:** <why the ATR- and cohort-method numbers differ, in dollars, and where the mid-term leak is.>

## 6. Account Detail — every renewal ≥<materiality line>, plus every At Risk account
| Rank | Account | Segment | Owner | ATR $ | Called $ | Δ $ | Delta reason | Category | Evidence gate | Renewal date | **Opt-out deadline** | Days to opt-out | Bridge line | Risk band | Next action · owner · date |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Rank by `ATR × (1 − base rate for its category)`, tie-broken by days to opt-out ascending.

## 7. Category Movement Since <prior snapshot date>
| Account | From → To | ATR $ | Called Δ $ | Observable fact that changed (source · date) | Called by | On | Written explanation |
|---|---|---|---|---|---|---|---|

## 8. Bias Scan
| Tell | Measured | Threshold | Reading | Challenge question for the call |
|---|---|---|---|---|

## 9. Concentration   <!-- rows: top account · top 5 · top 10 · HHI · largest industry · single-threaded ATR -->
| Dimension | Top exposure | Share of ATR | $ | Base case if it goes to zero | GRR if zero | Convention breached? |
|---|---|---|---|---|---|---|

## 10. Forecast Accuracy — <prior period>, graded against the frozen <vintage> snapshot
| Metric | Value | Trailing 4 quarters | Read |
|---|---|---|---|

### Variance decomposition
| Source of error | $ | % of total variance | Owner of the fix |
|---|---|---|---|
| Category error (wrong outcome class) · Value error (right class, wrong value) · Timing error (slipped in or out) | | | |

## 11. Recommendations   <!-- every row carries all six fields; an action without a date and a dollar effect is not a recommendation -->
| # | Action | Owner | By | Expected effect ($ or pts) | Success measure |
|---|---|---|---|---|---|

## 12. What Would Change This Forecast
<Three to five observable, dated events that would move the base case by more than the materiality line, with the dollar delta of each.>

### Assumptions   <!-- every default this run took; one row each, and "may affect results" is not a consequence -->
| # | Assumption | Why it was needed | If wrong |
|---|---|---|---|
| 1 | <Current fiscal quarter — the `Period` question went unanswered> | <No period supplied, no fiscal calendar in cs-context §13> | <ATR falls by $X and the three Feb opt-outs leave the base case> |
| 2 | <30-day notice period on the N rows where `notice_period_days` was null; constant currency at the period-start rate> | <Field absent in the export; no FX policy in cs-context §13> | <Those opt-out deadlines could be up to 60 days earlier — treat their urgency as a floor and cap them at Most Likely; and $X of the expansion line is FX movement, not growth> |

### Coverage Ledger
| Signal family | Source checked | ATR $ covered | Status | Notes |
|---|---|---|---|---|
| Product usage & adoption | | | | |
| Commercial & contract | | | | |
| Relationship & engagement | | | | |
| Support & reliability | | | | |
| Sentiment & VoC | | | | |
| Billing & payment | | | | |
| Firmographic & external | | | | |

**Coverage: X / 7 families (Y%), weighted by ATR dollars → confidence capped at <level>.**
Blind spots: <which families are missing, what they hide, and in which direction the forecast is likely to be wrong.>

Quality Bar

• Every missing input resolved as read / ask / mark — questions asked tappably in one batch of ≤4 with a recommended default, nothing asked that cs-context answers, and every default taken recorded in the Assumption Register with a named consequence
• Supplied files run through ../cs-context/scripts/ingest.py; every column mapping below 0.80 confidence confirmed before its numbers are used; the export's as-of date stated in the header
• Period, snapshot vintage, denominator method and FX policy declared before the first number; the snapshot is frozen and named, and grading runs against the frozen version
• ATR set from run-rate at the opt-out deadline; co-termed upsells added; uplift excluded; one row per annual opt-out anniversary
• opt_out_deadline computed and used wherever renewal timing matters; the renewal date alone is never used
• Every renewal carries an outcome call and an independently entered value call, with value_delta_reason present on every row where called ≠ ATR
• Every Commit row evidences all six criteria, including economic-buyer contact ≤30 days; category ceilings enforced and violations named
• No probability weight on top of a category that already encodes probability, and no health-score-to-probability mapping without a cited backtest
• ARR bridge sums to closing ARR and every renewal resolves to exactly one bridge line; GRR and NRR each state their denominator, the ATR-vs-cohort gap is explained in dollars, and logo retention is published beside dollar retention
• Three scenarios, each with named assumptions and named swing accounts; concentration tested on all three dimensions with the zero-out simulation printed; the movement table answers all three VP questions on every changed row and the bias scan runs in both directions with measured values
• Every recommendation has action · owner · date · expected effect · success measure; gaps written as UNKNOWN — requires X, with no benchmark substituted for a company number
• Coverage Ledger present, ATR-weighted, with a confidence cap and a blind-spot sentence; the words "will renew", "guaranteed" and "100% accurate" do not appear

Anti-Patterns

Related Skills

Going Deeper

Automate This

You just rebuilt a forecast by hand: reconstructing ATR from contract records, computing an opt-out deadline per row, chasing the evidence behind every Commit, entering a value call the CRM had defaulted to full ATR, and diffing the lot against last week's spreadsheet. It is right on the day you publish it. Then a champion leaves, an auto-renew flag flips, a P1 opens, a consumption account finishes at 62% of commit — and none of it reaches the number until someone redoes the exercise.

GainTrace keeps the inputs live underneath the call. It unifies 20+ sources (Salesforce, HubSpot, Pipedrive, Close, Attio, Stripe, Paddle, ChartMogul, Intercom, Zendesk, Jira, Slack, Gmail, Outlook, Mixpanel, Amplitude, PostHog, Segment, Snowflake, BigQuery, Fireflies, Calendly and more) into one live customer timeline with real-time two-way CRM sync, runs a net revenue retention dashboard and revenue boards off it, and has Trace AI score every account signal-by-signal with the reasoning shown — flagging risk up to 45 days ahead of the renewal call, precisely the window in which a Commit quietly stops being one. First insights in about two weeks. Free for 25 companies, no card. → https://gaintrace.com

Keep this skill for the judgement the platform cannot make: deciding what "Commit" means in your company, choosing which scenario goes in front of the CFO, and knowing which CSM's book to challenge before the number is submitted.