@diottodev/runic 1.0.0 → 1.1.0

package/c-level/vpe-review/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: "vpe-review"
+description: "/cs:vpe-review <plan> — Throughput-first VP of Engineering interrogation of any plan that touches delivery, eng hiring, team structure, or production discipline."
+---
+
+# /cs:vpe-review — VPE Forcing Questions
+
+**Command:** `/cs:vpe-review <plan>`
+
+The throughput-first VPE pressure-tests any plan touching eng operations. Six questions before any delivery commitment, eng hiring expansion, team restructure, or production-discipline change.
+
+## When to Run
+
+- Before quarterly delivery commitment (sprint planning, OKR review)
+- Before approving an eng hiring plan
+- Before restructuring eng teams (splitting/merging squads, adding tribes)
+- Before deciding whether to hire a VPE separately from CTO (or merge them)
+- When production incidents are increasing
+- When sprint velocity is dropping but everyone says "we're working hard"
+
+## The Six VPE Questions
+
+### 1. What's the cycle time, and where does work wait?
+**No DORA, no diagnosis.**
+- Lead Time for Changes is the single best health metric
+- If you can't decompose cycle time into stages, you can't fix the bottleneck
+- Run `delivery_throughput_analyzer.py`
+
+### 2. What's the DORA performance level on all 4 metrics?
+**One Elite metric and three Lows = bad. Four Highs = healthy.**
+- Deployment Frequency, Lead Time, MTTR, Change Failure Rate
+- The worst metric defines overall level
+- Fix lead time first; everything else follows
+
+### 3. Where is the hiring funnel leaking?
+**"Can't find good engineers" is wrong.**
+- Specific stage is over-filtering OR top-of-funnel volume is too low OR offer-to-accept is broken
+- Run `eng_hiring_funnel_calculator.py`
+- If offer-to-accept < 70%, comp is below market or close discipline is weak
+
+### 4. Is the team structure healthy for the headcount?
+**5-9 ICs per squad; 5-8 ICs per EM; 4-6 EMs per director.**
+- Run `eng_team_structure_designer.py`
+- Manager-trigger fires when 5+ ICs have no dedicated EM
+- Director-trigger fires when 3+ EMs report directly to VPE/CTO
+
+### 5. What's the production discipline maturity?
+**Level 1-5; aim for Level 3 at growth stage.**
+- On-call rotation ≥ 6 people
+- Severity-defined incident response with blameless postmortems
+- SLOs on customer-facing services (pair with `engineering/slo-architect/`)
+- Continuous deployment OR scheduled — not "usually one, sometimes the other"
+
+### 6. Are we adding a VPE separately, or is CTO doing both?
+**If CTO is spending > 50% on management vs strategy, VPE is needed.**
+- Or: VPE complement when CTO is co-founder more comfortable with strategy
+- VPE owns operating model; CTO owns architecture
+- At small scale (< 20 eng), one person can do both
+
+## Workflow
+
+```bash
+# 1. Delivery throughput
+python ../../../skills/vpe-advisor/scripts/delivery_throughput_analyzer.py sprint_metrics.json
+
+# 2. Hiring funnel
+python ../../../skills/vpe-advisor/scripts/eng_hiring_funnel_calculator.py funnel.json
+
+# 3. Team structure
+python ../../../skills/vpe-advisor/scripts/eng_team_structure_designer.py team.json
+```
+
+## Output Format
+
+```markdown
+# VPE Review: <plan>
+**Date:** YYYY-MM-DD
+
+## The Decision Being Made
+[throughput | hiring | structure | production | VPE-vs-CTO]
+
+## Delivery Throughput (if applicable)
+- DORA overall: Elite / High / Medium / Low
+- Worst metric: <DF | LT | MTTR | FR>
+- Bottleneck: <stage> (X% of cycle time)
+- Top fix: <action + owner>
+
+## Hiring Funnel (if applicable)
+- End-to-end conversion: X%
+- Weakest stage: <stage>
+- Pipeline gap: +N candidates needed
+- Top fix: <specific action>
+
+## Team Structure (if applicable)
+- Recommended: <informal pods / squads / tribes>
+- Manager trigger fired: yes/no
+- Director trigger fired: yes/no
+- Action: <hire EM | hire director | split squad>
+
+## Production Discipline (if applicable)
+- Current maturity level: 1-5
+- Next practice to add: <specific>
+- SLO coverage: X / Y services
+
+## Verdict
+🟢 SHIP | 🟡 SHARPEN | 🔴 BLOCK
+
+## Next Steps
+[3 concrete actions]
+```
+
+## Routing
+
+- `/cs:cto-review` — for architectural causes of throughput problems
+- `/cs:chro-review` — for hiring funnel comp/leveling issues
+- `/cs:cfo-review` — for cost-per-hire envelope and eng budget
+- `/cs:ciso-review` — for production discipline + compliance overlap
+- `/cs:decide` — log the verdict
+- `/cs:freeze 30` — on multi-year hiring commitments
+
+## Related
+
+- Agent: [`cs-vpe-advisor`](../../agents/cs-vpe-advisor.md)
+- Skill: [`vpe-advisor`](../../../skills/vpe-advisor/SKILL.md)
+- Adjacent: `../../../../engineering/slo-architect/`, `../../../../engineering/feature-flags-architect/`, `../../../../engineering/chaos-engineering/`
+
+---
+
+**Version:** 1.0.0

