renewal_forecasting v1.0.0

name: renewal_forecasting description: Forecast customer renewals account by account: score usage, outcome, stakeholder, support, and commercial signals, place each renewal in a confidence category with stated evidence, run save plays by risk tier, and grade the frozen forecast every quarter with WAPE, signed bias, and risk detection rate. Triggers on "renewal forecast", "will they renew", "ATR", "available to renew", "renewal risk", "forecast accuracy", "commit forecast", "save play", "at-risk renewals", or a quarterly renewal review.

Renewal Forecasting

Purpose

A renewal forecast is a promise a business plans against. The weak version sums the contracts expiring in a quarter, shades the total by gut feel, and presents one number. That number cannot be defended account by account, it counts expansion hope as renewal, and it gets graded against a forecast that was edited all quarter, so nobody learns anything when it misses.

This skill builds the stronger version. Every renewal gets two separate calls, an outcome call and a value call, because accounts renew smaller as often as they churn outright. Every call sits in a confidence category with entry criteria based on observable evidence, a date, a person, and a document, never on how a rep feels. Work is scheduled from the decision date, which is the renewal date minus the notice period, because that is the last day the outcome can still change. And the forecast is frozen at the start of the quarter so it can be graded honestly at the end.

Workflow

1. Build the ATR list by decision date

1. List every contract that reaches its decision date in the forecast period. ATR means available to renew: the full contract value that could renew, before any judgement about whether it will.
2. Compute the decision date per contract as renewal date minus notice days, both taken from the contract itself. Bucket ATR by decision quarter. A contract renewing in February on 90 days notice is decided in the prior quarter, and planning by renewal date hides that.
3. Record per account: ATR, renewal date, notice days, owner, and segment. An account with no named owner is flagged until one is set.

2. Score the signals

Score five groups, each 0 to 100, weighted: usage 30%, outcomes 20%, stakeholder coverage 20%, support 15%, commercial 15%. The full signal lists, thresholds, and hard flags live in references/signal-scoring.md. The rules that shape the score:

1. Score against the account's own baseline and segment, not the whole book.
2. Weight trend over level. Usage down a third in 30 days says more than a high total that is falling.
3. Watch concentration. An account whose usage sits in one person has a single point of failure, whatever the total says.
4. Never score a group you cannot measure as healthy. Mark it low confidence or leave the account unscored and name what is missing.
5. Hard flags override the total: notice given, data export started, champion and buyer both gone, a severe ticket open and unowned, a failed payment near the decision date. Any one puts the account on the at risk list.

Bands: Green 70 and up, Amber 50 to 69, Red under 50.

3. Place each account in a confidence category, with evidence

Categories follow the standard forecast set, adapted for renewals. Entry requires the evidence listed. If the evidence is not there, the account does not enter, whatever its score says.

• Closed: renewal signed. Evidence: the signed document.
• Commit: the buyer has confirmed renewal in words or writing, and paperwork is in procurement or legal, and the score is 50 or better, and no blocker is unresolved. Evidence: the confirmation date, who gave it, and where the paperwork sits.
• Best Case: the champion confirms intent and the budget is confirmed, but paperwork has not reached procurement or legal, or one blocker is still open.
• Pipeline: no explicit confirmation yet. The default home for accounts early in their window and for mixed signals.
• At Risk: score under 50, or any hard flag, without notice given. These accounts carry a save play, see step 5.
• Omitted: the customer gave notice, or the decision date passed with no signed renewal and no written extension. Excluded from expected value, kept in the ATR bridge so the loss stays visible.

One more rule: an account whose decision date is inside 30 days with paperwork not started cannot sit above Best Case.

4. Make the value call and roll up

