Case Study 6.1: Acme Corp — From Copy-Paste to a Pricing Module

The Problem

It's Marcus's turn to be frustrated. He's reviewing Priya's scripts before approving them for the shared analytics folder. He's found that the gross margin calculation appears three times across her scripts — with three slightly different implementations.

"Which one is right?" he asks.

Priya doesn't have a confident answer. She wrote them at different times, refined them independently, and now can't say for certain which version incorporates the most recent change Sandra made to the COGS allocation methodology.

"This," Marcus says, "is how we ended up with seven versions of the pricing spreadsheet."

The Refactor

Priya spends a Saturday morning consolidating. Her goal: one authoritative place for every business rule, imported by every script that needs it.

She creates acme_business_rules.py — a module of functions:

"""
acme_business_rules.py
Authoritative source for Acme Corp business calculations.

When business rules change, update this file.
All scripts that import from here automatically get the update.
"""

# ── MARGIN CALCULATIONS ───────────────────────────────────────────────────────

def gross_margin(revenue, cogs):
    """
    Gross margin = (Revenue - COGS) / Revenue

    Note: COGS includes product cost and direct freight.
    Does NOT include warehouse overhead (per CFO memo 2024-02-01).
    """
    if revenue == 0:
        return 0.0
    return (revenue - cogs) / revenue


def operating_margin(revenue, cogs, operating_expenses):
    """
    Operating margin after SG&A.

    Operating expenses = SG&A + warehouse overhead (per CFO memo 2024-02-01).
    Excludes interest and taxes.
    """
    if revenue == 0:
        return 0.0
    gp = revenue - cogs
    op = gp - operating_expenses
    return op / revenue


# ── CUSTOMER TIER LOGIC ───────────────────────────────────────────────────────

# Updated per Sales Policy v2.3 (effective 2024-01-15)
_TIER_DISCOUNTS = {
    "Platinum": 0.20,
    "Gold": 0.15,
    "Silver": 0.10,
    "Bronze": 0.05,
    "Standard": 0.00,
}

def customer_discount_rate(tier):
    """Return discount rate for a tier. Unknown tiers get 0%."""
    return _TIER_DISCOUNTS.get(tier, 0.00)


def tier_from_annual_spend(annual_spend):
    """
    Determine customer tier based on annual spend.

    Thresholds per Sales Policy v2.3:
      Platinum: $250,000+
      Gold: $100,000 – $249,999
      Silver: $25,000 – $99,999
      Bronze: $5,000 – $24,999
      Standard: below $5,000
    """
    if annual_spend >= 250_000:
        return "Platinum"
    elif annual_spend >= 100_000:
        return "Gold"
    elif annual_spend >= 25_000:
        return "Silver"
    elif annual_spend >= 5_000:
        return "Bronze"
    else:
        return "Standard"

The Test

Before using the module, Priya writes a few manual checks:

# Verify the gross margin function
assert gross_margin(100_000, 63_000) == 0.37, "Should be 37%"
assert gross_margin(0, 0) == 0.0, "Should handle zero revenue"

# Verify tier assignment
assert tier_from_annual_spend(300_000) == "Platinum"
assert tier_from_annual_spend(125_000) == "Gold"
assert tier_from_annual_spend(4_999) == "Standard"

print("All checks passed ✓")

All pass. She now has confidence in the implementation.

The Rollout

Priya updates each of her existing scripts to import from acme_business_rules.py:

# In acme_daily_scorecard.py (before)
gross_margin_rate = (revenue - (revenue * 0.63)) / revenue  # Hardcoded COGS assumption

# After
from acme_business_rules import gross_margin
gross_margin_rate = gross_margin(revenue, actual_cogs)  # Uses real COGS

When Sandra asks for the COGS definition to be updated (a memo changes which costs are included), Priya updates acme_business_rules.py once. Every script that imports it gets the change automatically.

Marcus approves the scripts for the shared folder. "This is how it should work," he says. Coming from Marcus, that's high praise.

Discussion Questions

1. The original scripts worked correctly in isolation but caused problems in combination. What organizational failure does this represent, and how do functions/modules solve it?

2. Priya adds manual assertion checks before deploying her module. Why is this important? What categories of errors can assertions catch, and what can they not catch?

3. The tier_from_annual_spend function has hardcoded thresholds. What would need to change if Acme Corp updated their tier thresholds quarterly based on market conditions?

4. Marcus's concern was "which one is right?" How does creating a centralized module with clear documentation (including references to source policy documents) address the governance problem, not just the technical one?