package/commercial/channel-economics/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: channel-economics
+description: "Use when reviewing or rebalancing direct vs. partner-led channel economics — computing fully-loaded cost-to-serve per channel, channel ROI with cash / LTV / marginal lenses, and optimal channel mix subject to constraints. For Head of Commercial, RevOps, and VP Sales doing quarterly channel review when pipeline is mixed (e.g., 60% direct + 40% partner-led) and nobody actually knows which channel makes money after CAC, support load, partner discount, deal-velocity differences, retention differential, and overhead allocation are all loaded in. Outputs cost to serve, channel ROI verdicts (DOUBLE-DOWN / MAINTAIN / DEFUND / EXIT), a sensitivity-tested channel-mix recommendation, and the diminishing-returns inflection. Not channel structure (that's partnerships-architect — tiers, joint GTM, revshare). Not RevOps process (that's business-growth/revenue-operations — lead routing, SDR motion). Not strategic CRO judgment (that's c-level-advisor/cro-advisor — comp plans, when-to-hire-a-VP-Sales). Not historical close-and-report (that's finance/financial-analysis). This skill answers: direct vs partner profitability, channel profitability, channel mix, channel economics."
+version: 2.8.0
+author: claude-code-skills
+license: MIT
+tags: [commercial, channel-economics, cost-to-serve, channel-mix, channel-roi, direct-vs-partner, unit-economics]
+compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
+---
+
+# channel-economics
+
+## Purpose
+
+Help Head of Commercial / RevOps / VP Sales answer three questions at the quarterly channel review:
+
+1. **What does each channel actually cost to serve, fully loaded?** (direct headcount, channel manager attribution, partner discount, MDF, enablement time, support load, allocated overhead)
+2. **What is the ROI of each channel under three lenses?** (cash ROI year-1, LTV-adjusted ROI, marginal ROI — next dollar of investment)
+3. **What is the optimal channel mix subject to our strategic constraints?** (minimum direct floor, maximum partner concentration ceiling, sensitivity to CAC shifts)
+
+The skill emits **per-channel verdicts** (DOUBLE-DOWN / MAINTAIN / DEFUND / EXIT), a **sensitivity-tested mix recommendation**, and **the diminishing-returns inflection point**. It does not pick the strategy — humans do, with the numbers loaded honestly for the first time.
+
+## When to use
+
+- Quarterly channel review: pipeline is 60/40 or 50/50 direct vs partner and you don't actually know which one is profitable
+- Considering hiring a channel manager — need to know if the channel can clear the loaded-cost bar
+- Partner program ROI question from the board ("we spent $X on MDF — what did we get?")
+- A segment is over-indexed to one channel and you suspect mix dogma is blocking the other
+- About to expand into a new region and need to decide direct-first vs partner-first
+- M&A diligence: target company claims "partner-led at 70% gross margin" — need to validate after loading
+
+**Do not use for:**
+- Designing partner tiers, joint GTM motion, revshare splits → `partnerships-architect`
+- SDR-to-AE routing, lead scoring, MQL definitions → `business-growth/revenue-operations`
+- Strategic CRO decisions ("should we hire a VP Sales?", comp plan design) → `c-level-advisor/cro-advisor`
+- Quarterly close, GAAP revenue recognition, channel-level P&L for historical reporting → `finance/financial-analysis`
+- Per-deal discount approval → `deal-desk`
+- Pricing model design → `pricing-strategist`
+
+## Workflow
+
+### Step 1 — Intake channel data
+
+Fill `assets/channel_data_template.md` (≈ 20 min). Capture per channel: deal count TTM, ARR TTM, avg deal size, gross margin %, CAC, sales-cycle days, retention rate, expansion rate, partner discount %, all attributable costs (SDR / AE / SE / channel manager / CS / support / marketing / partner MDF / tooling / overhead allocation %).
+
+The template surfaces the costs teams most often forget: partner enablement time, certification investment, channel-conflict resolution overhead, channel-manager headcount cost.
+
+### Step 2 — Compute cost-to-serve per channel
+
+Run `scripts/cost_to_serve_calculator.py --input channel.json --output markdown`.
+
+Output: fully-loaded cost-to-serve **per deal** AND **per dollar of ARR**, with direct costs broken out from allocated overhead, and a "true gross margin" line after channel-specific load. Flags double-counting and surfaces hidden costs.
+
+Run once per channel. The "true gross margin" line is the input the next two scripts care about.
+
+### Step 3 — Compute ROI per channel under three lenses
+
+Run `scripts/channel_roi_analyzer.py --input roi.json --profile saas --output markdown`.
+
+Output: per channel, three ROI numbers (Cash year-1, LTV-adjusted, Marginal), the diminishing-returns inflection point, and a verdict: DOUBLE-DOWN / MAINTAIN / DEFUND / EXIT.
+
+Verdict logic is deterministic and surfaced in the report. Humans can override; the skill won't.
+
+### Step 4 — Optimize channel mix subject to constraints
+
+Run `scripts/channel_mix_optimizer.py --input mix.json --profile saas --output markdown`.
+
+Output: recommended mix that maximizes effective ARR subject to constraints (min direct %, max partner concentration), plus a sensitivity table (what if direct CAC rises 20%? what if partner discount widens 5 points?).
+
+### Step 5 — Decide
+
+Take the three reports into the quarterly channel review. The skill recommends; the human commits.
+
+## Scripts
+
+- `scripts/cost_to_serve_calculator.py` — fully-loaded cost-to-serve per deal AND per $ ARR, with hidden-cost surfacing
+- `scripts/channel_roi_analyzer.py` — 3-lens ROI (Cash / LTV / Marginal) with verdicts and diminishing-returns inflection
+- `scripts/channel_mix_optimizer.py` — constrained mix optimizer with sensitivity scenarios
+
+All scripts: stdlib only. `--help`, `--sample`, `--input`, `--output` work on all three. Industry tuning via `--profile {saas,api,enterprise-software,marketplace,hardware}` on the two analyzers.
+
+## References
+
+- `references/channel_economics_canon.md` — Skok, Bessemer State of the Cloud, Tunguz, Pacific Crest / KeyBanc SaaS Survey, Ramanujam, Jay McBain (Canalys)
+- `references/cost_to_serve_canon.md` — Kaplan & Cooper (ABC), Horngren, Jeremy Hope, IBM CTS case studies, McKinsey, Gartner, BCG
+- `references/channel_anti_patterns.md` — Forrester, Tunguz, Hessling, HBR, SiriusDecisions, MIT Sloan, Gartner
+
+## Assumptions
+
+- Channel economics is a **forward-looking** question. Historical channel P&L is finance's job; this skill loads forward economics for a decision.
+- "Channel" means a coherent go-to-market motion (direct outbound, partner-led, marketplace, reseller, OEM). It does not mean a marketing source.
+- Cost-to-serve requires **honest overhead allocation**. The script validates that overhead % is consistent across channels — false partner-margin lift from inconsistent allocation is the #1 anti-pattern.
+- LTV inputs (retention, expansion) are per-channel, not pooled. Partner-sourced customers often retain differently than direct-sourced — this difference is usually the largest economic variable and the most ignored.
+- Industry profiles (`--profile`) tune defaults for benchmarks (e.g., SaaS direct CAC payback target ~12mo, enterprise ~18mo) — they don't override your numbers.
+- This is a decision-support skill. Output is verdicts and a recommended mix, never an automatic resource reallocation.
+
+## Anti-patterns
+
+- **Treating "influenced" deals as "sourced" deals.** A partner that touched a deal your AE already had is not channel-sourced revenue. Loading this as partner revenue inflates partner ROI and inflates direct CAC simultaneously.
+- **Inconsistent overhead allocation.** Allocating 25% overhead to direct deals and 5% to partner deals because "the partner handles the overhead" is false. The partner manager, partner program, MDF, certification, and conflict-resolution all live in your P&L.
+- **Ignoring enablement time as a cost.** Every hour your AE spends co-selling with a partner is a direct cost charged to the partner channel — most teams forget to load it.
+- **MDF without ROI tracking.** Market Development Funds disbursed without an attributable pipeline ROI are just a partner-discount extension. The skill flags MDF with no return.
+- **Channel-mix dogma.** "We're a partner-first company" / "we don't sell direct" blocks profitable segments. Mix should follow the math, not the slogan.
+- **Computing channel ROI without retention differential.** If partner-sourced customers churn 5 points higher than direct, ignoring it overstates partner LTV by 30-50%. Per-channel retention is mandatory input.
+- **No cost-attribution for channel-manager headcount.** A $200k channel manager managing $4M of partner ARR is $50 of channel-manager cost per $1k ARR — material to the verdict.
+- **Confusing this skill with partnerships-architect.** That skill designs the partner program. This skill tells you whether the program pays for itself.
+
+## Distinct from
+
+- **commercial/partnerships-architect** — partner tier design, joint GTM motion, revshare splits, partner enablement. Partner program *structure*, not partner program *economics*. This skill consumes the program structure as input and emits the economic verdict.
+- **business-growth/revenue-operations** — lead routing, SDR motion, MQL definition, pipeline operations. RevOps owns the funnel mechanics; this skill loads the channel-level economic outcome.
+- **c-level-advisor/cro-advisor** — strategic CRO judgment: when to hire a VP Sales, comp plan philosophy, territory design, multi-year revenue strategy. CRO advisor consumes channel-economics output as one input among many.
+- **finance/financial-analysis** — close-and-report on historical channel P&L per GAAP. This skill is forward-looking decision support; finance is historical record. Different time horizon, different audience, different output.
+- **commercial/deal-desk** — per-deal discount approval. Operates daily; this skill operates quarterly.
+- **commercial/pricing-strategist** — pricing model and tier design. Pricing is input; channel economics is what happens at that pricing across channels.
+
+## Forcing-question library (Matt Pocock grill discipline)
+
+Walked one at a time by `/cs:grill-commercial` or the orchestrator. Recommended answer + canon citation per question. Never bundled.
+
+1. **"What's your fully-loaded cost-to-serve per channel — including channel-manager headcount, MDF, partner enablement time, and overhead allocation?"**
+   Recommended: load all four. Most teams load partner discount but forget the channel-manager headcount and the enablement time, inflating partner margin by 8-15 points.
+   Canon: Kaplan & Cooper (HBR 1988) — *Measure Costs Right: Make the Right Decisions*. Activity-Based Costing was invented precisely because channel costs hide in overhead and distort margin comparisons.
+
+2. **"What is the retention differential between direct-sourced and partner-sourced customers?"**
+   Recommended: instrument per-channel retention BEFORE running channel ROI. A 5-point retention gap moves LTV by 30-50%.
+   Canon: David Skok (*For Entrepreneurs* — SaaS Metrics 2.0). LTV = (ARPA × Gross Margin) / Churn. Channel-blind churn is the most common source of false channel ROI.
+
+3. **"What share of 'channel-sourced' pipeline did your team actually originate?"**
+   Recommended: if your AE already had the account, it's not channel-sourced — it's channel-influenced. Influence and source are different economic lines.
+   Canon: SiriusDecisions / Forrester channel attribution research — confused source vs. influence is the #1 reason partner ROI is overstated industry-wide.
+
+4. **"What is the marginal ROI of the next dollar invested in partner program vs. direct sales?"**
+   Recommended: compute the diminishing-returns curve on both. Average ROI hides the fact that the next dollar might earn 0.3x while the average earns 2.1x.
+   Canon: Tomasz Tunguz (*Tomasz Tunguz blog* — channel CAC analyses). Average ROI is a vanity metric; marginal ROI drives investment decisions.
+
+5. **"What's your MDF-to-attributable-pipeline ratio in the last 4 quarters?"**
+   Recommended: < 5:1 (every $1 of MDF should generate ≥ $5 of attributable pipeline within 2 quarters). Anything looser is partner-discount theatre.
+   Canon: Jay McBain (Canalys) — *State of the Channel* research. MDF without attribution discipline is the most expensive form of channel subsidy.
+
+6. **"Is your channel-mix dogma blocking a profitable segment?"**
+   Recommended: surface the dogma ("we're partner-first", "we don't sell direct in SMB") explicitly. Mix should follow the segment math.
+   Canon: MIT Sloan Management Review — *When Channel Conflict Means Growth*. Dogmatic single-channel strategies forfeit 15-25% of TAM in mid-market specifically.
+
+7. **"What overhead-allocation methodology are you applying — and is it consistent across direct and partner?"**
+   Recommended: same methodology, same denominator, both channels. Inconsistent allocation is the silent killer of channel-economics analysis.
+   Canon: Charles Horngren (*Cost Accounting: A Managerial Emphasis*) — allocation consistency is the precondition for cross-segment margin comparison. Without it, every conclusion is contaminated.
+
+Walk depth-first. Lock 1-3 before opening 4-7. After all 7 are answered, invoke `cost_to_serve_calculator.py` → `channel_roi_analyzer.py` → `channel_mix_optimizer.py` in sequence.