1. Get base rates from your own history: for each category, the share of ATR that actually renewed for accounts frozen in that category, from graded past quarters. The worked table is in references/worked-forecast.md. Never copy rates from another company or a vendor page. If you have no graded history, report ATR by category with no expected values, freeze the quarter, grade it, and use its rates next quarter.
2. Set a value fraction per account when a partial renewal is known or likely: the share of ATR it would renew at if it renews. A confirmed seat cut to 80% is a value fraction of 0.8, and it applies separately from the outcome category.
3. Expected ARR per account is ATR times the category base rate times the value fraction. Run it with python3 bin/renewal_forecast.py forecast accounts.csv --base-rates rates.json. The tool scores, categorises, computes decision dates, and rolls up.
4. Report the roll up as a bridge: total ATR, expected ARR, Commit ATR, at risk ATR (At Risk plus Omitted), and the split by decision quarter. Keep expansion out of this number entirely. Gross revenue retention, (starting ARR minus churn minus contraction) divided by starting ARR, is the measure this forecast feeds. Net revenue retention adds expansion back in, and mixing the two in one forecast hides contraction behind hoped for growth.

5. Run save plays by tier

Full plays live in references/save-plays.md. The shape:

• Red (under 50 or hard flagged): owner and manager named the same day, customer call inside 48 hours, risk reason coded from the customer's own words, a dated save plan that fixes the cause before any commercial lever is offered.
• Amber (50 to 69): outreach inside two weeks naming the specific signal, the single largest blocker fixed, stakeholder map rebuilt if the account is single threaded, renewal path agreed with dates worked back from the decision date.
• Green (70 and up): standard cadence, plus one early confirmation of budget and procurement path. Green accounts still churn on missed notice windows.

Code every at risk account with one primary reason: product-gap, value-not-realised, champion-loss, budget, procurement, support, pricing, competitor, merger, or payment. Report the at risk stack in dollars by reason, not as an account count.

6. Freeze, then work the quarter

1. Freeze the forecast at the start of the quarter: account, ATR, category, score, expected ARR, flagged status, and flag date, stored read only. Use the format in references/sample-frozen.csv.
2. Run a weekly forecast call inside the quarter on movement only: which accounts changed category, on what evidence, and which red plays moved. Log every change.
3. Start renewal work 90 to 120 days before the decision date for large accounts, 60 to 90 for smaller ones. A first touch 30 days out is a reaction, not management.

7. Grade the quarter and recalibrate

Follow references/forecast-review.md. Grade the frozen file with python3 bin/renewal_forecast.py grade frozen.csv and review six numbers: headline accuracy, WAPE, signed bias, commit hit rate, risk detection rate, and flagged save rate, plus the calibration table by category. Then take the three largest variances account by account, update base rates from the calibration table pooled over four quarters, and change at most one scoring weight or threshold per quarter, with the reason written down.

Output Contract

A forecast run produces:

• A per account table sorted by decision date: account, decision date, score, band, category with its evidence, ATR, value fraction, expected ARR, owner, and risk reason where coded.
• A roll up: total ATR, total expected ARR, Commit ATR, at risk ATR, implied gross retention on the ATR, and ATR and expected split by decision quarter and by category.
• A save list: every Red and Amber account with its play owner, start date, next action, and exit criteria.
• A coverage note: how many accounts have all five signal groups measured, and which accounts are unscored or low confidence and why.
• At quarter end, a review pack: the six grading metrics against last quarter, the calibration table, the three largest variances with causes, and the recalibration changes made.

Operating Rules

• Evidence beats score, and score beats opinion. A customer who gave notice is Omitted at any score. A rep's confidence with no confirmation, no budget, and no paperwork is Pipeline at any score.
• Two calls, always separate: whether it renews, and at what value. A forecast that only answers the first misses the partial loss, which is the common loss shape on larger accounts.
• Never grade an edited forecast. If there is no frozen snapshot, say the quarter cannot be graded and start freezing now.
• Base rates and accuracy targets come from the team's own graded history only. Do not present a vendor benchmark, or the sample rates in the references, as this book's expected performance. The sample numbers are labelled sample data so the method can be run end to end.
• Keep expansion out of the renewal forecast. Report it as its own line, signed expansion only, or the retention picture is fiction.
• Contract facts come from the contract: renewal date, notice period, auto renew terms, price clauses. If the contract text is not available, mark the field unverified and say so.
• A discount is the last lever in a save play, never the first. Diagnose the reason in the customer's words before any commercial offer, and log the reason code either way.
• This skill is forecasting and process support. Contract interpretation questions, disputed notice, and termination rights go to legal, and the forecast says so when one appears.