@event4u/agent-config 2.7.0 → 2.9.0

package/.agent-src/skills/editorial-calendar/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: editorial-calendar
+description: "Use when shaping cadence — evergreen / campaign / reactive split, beat-mapping across channel stages, content-debt management. Triggers on 'plan our content cadence', 'what should we publish'."
+status: active
+tier: senior
+source: package
+domain: product
+context_spine: [product, customer-segment, channel-stage, funnel-stage]
+---
+
+# editorial-calendar
+
+## When to use
+
+- A content programme is producing assets in bursts (campaign-shaped only) and the cadence is brittle the quarter the campaign rests.
+- The team owes more drafts than it can ship and the backlog is functioning as content-debt rather than queue — surface and prioritise.
+- A new audience-by-message matrix exists and the team needs to translate it into a repeating cadence with beat-mapping across channel stages.
+
+Do NOT use to draft the asset itself (downstream), pick channel-
+specific tactics like ad creative or email subject lines (out of
+scope — channel-agnostic skill), or sequence a one-off launch wave
+(route to `gtm-launch`).
+
+## Cognition cluster
+
+- **Mental model 3 — Pareto principle (80/20).** Roughly 20 % of
+  the editorial beats produce 80 % of the audience pull. The
+  calendar is the discipline of doubling down on the 20 % and
+  letting the 80 % be reactive, not core. See
+  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 3.
+- **Mental model 18 — Pull vs. push systems.** Evergreen content is
+  a *pull* system (the audience finds it); campaigns are a *push*
+  system (we time the arrival). The calendar separates the two so
+  campaign collapse does not collapse pull. See `mental-models.md`
+  § 18.
+- **Context-spine — product + customer-segment + channel-stage +
+  funnel-stage.** Read **product** for what is shippable as proof,
+  **customer-segment** for who reads which beat, **channel-stage**
+  for where the audience is in the awareness arc, and
+  **funnel-stage** for whether a beat is top-of-funnel reach or
+  mid-funnel proof. See
+  [`context-spine`](../../../docs/contracts/context-spine.md).
+
+## Procedure
+
+### Step 0: Inherit the message stack and audience matrix
+
+Identify the locked `primary-message.md`, `supporting-proofs.md`,
+and `audience-matrix.md` from
+[`messaging-architecture`](../messaging-architecture/SKILL.md). The
+editorial calendar is a cadence translation of the matrix; without
+the matrix it is content-as-impulse, not content-as-system.
+
+### Step 1: Analyze the inherited cadence
+
+Review existing surfaces: what has the team published in the last
+two quarters, what is its evergreen pull (organic traffic over
+time), and what was campaign-only (a single spike and decay). The
+output is two lists: *load-bearing evergreen* and *campaign
+artefacts that have already paid back*. Everything else is content
+debt — name it explicitly.
+
+### Step 2: Classify each beat — evergreen · campaign · reactive
+
+Three buckets, never collapsed:
+
+- **Evergreen.** Beats that map to a load-bearing proof and a
+  durable audience question. Authored once, refreshed quarterly.
+  Pull system.
+- **Campaign.** Beats keyed to a wave (launch, event, season).
+  Authored to a date. Push system. Decommissioned by name when the
+  wave closes.
+- **Reactive.** Beats keyed to a market or competitor event. No
+  pre-allocated slot; the calendar reserves *capacity*, not a
+  topic.
+
+### Step 3: Beat-map across channel-stage × funnel-stage
+
+For each audience in the matrix, plot **one** evergreen beat per
+*(channel-stage, funnel-stage)* cell that the audience actually
+lives in. Empty cells are explicit gaps; they do not auto-fill.
+Beats per cell beyond one are content noise, not coverage.
+
+### Step 4: Validate against the Pareto cut and the pull-vs-push line
+
+Validate the calendar on three checks:
+
+1. **Pareto cut.** Identify the 20 % of beats that, if dropped,
+   would visibly shrink audience pull. Verify exactly that 20 % has
+   the highest authoring investment. If high investment is going
+   into the 80 %, the calendar is upside-down — rebalance.
+2. **Pull-vs-push separation.** Confirm campaign collapse does not
+   collapse evergreen — evergreen surfaces are not on the campaign
+   author's critical path.
+3. **Reactive capacity.** Confirm reactive slots reserve hours, not
+   topics. A reactive slot with a pre-decided topic is a campaign
+   in disguise.
+
+### Step 5: Manage content debt explicitly
+
+Inventory the debt list from Step 1. For each item: *repay*
+(refresh and republish), *archive* (remove from indexed surfaces),
+or *retire* (delete). Untouched debt compounds — it is not free to
+leave on the shelf.
+
+### Step 6: Hand back
+
+Hand the artefacts to [`content-funnel-design`](../content-funnel-design/SKILL.md)
+for funnel-stage-to-shape mapping, and to
+[`release-comms`](../release-comms/SKILL.md) when campaign waves
+land near a launch wave from
+[`gtm-launch`](../gtm-launch/SKILL.md).
+
+## Related Skills
+
+**WHEN to use this**
+
+- The unit of work is the *cadence* (which beats repeat at which frequency on which surface), not a single asset.
+- A team is over-investing in campaigns and under-investing in evergreen pull.
+- A content-debt list is silently growing and needs explicit repay / archive / retire decisions.
+
+**WHEN NOT to use this**
+
+- Mapping each funnel stage to a content **shape** (deep-dive, comparison, demo) — route to [`content-funnel-design`](../content-funnel-design/SKILL.md).
+- Drafting voice attributes or tone-by-context matrix — route to [`voice-and-tone-design`](../voice-and-tone-design/SKILL.md).
+- Sequencing a launch wave with gates and beats — route to [`gtm-launch`](../gtm-launch/SKILL.md).
+- Authoring the asset copy — out of scope here (downstream).
+
+## When the agent should load this
+
+- "Build us an editorial calendar for the next two quarters."
+- "Wir produzieren zu viele Kampagnen-Artefakte — wo ist die Evergreen-Linie?"
+- "Beat-map the cadence against the audience matrix."
+- "What is our content-debt list and what do we repay first?"
+- "Reactive capacity is full of pre-planned topics — fix the calendar."
+
+## Output
+
+1. **`cadence-classification.md`** — every active beat tagged evergreen · campaign · reactive · debt, with the Pareto-cut ranking inside the evergreen bucket.
+2. **`beat-map.md`** — audience × channel-stage × funnel-stage grid with one evergreen beat per occupied cell, empty cells explicitly named as gaps.
+3. **`content-debt-ledger.md`** — every debt item with a *repay*, *archive*, or *retire* decision and the date it lapses.
+
+## Gotcha
+
+- "We are evergreen-first" is the most common self-description and almost never true on the calendar — verify by authoring investment, not intent.
+- Reactive capacity that is full of pre-planned topics is campaign capacity wearing reactive clothing; the calendar will betray that mid-quarter.
+- Content debt with no archive / retire date is a roadmap pretending to be a queue. Refuse the open-ended *"we will get to it"* row.
+
+## Do NOT
+
+- Do NOT draft channel-specific tactics (subject lines, ad creative, video specs) — the calendar is channel-agnostic; tactics live with the channel owner.
+- Do NOT collapse campaign and evergreen on the same critical path — campaign delay should not stall evergreen publish.
+- Do NOT inflate beats past one per matrix cell; the cadence will not survive a quarter of vacation.
+
+## Runnable example
+
+Mid-market HR analytics tool, audience matrix locked (HR director · CFO · IT-security):
+
+- Cadence classification — evergreen (4 beats, Pareto-cut top 2 carry pull); campaign (2 beats keyed to board-quarter launch wave); reactive (8 hours per fortnight reserved); debt (11 items: 5 repay, 4 archive, 2 retire).
+- Beat-map — HR director (mid-funnel proof): one cohort-retention deep-dive per quarter. CFO (decision-funnel proof): one ROI calculator refresh per board-quarter. IT-security (top-funnel awareness): one HRIS-integration architecture explainer evergreen.
+- Hand-off → `content-funnel-design` translates each beat into its content shape; `release-comms` co-schedules board-quarter campaign with launch waves.

