Margin simulation

Margin Simulation

Model the full commercial viability of any agency engagement — from a single campaign to a multi-year retainer — using deterministic P&L analysis, Monte Carlo simulation for uncertainty quantification, leakage detection, sensitivity analysis, and scenario modeling.

How This Skill Thinks

This skill does not just calculate margin. It orchestrates a pipeline:

1. Script execution (scripts/margin_engine.py): Runs the deterministic P&L, Monte Carlo simulation (5,000 draws), leakage detection, and sensitivity analysis programmatically
2. Reference lookup (references/leakage_and_pricing.md): Provides benchmark data, leakage taxonomy, pricing strategies, and the 70/30 model impact on margin
3. Qualitative judgment (Claude): Interprets results in context — client relationship dynamics, market positioning, competitive pressure, historical patterns — and shapes the recommendation
4. Visual output (Visualizer): Renders the margin dashboard as an inline widget with Monte Carlo distribution, leakage waterfall, and scenario cards

The script produces numbers. Claude produces insight. The Visualizer makes it actionable. None of these replaces the other.

Quick Reference

Resource	Purpose	Usage
scripts/margin_engine.py	Core simulation engine — deterministic P&L + Monte Carlo (5K runs) + leakage detection + sensitivity analysis + scenario modeling	python margin_engine.py --input config.json --output margin.json
references/leakage_and_pricing.md	Leakage taxonomy (8 patterns, 3 severity tiers), margin benchmarks by engagement type, Monte Carlo methodology, pricing strategies, 70/30 impact analysis	Read for benchmarks and methodology explanation

How to Use the Script

Build a config JSON from the user's inputs, then run the engine:

import sys
sys.path.insert(0, "<skill-path>/scripts")
from margin_engine import MarginSimulator

config = {
    "client_name": "FreshBrew Coffee",
    "engagement_type": "retainer",
    "monthly_revenue": 15000,
    "contract_months": 12,
    "margin_target": 0.30,

    "fte_costs": [
        {"name": "Creative (mid)", "monthly_amount": 1250, "seniority": "mid", "fte": 0.5},
        {"name": "Account (mid)", "monthly_amount": 560, "seniority": "mid", "fte": 0.2},
        {"name": "Data (mid)", "monthly_amount": 450, "seniority": "mid", "fte": 0.15},
    ],
    "vendor_costs": [],
    "tool_costs": [{"name": "Design tools", "monthly_amount": 150}],
    "ai_infrastructure": 500,

    # Leakage flags — True means protection exists
    "has_revision_cap": True,
    "has_pm_hours": False,
    "has_change_order": True,
    "has_client_sla": True,
    "has_vendor_caps": True,
    "has_seniority_match": True,
    "has_adhoc_cap": True,
    "has_tool_passthrough": False,
}

sim = MarginSimulator(config)
result = sim.run()
# result.margin_pct, result.monte_carlo, result.leakage_items, result.scenarios, etc.

If the user has already run fte-capacity-sizing, use those FTE costs directly — the capacity model's output feeds this simulation's input.

Calibration note: Monte Carlo results depend on uncertainty parameters. Default uncertainty is ±10% on FTE costs, ±15% on vendor costs. If the user provides actual variance data or historical overrun rates, use those instead. The simulation uses N=5,000 draws by default; this produces stable percentiles (±0.5pp). Numpy is preferred but the engine falls back to pure Python if unavailable.

Trigger Conditions

Activate this skill when:

• The user asks about margin, profitability, P&L, or EBITDA for a client or scope
• The user wants to know if a fee can support the delivery cost
• The user asks "what should we charge?" or "is this fee enough?"
• The fte-capacity-sizing produces a cost model that needs financial validation
• The scope-audit identifies commercial risk and routes here
• The agency-request-intake-router flags a financial concern
• The user is building a proposal and needs pricing validation

Simulation Process

Work through all eight steps. The script handles Steps 2-7 computationally; you handle Steps 1 and 8 (context gathering and recommendation framing).

Step 1 — Capture Revenue and Cost Inputs

Gather from the user or from upstream skills:

• Revenue: Monthly fee, retainer amount, or project fee (÷ months)
• FTE costs: From fte-capacity-sizing output or direct input (role × rate × FTE)
• Vendor costs: Production, media ops, freelancers, specialized services
• Tool costs: SaaS subscriptions, platform licenses, API costs
• AI infrastructure: Claude API, MCP hosting, agent pipeline costs (default: $500/mo)
• Contract term: Duration in months (default: 12)
• Margin target: Default 30%, adjustable by user

If any cost category is missing, flag it as ⚠️ and use benchmarks from references/leakage_and_pricing.md.

Step 2 — Build Deterministic P&L

Calculate the base-case margin:

Total delivery cost = FTE cost + Vendor cost + Tool cost + AI infra
                    + Overhead (12% of FTE + Vendor)
                    + Rework buffer (10% of FTE cost)
                    + Risk buffer (5% of FTE + Vendor)

Gross margin = Revenue - Total delivery cost
Margin % = Gross margin / Revenue × 100
OI / EBITDA impact = Gross margin × Contract months

Step 3 — Detect Leakage

Check the scope for each of 8 leakage patterns. For each unprotected source, calculate the monthly cost impact and the adjusted margin. See references/leakage_and_pricing.md → "Leakage Taxonomy" for the full pattern catalog.

Step 4 — Run Monte Carlo Simulation

Execute 5,000 Monte Carlo draws to model margin uncertainty. Each draw applies random perturbation to costs, plus stochastic scope creep and client delay events. The output is a margin distribution with P10/Mean/P90 range and probability of falling below target.

Read references/leakage_and_pricing.md → "Monte Carlo Methodology" for the full algorithm specification.

Step 5 — Run Sensitivity Analysis

Test each cost driver with a ±20% shock to identify which driver has the largest marginal impact on margin. This answers: "Where should I negotiate?" — focus energy on the most sensitive driver.

Step 6 — Build Scenarios

Generate 4 scenarios:

• Base case: Deterministic P&L as calculated
• Optimistic: 15% cost reduction (AI uplift, no scope creep)
• Pessimistic: 30% cost increase (scope creep + rework + delays)
• With leakage: Base cost + all detected leakage impacts

Step 7 — Determine Verdict

Issue a commercial verdict based on margin level, Monte Carlo risk, and leakage exposure:

Condition	Verdict
Margin ≥ 40%	Highly viable
Margin 30-40% (target met)	Viable
Margin 15-30%	Tight — vulnerable to creep
Margin 0-15%	Underfunded — near breakeven
Margin < 0%	Non-viable — losing money

Monte Carlo enrichment: if P(below target) > 50%, flag structural risk regardless of base margin.

Step 8 — Frame the Recommendation

This is your qualitative layer — the script produces numbers, you produce judgment:

• What should the user do about it? (Renegotiate? Reduce scope? Increase AI automation?)
• What's the client context? (New relationship worth investing in? Legacy client with history of creep?)
• What are the alternatives? (Walk away? Restructure as project-based? Phase the work?)

Output Format

Produce the margin simulation in TWO forms: first as an inline visual artifact (rendered in chat via the Visualizer), then as a structured markdown report below it.

Visual Artifact (Primary)

Render the margin dashboard as an inline HTML widget using the Visualizer. The widget should display:

• A header bar color-coded by verdict: dark green (Highly viable), green (Viable), amber (Tight), orange (Underfunded), red (Non-viable)
• A top metrics row with 4 cards: Monthly revenue, Total cost, Margin %, OI/EBITDA
• A cost waterfall — stacked horizontal bar showing FTE / Vendor / Tools / AI / Overhead / Rework / Buffer as proportional segments, labeled with $ and %
• A Monte Carlo range — a mini horizontal bar showing P10–Mean–P90 with probability badges:
  • P(below target) as a percentage badge
  • P(negative) as a red badge if > 5%
• A leakage section — each leakage source as a row with severity badge, monthly $ impact, and fix
• A scenario comparison — 4 cards (Base / Optimistic / Pessimistic / With leakage) each showing margin % and verdict
• An action footer with sendPrompt() buttons:
  • "Generate change order to improve margin for [client]" → change-order-generator
  • "Resize team to reduce cost for [client]" → fte-capacity-sizing
  • "Draft executive memo on commercial risk for [client]" → executive-growth-memo