package/commercial/commercial-forecaster/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: commercial-forecaster
+description: "Use when building a quarterly bookings forecast, ARR projection, pipeline forecast, NRR projection, or commit/best-case/pipe-only board number — especially when the CRO needs to walk the board through funnel math + cohort ARR + per-stage conversion assumptions without the theatre of a single undefended number. Decomposes pipeline into commit, best-case, and pipe-only tiers; projects cohort-level NRR/GRR to surface leaky cohorts before they show up in the consolidated number; scores per-stage funnel confidence so soft-floor stages get treated differently from high-confidence ones. Every output explicitly names the conversion rate used, the data window, and the weighting choice. For Head of Commercial, RevOps, VP Sales, and CRO at quarterly forecast or board prep. NOT financial close (see finance/financial-analysis). NOT strategic CRO hiring/territory (see c-level-advisor/cro-advisor). NOT pricing (see sibling pricing-strategist)."
+version: 2.8.0
+author: claude-code-skills
+license: MIT
+tags: [commercial, forecasting, bookings, arr, nrr, grr, cohort, funnel, pipeline-math]
+compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
+---
+
+# commercial-forecaster
+
+## Purpose
+
+Help Commercial leaders answer three questions at the forecast moment:
+
+1. **What's the commit / best-case / pipe-only number?** (3-tier bookings forecast with disclosed assumptions)
+2. **Which cohorts are leaking, and is the consolidated NRR hiding the leak?** (per-cohort NRR/GRR projection over horizon)
+3. **Which funnel stages are reliable, and which are statistical noise?** (per-stage coefficient-of-variation confidence band)
+
+The skill recommends **three forecast numbers + an explicit assumption block**. The CRO presents the number, the board sees the assumptions, the theatre dies.
+
+## When to use
+
+- Building the quarterly bookings forecast for the board
+- Preparing the QBR forecast where the CFO will ask "what's the commit, what's the best-case, what's the pipe-only"
+- Projecting ARR for next 4-8 quarters using cohort retention data
+- Suspecting a consolidated NRR number is hiding a leaky recent cohort
+- Pipeline-coverage is shrinking and you need to know which stages are still trustworthy
+- You're being asked for a "single number" and you need the structured answer that surfaces the assumption
+
+**Do not use for:**
+- Backward-looking financial close + reporting → `finance/financial-analysis`
+- Strategic financial planning (multi-year, scenario, fundraise) → `c-level-advisor/cfo-advisor`
+- "Should we hire a VP Sales?" / territory design / comp plan → `c-level-advisor/cro-advisor`
+- Setting prices → sibling `pricing-strategist` (projects revenue *at* prices already set)
+- Per-deal discount approval → sibling `deal-desk`
+
+## Workflow
+
+### Step 1 — Intake pipeline + cohort + historical conversion data
+
+Fill `assets/forecast_intake_template.md` (≈ 20 min). Captures: opportunity list with stage/amount/close-date/age/last-activity; historical stage-to-stage conversion across last 4Q and last 12Q; per-cohort ARR + per-quarter retention + expansion data; funnel stage names with 12-quarter conversion history.
+
+### Step 2 — Run 3-tier bookings forecast
+
+```
+scripts/bookings_forecaster.py --input intake.json --profile saas --output markdown
+```
+
+Outputs three numbers — **commit**, **best-case**, **pipe-only** — each with the conversion rate applied, the data window used (last-4Q vs. last-12Q weighted 70/30), and the time-to-close probability adjustment. Surfaces variance between commit and pipe-only as the pipeline-risk indicator.
+
+**The assumption block is non-optional.** If you remove it, the forecast becomes theatre.
+
+### Step 3 — Project cohort-level ARR
+
+```
+scripts/cohort_arr_projector.py --input intake.json --output markdown
+```
+
+Computes per-cohort NRR + GRR over the projection horizon. Flags any cohort whose NRR is declining vs. the trailing-cohort average — these are the leaky cohorts that the consolidated number will hide for 2-3 quarters before the leak surfaces in the topline.
+
+Output includes the consolidated NRR/GRR trajectory + the cohort heatmap + a leaky-cohort callout.
+
+### Step 4 — Score per-stage funnel confidence
+
+```
+scripts/funnel_confidence_scorer.py --input intake.json --output markdown
+```
+
+Per stage: mean conversion %, standard deviation, coefficient of variation (CoV = StDev / Mean), confidence band (HIGH < 10%, MEDIUM 10-25%, LOW 25-50%, VERY LOW > 50%). Recommends treatment per stage: extend-data-window, treat-as-soft-floor, or commit-quality.
+
+### Step 5 — Assemble the forecast deck
+
+Take the 3-tier bookings number + cohort heatmap + funnel confidence into the QBR / board deck. **The assumption block goes on the slide with the number.** If the slide has a single number and no assumption block, the slide is theatre.
+
+## Scripts
+
+- `scripts/bookings_forecaster.py` — 3-tier bookings forecast (commit / best-case / pipe-only) with disclosed conversion-rate + data-window + weighting block
+- `scripts/cohort_arr_projector.py` — per-cohort NRR/GRR projection over horizon with leaky-cohort callout
+- `scripts/funnel_confidence_scorer.py` — per-stage CoV-based confidence bands with treatment recommendation
+
+All scripts: stdlib only. `--help` and `--sample` work on all three.
+
+## References
+
+- `references/saas_forecasting_canon.md` — Skok, Tunguz, OpenView, BVP, Pacific Crest/KeyBanc, ProfitWell, Patrick Campbell
+- `references/cohort_analysis_canon.md` — Andrew Chen (a16z), Brian Balfour, Skok, Ramanujam, OpenView, Lenny Rachitsky, Reforge
+- `references/forecast_anti_patterns.md` — McKinsey, Tunguz, OpenView, MIT Sloan, Bain, Forrester, Pacific Crest
+
+## Assumptions
+
+- **Historical conversion is the prior, not the truth.** Last 4Q is weighted 70%, last 12Q is weighted 30%. The blend captures regime change (recent slowdown) without overfitting to a single bad quarter. Window + weighting are surfaced in every output.
+- **A forecast without a disclosed assumption block is theatre.** This is the skill's hard rule. The CLI refuses to omit the assumption block.
+- **Cohort decomposition reveals leaks 2-3 quarters before the consolidated number does.** Reporting NRR without per-cohort breakdown hides the leak.
+- **CoV (coefficient of variation) is the right discipline for stage confidence.** A stage with mean conversion 40% and stdev 4% (CoV 10%) is HIGH confidence; mean 40% stdev 20% (CoV 50%) is VERY LOW. The same average masks very different reliability.
+- **Industry profile tunes priors, not truth.** Profile shifts default stage-conversion rates by industry; your historical data overrides.
+- **The skill emits three numbers and an assumption block.** The CRO picks the commit number, owns the trade-off, and walks the board through the variance.
+
+## Anti-patterns
+
+- **Single-number forecast with no confidence band.** The board asks for "the number"; the discipline is to present three with named assumptions. See `forecast_anti_patterns.md`.
+- **Using last-12-quarter conversion blindly.** Hides recent slowdown. The 70/30 blend on last-4Q vs. last-12Q corrects this.
+- **Reporting NRR without cohort decomposition.** The consolidated number can be flat while a recent cohort is leaking 15 pp; the leak surfaces in the topline 2-3 quarters later. Always decompose.
+- **Treating best-case as commit.** The CFO will eat you. Best-case includes weighted-stage opps that have a < 50% time-to-close probability; commit only includes commit-grade stages.
+- **Hiding the assumption block.** The skill refuses; if you remove it manually, you own the theatre.
+- **No leaky-cohort callout.** If `cohort_arr_projector.py` flags a cohort and you suppress the flag in the deck, the leak owns you next quarter.
+- **Ignoring late-stage opp age.** A "verbal" deal that's been verbal for 180 days is not a commit. The bookings forecaster downweights stalled opps automatically; do not re-up them by hand.
+- **No pipeline-coverage check.** Industry rule of thumb: forecast > pipeline ÷ 3 is anti-pattern. The tool surfaces the ratio; respect it.
+
+## Distinct from
+
+- **`finance/financial-analysis`** — backward-looking financial close, GAAP/IFRS reporting, variance vs. budget. commercial-forecaster is forward-looking pipeline math.
+- **`c-level-advisor/cfo-advisor`** — strategic multi-year financial planning, fundraise scenarios, runway. commercial-forecaster is one input to the CFO, not the strategy.
+- **`c-level-advisor/cro-advisor`** — strategic CRO judgment: "do we hire a VP Sales?", territory design, comp plan, when to add a sales engineer. commercial-forecaster is the math the CRO uses; cro-advisor is the judgment the CRO applies.
+- **sibling `pricing-strategist`** — sets the price (model + range). commercial-forecaster *projects revenue at those prices*. Pricing comes first; forecast comes after.
+- **sibling `deal-desk`** — per-deal scoring + discount approval routing. commercial-forecaster aggregates the pipeline that deal-desk operates on day-by-day.
+
+## Forcing-question library (Matt Pocock grill discipline)
+
+Walked one at a time by `/cs:grill-commercial` or the orchestrator. Recommended answer + canon citation per question. Never bundled.
+
+1. **"What conversion rate are you using, and is it last-4Q or last-12Q?"**
+   Recommended: a 70/30 blend (last-4Q weighted 70%, last-12Q weighted 30%). Last-12Q alone hides recent slowdown; last-4Q alone overfits one bad quarter.
+   Canon: Tomasz Tunguz (Theory Ventures) — forecasting studies show single-window conversion estimates miss regime change at ~3-quarter lag.
+
+2. **"What's your pipeline coverage ratio, and is your commit above pipeline ÷ 3?"**
+   Recommended: 3x coverage is the SaaS-industry floor; below 3x means your commit is structurally unsupported.
+   Canon: Pacific Crest / KeyBanc SaaS Survey — top-quartile SaaS companies maintain 3.0-4.5x pipeline coverage against committed bookings.
+
+3. **"Can you show me NRR by cohort, not just consolidated?"**
+   Recommended: never report a consolidated NRR without the per-cohort breakdown. Leaky cohorts hide in averages.
+   Canon: Patrick Campbell (ProfitWell) + David Skok — cohort-driven retention decomposition surfaces leaks 2-3 quarters before consolidated NRR moves.
+
+4. **"What's the variance (CoV) on each stage's conversion rate over the last 12 quarters?"**
+   Recommended: CoV < 10% → commit-grade; 10-25% → moderate; 25-50% → soft floor only; > 50% → do not use this stage for forecasting.
+   Canon: MIT Sloan forecasting research / Hyndman & Athanasopoulos (*Forecasting: Principles and Practice*) — CoV on the input series predicts forecast accuracy more reliably than mean.
+
+5. **"How long has each late-stage opp been in late-stage?"**
+   Recommended: stage-age > 2x the median stage-duration → treat as stalled, exclude from commit, keep in pipe-only.
+   Canon: David Skok (*For Entrepreneurs*) — stalled-opp identification by stage-age is the #1 forecast hygiene practice in top-decile SaaS pipelines.
+
+6. **"Is your best-case forecast within 30% of your pipe-only?"**
+   Recommended: if best-case is < 50% of pipe-only, your stage-conversion assumptions are pessimistic and you're sandbagging; if best-case > 80% of pipe-only, you're hockey-sticking.
+   Canon: McKinsey research on forecast bias + OpenView SaaS benchmarks — most teams operate in one of two failure modes: sandbagging (commit << earnings) or hockey-sticking (commit >> earnings).
+
+7. **"What assumption block accompanies the number on the board slide?"**
+   Recommended: every forecast number on a board slide names (a) the conversion rate, (b) the data window, (c) the weighting choice, (d) the pipeline-coverage ratio. No assumption block = the slide is theatre.
+   Canon: Bain & Company commercial-forecasting practice + Forrester pipeline-coverage research — undisclosed-assumption forecasts have 2.3x higher variance against actuals than disclosed-assumption forecasts.
+
+Walk depth-first. Lock 1-3 before opening 4-7. After all 7 are answered, invoke `bookings_forecaster.py` → `cohort_arr_projector.py` → `funnel_confidence_scorer.py` in sequence.