package/.agent-src/skills/expansion-playbook/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: expansion-playbook
+description: "Use when designing account-expansion mechanics — upsell vs cross-sell, expansion-trigger signals, NRR cognition. Triggers on 'lift NRR', 'when do we upsell vs cross-sell'."
+status: active
+tier: senior
+source: package
+domain: product
+context_spine: [product, customer-segment]
+---
+
+# expansion-playbook
+
+## When to use
+
+- Net Revenue Retention plateaued and the team cannot name *which* expansion lever drives it — upsell, cross-sell, and seat-expansion get conflated under *"NRR"* and the moves are uniform when they should be lever-specific.
+- An expansion play is firing on usage signals alone — accounts using more seats are treated as expansion targets without checking the upstream pain that earned the expansion.
+- A new pricing or packaging change is live and the team needs to re-key the expansion triggers to the new shape before the old triggers misfire.
+
+Do NOT use to save churning accounts (route to
+`churn-prevention`), design days 0–30 onboarding (route to
+`onboarding-design`), or build product-led seat-expansion loops
+unattended by a human play (route to `retention-loops`).
+
+## Cognition cluster
+
+- **Mental model 18 — Pull vs. push.** Expansion that the buyer
+  pulls (because pain or scope grew) compounds; expansion the
+  vendor pushes (because the quarter needs the number) corrodes
+  the relationship and inflates churn the next cycle. Pick the
+  trigger that signals pull. See
+  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 18.
+- **Mental model 9 — Hypothesis-driven thinking.** Each expansion
+  trigger is a hypothesis: *"if signal X is true, the buyer will
+  accept expansion Y at price Z."* Triggers without falsification
+  evidence are wishes; if a trigger has misfired three times, the
+  trigger is wrong, not the buyer. See `mental-models.md` § 9.
+- **Mental model 3 — Pareto (80/20).** ~20 % of accounts carry
+  ~80 % of expansion potential. Uniform expansion outreach across
+  the book is noise; weighted outreach by pull-signal strength is
+  reasoning. See `mental-models.md` § 3.
+- **Context-spine — product + customer-segment.** Read the
+  **product** slot for which capabilities the segment can absorb
+  next (sequencing matters — a cross-sell into a feature the
+  segment cannot use yet inflates churn), and the
+  **customer-segment** slot for switch-event patterns that signal
+  organic scope expansion. See
+  [`context-spine`](../../../docs/contracts/context-spine.md).
+
+## Procedure
+
+### Step 0: Inspect — separate upsell, cross-sell, seat-expansion
+
+Inspect the trailing four quarters of expansion $ and decompose:
+
+1. **Upsell** — same product family, higher tier (more seats at same SKU, premium tier of same SKU).
+2. **Cross-sell** — different product family or SKU.
+3. **Seat-expansion** — same SKU, more users, no tier change.
+
+Compute each lever's $ contribution and NRR contribution. A book
+treating these as one number cannot diagnose which lever is
+broken.
+
+### Step 1: Define one expansion trigger per lever, pull-signalled
+
+Each trigger is a *buyer-side pull signal* with falsifiable
+evidence:
+
+1. **Upsell trigger** — buyer crosses tier-defining usage ceiling
+   (e.g. seats > X, or feature-X-usage > Y) sustained for ≥ 30 days.
+2. **Cross-sell trigger** — buyer requests a capability that lives
+   in an adjacent SKU **twice in 60 days**, by two different
+   contacts, in writing.
+3. **Seat-expansion trigger** — admin invites N new users in a
+   rolling 30-day window AND health-score (from `churn-prevention`)
+   is green.
+
+Triggers that misfire three times in a quarter become Step 0
+diagnoses next quarter; do not patch them inside the quarter.
+
+### Step 2: Map lever → play
+
+Each lever gets one default play and one disqualifier:
+
+- **Upsell** — quarterly business review surfacing the usage
+  ceiling; tier-upgrade proposal with proof-of-value. Disqualifier:
+  account on red health score (route to `churn-prevention`).
+- **Cross-sell** — capability-fit discovery call with sponsor +
+  user; pilot before contract change. Disqualifier: cross-sell SKU
+  not GA for the segment.
+- **Seat-expansion** — admin co-pilot session + group onboarding
+  for new seats. Disqualifier: utilisation on existing seats
+  < 40 % (you would be selling decay).
+
+### Step 3: Sequence multi-lever opportunities
+
+If two triggers fire on the same account in the same quarter:
+sequence **upsell before cross-sell** (compound the contract the
+buyer already believes in) **before seat-expansion** (the most
+fragile lever — easiest to inflate, easiest to lose). Two plays
+fired in parallel signal vendor-push and corrode the relationship.
+
+### Step 4: Compute NRR by lever and verify against the dilution check
+
+NRR = (start-ARR + expansion − churn − contraction) ÷ start-ARR,
+per cohort. Decompose expansion into the three levers. **Verify**
+each trigger's pull-signal is intact: confirm the buyer-side
+artefact (usage ceiling crossed, written request, admin invite)
+exists in instrumentation; a lever whose triggers cannot be
+verified against artefacts is push-expansion mislabelled as pull,
+and the next cycle's churn will return the revenue. A book hitting
+115 % NRR via seat-expansion only is more fragile than a book
+hitting 110 % via upsell + cross-sell — fragility shows up in the
+next cycle's churn, not this one's revenue line.
+
+### Step 5: Hand back
+
+Hand the lever decomposition, the three pull-signalled triggers,
+and the per-lever play to CS / AM operations and to
+[`forecast-accuracy`](../forecast-accuracy/SKILL.md) for the
+expansion side of the forecast call. NRR work without lever
+separation is spending in random directions.
+
+## Related Skills
+
+**WHEN to use this**
+
+- Decomposing NRR into upsell · cross-sell · seat-expansion levers.
+- Defining pull-signalled triggers and per-lever plays.
+
+**WHEN NOT to use this**
+
+- Saving accounts likely to churn — route to
+  [`churn-prevention`](../churn-prevention/SKILL.md).
+- Designing days 0–30 onboarding milestones — route to
+  [`onboarding-design`](../onboarding-design/SKILL.md).
+- Product-led, vendor-unattended seat growth loops — route to
+  [`retention-loops`](../retention-loops/SKILL.md).
+
+## When the agent should load this
+
+- "Lift our NRR — which lever?"
+- "When do we cross-sell vs upsell account X?"
+- "Why does our expansion churn back inside the next cycle?"
+- "Welcher Expansion-Trigger ist eigentlich pull, nicht push?"
+
+## Output
+
+1. **`lever-decomposition.md`** — trailing-quarter expansion $ split into upsell · cross-sell · seat-expansion with NRR contribution per lever.
+2. **`expansion-triggers.md`** — one pull-signalled trigger per lever · falsifiable evidence · misfire counter.
+3. **`lever-play-map.md`** — per-lever default play · disqualifier · sequencing rule for multi-trigger accounts.
+
+## Gotcha
+
+- A trigger that fires on usage alone, without separating *pain growth* from *consumption growth*, will push when it should pull. Push-expansion lifts this quarter and depresses the next.
+- Seat-expansion looks like the easiest lever and is the most fragile — easy to inflate by selling seats into accounts whose existing seats are under-utilised; the contraction lands one cycle later.
+- *"Strategic"* cross-sell into a capability the segment is not yet ready to use buys revenue and pays for it in churn — segment-readiness is the gate, not vendor-side ambition.
+
+## Do NOT
+
+- Do NOT fire multiple expansion plays in parallel on one account; sequence per Step 3.
+- Do NOT count seat-expansion at < 40 % existing-seat utilisation as expansion; it is selling decay.
+- Do NOT chase NRR target without lever decomposition; the headline number can be hit by the most fragile lever.
+
+## Runnable example
+
+Mid-market SaaS, NRR 112 % last quarter, churn ticked up this quarter.
+
+- Lever decomposition — upsell 35 %, cross-sell 18 %, seat-expansion 47 % of expansion $. Seat-expansion-led growth flagged as fragile.
+- Triggers — *(1)* upsell trigger: seats > 50 sustained 30+ days (band 28–42 % conversion). *(2)* cross-sell: capability request twice in 60 days from two contacts (band 41–61 % conversion). *(3)* seat-expansion: admin invites ≥ 10 new users in 30 days AND green health (band 52–68 % conversion); misfire count for the quarter: 4 — trigger flagged for Step 0 re-diagnosis next quarter.
+- Lever-play map — upsell QBR + tier proposal, disqualified for 3 red-health accounts; cross-sell pilot blocked for 2 accounts where SKU not yet GA-ready for mid-market.
+- Hand-off — decomposition + triggers → CS / AM ops; sequencing rule live; expansion side of `forecast-accuracy` rebuilt on lever-weighted historical close rates.