Use CSS variables for light/dark mode. Keep it compact — a finance dashboard card.

Markdown Report (Secondary)

After the visual artifact, produce the full simulation as markdown:

## 💰 MARGIN SIMULATION — [Client / Project Name]

### Executive summary
[2-3 sentences: verdict, base margin, Monte Carlo risk, top leakage source, key recommendation]

### Revenue
| Metric | Value |
|--------|-------|
| Monthly revenue | $[X] |
| Contract term | [N] months |
| Total contract value | $[X] |

### Cost structure
| Category | Monthly | % of revenue | Notes |
|----------|---------|-------------|-------|
| FTE / labor | $[X] | [Y]% | [role breakdown] |
| Vendor / third-party | $[X] | [Y]% | |
| Tools / platforms | $[X] | [Y]% | |
| AI infrastructure | $[X] | [Y]% | Claude, MCP, agents |
| Overhead (12%) | $[X] | [Y]% | |
| Rework buffer (10%) | $[X] | [Y]% | |
| Risk buffer (5%) | $[X] | [Y]% | |
| **Total delivery cost** | **$[X]** | **[Y]%** | |

### Margin
| Metric | Value |
|--------|-------|
| Gross margin | $[X]/mo |
| Margin % | [X]% |
| OI / EBITDA impact | $[X] over [N] months |
| Target margin | [X]% |
| Verdict | [verdict] |

### Monte Carlo simulation (N=5,000)
| Metric | Value |
|--------|-------|
| Mean margin | [X]% |
| Median margin | [X]% |
| P10 (pessimistic) | [X]% |
| P90 (optimistic) | [X]% |
| Std deviation | [X]pp |
| P(below target) | [X]% |
| P(negative) | [X]% |

### Leakage analysis
| Source | Severity | Monthly impact | Fix |
|--------|----------|---------------|-----|
[One row per leakage source]
| **Total leakage** | | **$[X]/mo** | |
| **Adjusted margin** | | **[X]%** | |

### Sensitivity analysis
| Cost driver | Base value | +20% shock | Margin impact |
|------------|-----------|------------|---------------|
[Ranked by absolute impact]

### Scenario comparison
| Scenario | Cost | Margin | Verdict |
|----------|------|--------|---------|
[4 scenarios]

### Recommendations
[Numbered list of specific actions based on verdict, Monte Carlo, leakage, and sensitivity]

When Information Is Incomplete

If the user provides only partial cost data:

• Use benchmarks from references/leakage_and_pricing.md for missing categories
• If FTE costs are unknown, suggest running fte-capacity-sizing first
• Flag estimated values with ⚠️ Estimated
• Run the simulation with available data and note confidence level

Examples

Example 1 — Viable retainer:

User: "FreshBrew pays $15K/month. Our team costs $4K/month (from capacity model). No vendor costs. Tools are $300/month. Is this viable?"

→ Total cost: ~$5,800/mo. Margin: 61%. Monte Carlo P10: 48%. Verdict: Highly viable. No leakage if revision cap and CO mechanism are in place.

Example 2 — Thin margin with leakage:

User: "Client pays $25K/month. FTE cost is $14K, vendors $3K, tools $1K. No revision caps, no change order process, no client approval SLA."

→ Base margin: 18% (Tight). 3 leakage sources add $4.5K/mo. Adjusted margin: 0.2%. Monte Carlo P(negative): 35%. Verdict: Underfunded. Recommendation: fix leakage sources first — that alone recovers 18pp of margin.

Example 3 — Non-viable project:

User: "We quoted $50K for a 3-month project. Team cost is $22K/month including senior strategist and creative director."

→ Revenue: $16.7K/mo. Cost: $28K/mo. Margin: -68%. Verdict: Non-viable. Fee would need to be $105K+ to hit 30% margin, or scope must be cut by 60%.

Skill Chaining

Condition	Next skill
Need FTE cost inputs	fte-capacity-sizing (upstream)
Leakage requires scope fix	scope-audit or change-order-generator
Need to reduce headcount to improve margin	fte-capacity-sizing (resize)
Leadership needs commercial risk summary	executive-growth-memo
Margin approved, campaign ready	campaign-launch-qa