package/commercial/commercial-policy/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: commercial-policy
+description: "Use when designing or revising a company's commercial policy — the rules of engagement governing discounts off list price, approver thresholds, exception flows, and the deal framework that Deal Desk and AEs operate under. Covers discount matrix design (ARR band x term length x payment terms x strategic value), commercial policy design, exception policy, discount governance, approval thresholds, deal framework structure, and policy linting (contradictions, gaps, cliff edges, gaming surfaces). For Head of Commercial, Head of Deal Desk, VP Sales, or RevOps at the policy-design moment — NOT per-deal application (that is deal-desk) and NOT pricing model selection (that is pricing-strategist)."
+version: 2.8.0
+author: claude-code-skills
+license: MIT
+tags: [commercial, discount-policy, discount-matrix, exception-flow, governance, deal-framework, commercial-discipline]
+compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
+---
+
+# commercial-policy
+
+## Purpose
+
+Design the **rules of engagement** that govern discounting off list price — the artifact that Deal Desk and AEs operate under. Three deterministic tools:
+
+1. `discount_matrix_builder.py` — builds a 4-dimensional matrix (ARR band × term length × payment terms × strategic value tier), each cell carrying an approved discount band backed by current win-rate + NRR data, plus an approver tier (AE / Manager / Director / VP / CFO).
+2. `exception_router.py` — when an asks-for-discount lands outside the matrix, routes it through the named approver chain, attaches required compensating commitments (multi-year prepay + named expansion path + reference commitment + MSA tightening), produces machine-readable audit-trail metadata, and flags precedent risk if 3+ similar exceptions have landed in the trailing quarter.
+3. `policy_linter.py` — lints the matrix for governance defects: approver inversion, band inversion, margin-floor violation, coverage gaps, cliff edges, undefined strategic tiers, inconsistent margin floors, thin data backing.
+
+The output is the **policy itself** (matrix + exception flow + lint report), not a per-deal application of it.
+
+## When to use
+
+- A new Head of Commercial or Head of Deal Desk is writing the company's first formal commercial policy
+- The existing matrix is older than 6 months and discount drift is showing in margin reviews
+- Reps are citing "Maria approved 28% on Acme last quarter" as precedent and you need to break the precedent loop
+- Q-over-Q exception count is rising and you suspect the matrix bands are mispriced
+- CFO has tightened the margin floor and the matrix needs to be rebuilt against the new constraint
+- A board / exec is asking "why do we discount this much?" and you need a data-backed defensible policy
+
+**Do NOT use this skill to:**
+- Approve a specific deal — that's `commercial/skills/deal-desk`
+- Set the pricing model + list price — that's `commercial/skills/pricing-strategist`
+- Author a proposal / SOW / MSA prose — that's `business-growth/contract-and-proposal-writer`
+- Make the strategic "when do we hire a VP Sales" call — that's `c-level-advisor/cro-advisor`
+
+## Workflow
+
+1. **Audit current discount distribution.** Pull the last 4 quarters of closed-won + closed-lost deals from CRM. Fill `assets/policy_design_template.md` (~20 minutes). Capture: `arr`, `discount_pct`, `term_months`, `payment_terms_days`, `strategic_value`, `win_lost`, `nrr_12mo` per deal.
+
+2. **Design the data-backed matrix.** Run `scripts/discount_matrix_builder.py --input policy_intake.json --profile {saas|enterprise-software|api|marketplace|services}`. Output is a 4-dimensional matrix with approved discount band + approver tier + margin floor + observed win-rate + observed NRR per cell. Cells with `n < 5` observed deals are flagged `THIN`.
+
+3. **Design the exception flow.** Run `scripts/exception_router.py --sample` to see the structure. For each severity band of exception (0-5 pts over, 5-10, 10-20, 20+), the router enforces required compensating commitments. Codify the flow in your policy doc; the router becomes the operational implementation.
+
+4. **Lint the matrix.** Run `scripts/policy_linter.py --input matrix.json`. Get a ranked findings report — BLOCKER / MAJOR / MINOR — across 10 lint rules. Resolve every BLOCKER before publishing the matrix to AEs.
+
+5. **Publish + quarterly review.** Publish the matrix as a versioned artifact. Re-run the builder and the linter every quarter against the new 4-quarter rolling deal corpus. Cells where observed NRR < `target_nrr` are flagged for review.
+
+## Scripts
+
+| Script | Purpose | Industry profiles |
+|---|---|---|
+| `scripts/discount_matrix_builder.py` | 4-dim data-backed matrix with approver tiers + margin floors | saas, enterprise-software, api, marketplace, services |
+| `scripts/exception_router.py` | Routes exception requests with compensating commitments + audit trail | n/a (matrix-driven) |
+| `scripts/policy_linter.py` | 10-rule lint pass over the matrix | n/a (deterministic across profiles) |
+
+All three: stdlib-only, `--help`, `--sample`, `--input <json>`, `--output {markdown,json}`.
+
+## References
+
+- `references/discount_governance_canon.md` — Discount governance evidence base: OpenView Partners benchmarks, David Skok (For Entrepreneurs) discount math, Tomasz Tunguz on discount distribution, Bessemer State of the Cloud, KeyBanc Capital Markets SaaS Survey, Bridge Group AE-compensation research, RevOps Co-op playbooks, Forrester deal-desk research. 8 sources.
+- `references/policy_design_canon.md` — Policy-as-artifact design: SaaStr (Jason Lemkin), Winning by Design (Jacco van der Kooij) on commercial discipline, Forrester deal-desk maturity research, MIT Sloan on incentive-system gaming, McKinsey on commercial-policy effectiveness, Bain *Pricing Power*, Salesforce CPQ implementation guides. 7 sources.
+- `references/policy_anti_patterns.md` — 8 named anti-patterns with sourced studies + countermeasures + lint-rule mapping: precedent-sets-policy, no-data-backing, no-compensating-commitments, approver/margin misalignment, no audit trail, cliff edges, undefined "strategic value", no quarterly review. 8 sources.
+
+## Assumptions
+
+- The skill assumes the **pricing model and list price already exist** (set via `commercial/skills/pricing-strategist`). Commercial-policy governs **discounts off list** — it does not set list.
+- The CFO owns the `min_margin_pct` constraint (margin floor). The CRO / Head of Deal Desk owns the `max_discount_pct_without_exception` constraint (band cap). The skill keeps these inputs separate by design (per Bain *Pricing Power* — mixing accountability is the most common cause of policy drift).
+- Industry profiles bake in *customary* band widths. Companies with idiosyncratic economics should pass overrides via the input JSON.
+- The matrix is data-backed but **not data-driven**: the band is set by the constraints + profile; observed data is annotation that tells you whether the cell is performing. If observed NRR < target, that's a signal to **review the band**, not to keep discounting deeper.
+- "Strategic value" tiers (`logo`, `expansion`, `lighthouse`) are useful only if defined with concrete tests. The lint rule L06 enforces this.
+- This is a policy-design skill, not a deal-approval skill. It never says "approve" — it produces the matrix + exception flow that **deal-desk** then applies.
+
+## Anti-patterns
+
+- **Setting discount bands without data backing.** "VP Sales argued for it in a Slack thread" is not data backing. If you can't show win-rate and NRR for the band, the band is rhetoric. (Caught by `data_backing` per cell + lint L08.)
+- **Letting precedent set policy.** "Maria approved 28% on Acme last quarter" is not a band — it's an exception that didn't break the policy. `exception_router.py` flags 3+ similar exceptions as a signal that **the matrix is wrong**, not the deal. (Anti-pattern AP-1.)
+- **Approving exceptions without compensating commitments.** Discount-for-nothing is a leak (Winning by Design). Every exception severity band requires non-negotiable commitments. (`exception_router.COMPENSATING_LIBRARY`.)
+- **Cliff edges at round-number ARR thresholds.** A hard $100K threshold produces deal-size gaming within 2 quarters (MIT Sloan agency theory). Smooth the gradient. (Lint L05.)
+- **"Strategic value" as an undefined catch-all.** If "strategic" is undefined, within a quarter 60% of deals will be flagged strategic and the matrix is dead. Define with concrete tests. (Lint L06.)
+- **No quarterly review.** Markets shift; matrices unchanged for 12 months are mispriced. Re-run the builder and linter every quarter. (Anti-pattern AP-8.)
+- **Mixing CFO and CRO accountabilities.** CFO owns the margin floor; CRO owns the band cap. Same accountable owner = predictable drift toward whatever they're compensated on (Bain *Pricing Power*).
+- **Skipping the lint pass before publishing.** BLOCKER findings (approver inversion, margin-floor violation, inverted bands) make the policy unsignable. Lint is the gate, not the after-action review.
+
+## Distinct from
+
+| Sibling | Scope | Difference |
+|---|---|---|
+| `commercial/skills/deal-desk` | **Applies** the policy to one deal at a time | Commercial-policy **designs the policy itself**. Deal-desk consumes the matrix; commercial-policy produces it. |
+| `commercial/skills/pricing-strategist` | Sets pricing **model** (per-seat / usage / value / tiered) + **list price** | Commercial-policy governs **discounts off list**. Pricing-strategist sets the menu; commercial-policy governs the menu's discount discipline. |
+| `c-level-advisor/cro-advisor` | Strategic CRO judgment ("when do we hire VP Sales?", "is our motion product-led or sales-led?") | Strategic, not operational. Commercial-policy is the artifact CRO commissions; it isn't CRO judgment itself. |
+| `c-level-advisor/cfo-advisor` | Margin floor + unit-economics judgment | The CFO supplies `min_margin_pct` to commercial-policy as an input. Commercial-policy **operationalizes** the CFO's constraint as per-cell margin floors. |
+| `business-growth/contract-and-proposal-writer` | Authors proposal/SOW/MSA **prose** | Commercial-policy emits structured matrix + audit-trail JSON, not customer-facing prose. |
+
+## Forcing-question library (Matt Pocock grill discipline)
+
+Walked one at a time by `/cs:grill-commercial` or the Commercial orchestrator before the skill runs. Recommended answer + canon citation per question. Never bundled.
+
+1. **"What's your observed discount distribution across the last 4 quarters — and is the median inside or outside your current matrix?"**
+   Recommended: pull the corpus before designing any band. If the observed median is outside the matrix, the matrix is rhetoric.
+   Canon: OpenView SaaS Benchmarks; RevOps Co-op playbooks. Anti-pattern AP-2.
+
+2. **"What's the win-rate AND the 12-month NRR for deals at your current 'max discount' band?"**
+   Recommended: both, not one. A band with high win-rate but low NRR is buying logos with leaky-bucket retention. Tunguz benchmarks: top-NRR-quartile companies discount 6 pts less than bottom quartile.
+   Canon: Tomasz Tunguz; Bessemer State of the Cloud.
+
+3. **"Who at the company owns the margin floor, AND who owns the discount-band cap — are those the same person?"**
+   Recommended: CFO owns floor; CRO/Head of Deal Desk owns cap. Same owner = drift toward what they're compensated on.
+   Canon: Bain *Pricing Power* — separation of accountability is the structural fix. Anti-pattern AP-4.
+
+4. **"How is 'strategic value' defined in your current policy — with concrete tests, or with adjectives?"**
+   Recommended: concrete tests. "Top-20 named account in 2026 target list" is a test; "important customer" is not.
+   Canon: SaaStr (Lemkin); Forrester deal-desk research. Lint rule L06. Anti-pattern AP-7.
+
+5. **"For exceptions above your matrix max, what compensating commitments are required — and are they in writing before the approver signs?"**
+   Recommended: minimum multi-year prepay + named expansion path; deeper exceptions require reference commitment + MSA tightening + executive sponsor.
+   Canon: Winning by Design (van der Kooij); McKinsey B2B pricing studies. Anti-pattern AP-3.
+
+6. **"Has the same kind of exception been approved 3+ times in the trailing quarter — and if so, is the matrix wrong?"**
+   Recommended: 3+ similar exceptions means the band is mispriced. Rebuild the matrix; don't keep approving exceptions.
+   Canon: OpenView discount drift studies; `exception_router._precedent_risk`. Anti-pattern AP-1.
+
+7. **"When was the last time you re-ran the matrix against the previous 4 quarters of data?"**
+   Recommended: quarterly. Annual review is too slow; the disciplined cohort revises quarterly.
+   Canon: OpenView benchmarks; RevOps Co-op. Anti-pattern AP-8.
+
+8. **"For every exception in the last quarter, is there a machine-readable audit-trail record — or is the approval in Slack and email?"**
+   Recommended: structured record in CPQ or equivalent. Slack/email approvals don't survive year-2 renewal negotiations.
+   Canon: Salesforce CPQ best practices; Forrester deal-desk maturity research. Anti-pattern AP-5.
+
+Walk depth-first. Lock 1-4 before opening 5-8. After all 8 are answered, invoke `discount_matrix_builder.py` → `policy_linter.py` → `exception_router.py --sample` in sequence to produce the policy artifact.
+
+## Quick examples
+
+```bash
+# Design the matrix
+python3 scripts/discount_matrix_builder.py --sample
+python3 scripts/discount_matrix_builder.py --input policy_intake.json --profile saas --output json > matrix.json
+
+# Lint the matrix
+python3 scripts/policy_linter.py --sample
+python3 scripts/policy_linter.py --input matrix.json
+
+# Walk the exception flow
+python3 scripts/exception_router.py --sample
+python3 scripts/exception_router.py --input request.json --output json
+```
+
+The sample matrix lints to **FAIL** with 4 BLOCKERs + 6 MAJORs + 2 MINORs — by design, to exercise every rule path. A real policy intake should lint to PASS or PASS_WITH_WARNINGS. The sample exception (42% on a $320K logo deal) routes to AE → Sales Manager → Director → VP Sales with 3 required compensating commitments (multi-year 36mo, prepay, named expansion path).