package/.agent-src/skills/forecast-accuracy/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: forecast-accuracy
+description: "Use when constructing the forecast call — commit / best-case / pipeline categorisation, deal-level evidence test, accuracy retro-loop. Triggers on 'build the forecast', 'why does our commit miss'."
+status: active
+tier: senior
+source: package
+domain: product
+context_spine: [product, customer-segment]
+---
+
+# forecast-accuracy
+
+## When to use
+
+- The quarterly forecast call is being constructed and the team needs a categorisation rule that survives retro — not a feel-good number that flatters this week.
+- Commit has missed two or more quarters and nobody can name which signals broke — the retro-loop is missing or the categorisation rule is unwritten.
+- A new RevOps lead inherits a pipeline and needs to rebuild the forecast call without inheriting last regime's optimism bias.
+
+Do NOT use to design pipeline stages (route to
+`pipeline-strategy`), qualify a single deal (route to
+`deal-qualification-meddic`), or build the finance-side
+top-down / bottom-up model (composes against — but does not
+duplicate — the finance-partner forecasting capability,
+via the `forecast-construction-shape` interface).
+
+## Cognition cluster
+
+- **Mental model 16 — Leading vs. lagging indicators.** Closed-won
+  is lagging; per-stage conversion and MEDDIC-slot completeness
+  are leading. A forecast built on lagging signals can only confirm
+  the result after it lands. See
+  [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 16.
+- **Mental model 29 — Premortem.** Before locking the call, write
+  the post-quarter retro as if commit missed by 20 %. The premortem
+  surfaces which categorisations are riding on weak evidence; demote
+  those before the call locks. See `mental-models.md` § 29.
+- **Mental model 9 — Hypothesis-driven thinking.** Each commit deal
+  carries a falsifiable claim: *"this closes by \<date\> because
+  \<evidence\>."* If the claim cannot be falsified inside the
+  quarter, the deal is best-case, not commit. See
+  `mental-models.md` § 9.
+- **Context-spine — product + customer-segment.** Read the
+  **product** slot for what is actually GA-shippable this quarter
+  (deals depending on non-shipped scope are not commit), and the
+  **customer-segment** slot for segment-historical close rates —
+  pricing-power and cycle-length differ by segment and the forecast
+  must too. See
+  [`context-spine`](../../../docs/contracts/context-spine.md).
+
+## Procedure
+
+### Step 0: Inspect — inherit pipeline + qualification artefacts
+
+Pull `stage-definitions.md`, `coverage-by-cell.md` from
+`pipeline-strategy`, and the latest `meddic-card.md` per deal from
+`deal-qualification-meddic`. Inspect whether each commit-candidate
+deal carries falsifiable evidence per MEDDIC slot — a forecast
+built without that inspection is rep opinion, not categorisation.
+
+### Step 1: Lock the three categories with falsifiable rules
+
+1. **Commit** — deal closes in-window with ≥ 90 % subjective
+   probability **and** MEDDIC slots all filled with evidence **and**
+   decision-process has buyer-written dates inside the window.
+2. **Best-case** — deal *could* close in-window with ≥ 50 %
+   probability **and** ≤ 2 MEDDIC slots unfilled **and** at least
+   one decision-process date inside the window.
+3. **Pipeline** — everything else. Pipeline is not a forecast
+   category; it is the population from which commit and best-case
+   are drawn.
+
+Reject *"commit"* placements that do not meet all three commit
+criteria, regardless of $ value or rep confidence.
+
+### Step 2: Apply the segment-historical close rate
+
+For each deal, compute *expected $* = $ × segment-historical
+in-window close-rate (trailing four quarters). Aggregate by
+category. If commit-$ exceeds (segment historical commit close-rate
+× pipeline-$ in commit), the call is structurally optimistic — find
+the optimism source before defending the number.
+
+### Step 3: Premortem the commit list
+
+Write *"if commit misses by 20 %, the reason is \_\_\_."* The most
+common patterns: (a) one anchor deal slipped, (b) segment cycle
+lengthened, (c) procurement/legal queues bunched at quarter-end.
+Tag each commit deal with which of these would kill it; deals tagged
+with two or more move to best-case.
+
+### Step 4: Construct the call with confidence bands
+
+Report **commit $** = sum of commit-tagged after Step 3 demotions.
+**Best-case $** = commit + best-case-tagged. Attach the band:
+*"commit ± \<historical-deviation\>; best-case ± \<historical
+upside\>"*. A call without a band has no honesty about its prior
+miss-rate.
+
+### Step 5: Run the accuracy retro-loop at quarter-end
+
+Compare predicted commit / best-case / pipeline to actual
+closed-won by category. Compute per-rep, per-segment, and per-stage
+miss-rate. Patterns that repeat for two quarters become categorisation
+rule changes in Step 1; one-off misses become deal-level evidence
+upgrades in Step 0.
+
+## Related Skills
+
+**WHEN to use this**
+
+- Constructing the quarterly forecast call from a qualified pipeline.
+- Running the accuracy retro-loop and feeding it back into Step 1.
+
+**WHEN NOT to use this**
+
+- Designing pipeline stages or per-stage conversion targets — route to
+  [`pipeline-strategy`](../pipeline-strategy/SKILL.md).
+- Single-deal qualification or disqualification — route to
+  [`deal-qualification-meddic`](../deal-qualification-meddic/SKILL.md).
+- Finance-side top-down model or board-deck forecast — composes
+  against (does not replace) the finance-partner forecasting capability
+  via the `forecast-construction-shape` interface.
+
+## When the agent should load this
+
+- "Build the Q3 forecast call."
+- "Why does our commit keep missing?"
+- "Run the forecast retro for last quarter."
+- "Welche Deals gehören wirklich in Commit?"
+
+## Output
+
+1. **`forecast-call.md`** — commit $ and best-case $ with confidence bands; per-segment breakdown.
+2. **`commit-list.md`** — one row per commit deal: $, segment, MEDDIC-completeness, decision-process date, premortem tag (none / single-risk / two-risk demoted).
+3. **`retro-deltas.md`** *(at quarter-end)* — predicted vs actual per category, per-segment, per-rep miss-rate, and the categorisation-rule change (if any) for next quarter.
+
+## Gotcha
+
+- *"Strong commit"* without buyer-written dates inside the window is a wish, not a forecast. Subjective probability without artefact evidence is what the retro will punish.
+- Segment-historical close rates change after a pricing change, a packaging change, or a competitive shift. Recompute the rates when the segment shape changes, otherwise the call inherits the old regime's optimism.
+- Reporting commit as a point estimate without the band hides the prior miss-rate. A team that has missed by 18 % twice and reports commit ± 0 % is performing forecasting, not doing it.
+
+## Do NOT
+
+- Do NOT place a deal in commit because the size is large; size is independent of evidence.
+- Do NOT skip the premortem on commit deals — most misses come from a small number of anchor deals slipping, and the premortem is where you catch them.
+- Do NOT change categorisation rules on a single-quarter miss; rules change on a two-quarter pattern.
+
+## Runnable example
+
+End of Q2, last two commits missed by 14 % and 21 %.
+
+- Step 1 enforcement — three deals placed in commit had ≥ 2 MEDDIC slots open; demoted to best-case (–$ 540 k commit, +$ 540 k best-case).
+- Segment close-rate — Mid-Market historical commit close-rate is 78 %; commit-$ implies 91 % aggregate close-rate; structural optimism of ~$ 320 k.
+- Premortem — two anchor deals (each > 10 % of commit) tagged single-risk (procurement queue); one tagged two-risk (no buyer-written date) → demoted.
+- Final call — *"commit $ 4.1 m ± 12 % (historical deviation); best-case $ 6.7 m + 8 % / – 14 %."* Commit-list flags the two procurement-risk anchors for VP-level intervention.
+- Retro at quarter-end — predicted commit $ 4.1 m, actual $ 4.0 m; rule unchanged; one rep over-commits two quarters running → categorisation-coaching action.

package/.agent-src/skills/forecasting/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: forecasting
+description: "Use when constructing the finance-side forecast — top-down vs bottom-up shape, confidence bands, retro-loop. Triggers on 'build the forecast model', 'reconcile top-down with bottom-up'."
+status: active
+tier: senior
+source: package
+domain: process
+context_spine: [product, fiscal-period, customer-segment]
+---
+
+# forecasting
+
+## When to use
+
+- The annual plan or quarterly board pack needs a forecast model that survives a retro — not last quarter's number with a multiplier.
+- Top-down (TAM × penetration × motion) and bottom-up (deal-level) calls have diverged and the reconciliation hasn't been written.
+- A new finance-partner inherits a forecast and needs to rebuild the construction shape without inheriting the prior regime's optimism.
+
+Do NOT use to qualify a single deal (route to `deal-qualification-meddic`), construct the RevOps commit list (route to `forecast-accuracy` (H10) — finance owns the shape, RevOps owns the call), or run capital-runway scenarios (route to `runway-cognition` (O3)).
+
+## Cognition cluster
+
+- **Mental model 9 — Hypothesis-driven thinking.** Each forecast is
+  a falsifiable claim about a window. If the call cannot be falsified
+  inside the window, the call is a narrative, not a forecast. See
+  [`mental-models.md`](../../../docs/contracts/mental-models.md) § 9.
+- **Mental model 29 — Premortem.** Before locking the call, write the
+  post-window retro as if commit missed by 20 %. The premortem
+  surfaces which construction inputs were riding on weak evidence;
+  demote those before the call locks. See `mental-models.md` § 29.
+- **Mental model 16 — Leading vs lagging.** Closed-won is lagging;
+  pipeline coverage, segment conversion, and slot-completeness are
+  leading. A forecast built only on lagging signals can confirm but
+  not steer. See `mental-models.md` § 16.
+- **Context-spine — product + fiscal-period + customer-segment.**
+  Read the **product** slot for what is GA-shippable in the window;
+  the **fiscal-period** slot for the cadence the model must
+  reconcile against (monthly close vs quarterly board pack vs annual
+  plan vs multi-year plan); the **customer-segment** slot for
+  segment-historical close rates. See
+  [`context-spine`](../../../docs/contracts/context-spine.md).
+
+## Procedure
+
+### Step 0: Inspect the construction shape
+
+Read the fiscal-period slot. Decide between three shapes:
+
+1. **Top-down** — anchor against TAM × penetration band × motion
+   band. Healthy for annual plans and multi-year plans where
+   bottom-up evidence is thin past one window.
+2. **Bottom-up** — sum deal-level conviction (composes H10
+   `forecast-accuracy` via the `forecast-construction-shape` ADR).
+   Healthy for quarterly windows where deal evidence is fresh.
+3. **Hybrid** — both, with an explicit reconciliation. Healthy when
+   top-down and bottom-up diverge by more than the historical
+   confidence band.
+
+State the choice. A forecast without a stated shape inherits the
+prior regime's shape silently.
+
+### Step 1: Construct the call against the shape
+
+For top-down: write `{tam, penetration_band, motion_band}` — every
+input cites its source. Penetration bands are evidence ranges, not
+single points; motion bands reflect channel mix.
+
+For bottom-up: consume H10's commit-list against the
+`forecast-construction-shape` interface. Sum commit-tagged ×
+in-window close-rate per segment.
+
+For hybrid: do both, then write the reconciliation. If top-down ≠
+bottom-up by more than the confidence band, the divergence is the
+forecast — not either number.
+
+### Step 2: Calibrate the confidence band
+
+Compute historical deviation from the last 4–8 windows of the same
+fiscal-period cadence. Attach as `{plus_pct, minus_pct}`. A band
+asymmetric on the downside is honest about prior misses; symmetric
+bands silently pretend prior accuracy.
+
+### Step 3: Premortem the construction
+
+Write *"if the forecast misses by 20 %, the reason is ___."* For
+top-down: which penetration / motion input was the load-bearing
+assumption? For bottom-up: which anchor deals carry > 10 % of
+commit? Demote inputs that the premortem can name as single-point
+risks.
+
+### Step 4: Emit the typed interface
+
+Produce `forecast-band.json` per the `forecast-construction-shape`
+ADR. H10 consumes the artifact for the commit-call. The fields:
+`construction_shape`, `commit_value`, `best_case_value`,
+`pipeline_value`, `confidence_band`, `retro_signature`,
+`segment_scope`, `fiscal_period`, `construction_inputs`. Drop the
+artifact in the location H10's `## Output` references.
+
+### Step 5: Run the accuracy retro-loop
+
+At window-end, compare predicted commit / best-case to actual
+closed-won. Compute per-segment and per-construction-input miss
+rate. Patterns that repeat for two windows become shape changes in
+Step 0 (e.g. switching from bottom-up to hybrid because deal
+evidence stopped predicting); one-off misses become input upgrades
+in Step 1.
+
+## Related Skills
+
+**WHEN to use this**
+
+- Constructing the finance-side forecast (annual plan, board pack, multi-year plan).
+- Running the construction-shape retro and feeding it back into Step 0.
+
+**WHEN NOT to use this**
+
+- Single-deal qualification — route to [`deal-qualification-meddic`](../deal-qualification-meddic/SKILL.md).
+- Commit / best-case / pipeline categorisation of deals — route to [`forecast-accuracy`](../forecast-accuracy/SKILL.md) (H10); H10 consumes against this skill's `forecast-band.json` interface.
+- Cash-runway shape and fundraise-trigger heuristics — route to [`runway-cognition`](../runway-cognition/SKILL.md) (O3).
+- Multi-statement scenario construction over base / upside / downside — route to [`scenario-modeling`](../scenario-modeling/SKILL.md) (O4).
+
+Wing-4 handoff: this skill emits the `forecast-band.json` artifact
+that `forecast-accuracy` (H10, Wing-3) reads. Per
+`docs/contracts/adr-forecast-construction-shape.md`,
+`docs/guidelines/wing4-handoff.md` § Chain 4.
+
+## When the agent should load this
+
+- "Build the annual forecast model."
+- "Top-down and bottom-up disagree — reconcile them."
+- "Why was last quarter's forecast off?"
+- "Was machen wir bei der Forecast-Konstruktion anders?"
+
+## Output
+
+1. **`forecast-band.json`** *(Wing-3 / Wing-4 typed interface)* — `construction_shape`, `commit_value`, `best_case_value`, `pipeline_value`, `confidence_band`, `retro_signature`, `segment_scope`, `fiscal_period`, `construction_inputs`. Per `adr-forecast-construction-shape.md`.
+2. **`construction-notes.md`** — shape chosen + why; per-input evidence; reconciliation note (hybrid only).
+3. **`premortem.md`** — "if we miss by 20 %, the reason is ___"; tagged demotions from Step 3.
+4. **`retro-deltas.md`** *(at window-end)* — predicted vs actual per construction input; shape-change recommendation if the pattern repeats.
+
+## Gotcha
+
+- A forecast without a stated `construction_shape` inherits last regime's shape silently. Always emit the field.
+- Symmetric confidence bands lie about prior misses. If the last two windows missed on the downside, the band is asymmetric.
+- Top-down models with single-point penetration assumptions are scenarios in disguise. Use bands.
+- Hybrid models that don't write the reconciliation are top-down models with bottom-up garnish.
+
+## Do NOT
+
+- Do NOT collapse hybrid forecasts into a single number without keeping the divergence visible.
+- Do NOT skip Step 4 — the typed interface is what makes H10 reproducible.
+- Do NOT change the construction shape on a single-window miss; shape changes require a two-window pattern.
+
+## Runnable example
+
+End of FY: annual plan + Q1 commit both due.
+
+- Step 0 — fiscal-period slot says `annual` + `quarterly`. Annual is top-down; Q1 is bottom-up.
+- Step 1 — top-down: TAM $4.2B, penetration band 0.6–0.9 %, motion band SaaS-mid; expected $25–38M ARR. Bottom-up: H10 commit-list sums to $8.1M in Q1, segment close rate 78 %.
+- Step 2 — last 4 quarters deviation: +6 % / –14 %. Confidence band attached.
+- Step 3 — premortem: top-down anchored on penetration upper bound; demoted to 0.6–0.75 %. Bottom-up: two anchor deals tagged single-risk procurement; demoted.
+- Step 4 — emit `forecast-band.json`: `construction_shape=hybrid`, commit $6.3M, best-case $8.1M, band +6/–14 %, retro_signature `quarterly | [+6, –14]`, segment_scope mid-market, fiscal_period `quarterly`.
+- Retro — at quarter-end, actual $6.1M; band held. Annual top-down revisit in two quarters.