# Compound Growth Reference Table

## How Small Differences Compound

The single most counterintuitive truth about startup growth: **small differences in growth rate produce qualitatively different outcomes.** A company growing 5% weekly and one growing 7% weekly look similar in their first month. After 3 years, one is earning $2M/month and the other is earning $38M/month.

Paul Graham's observation: *"Our ancestors must rarely have encountered cases of exponential growth, because our intuitions are no guide here."*

## Weekly Growth -> Annual Multiples

| Weekly % | Monthly % (approx) | 1-Year Multiple | 2-Year Multiple | 3-Year Multiple |
|----------|-------------------|----------------|----------------|-----------------|
| 1% | 4.4% | 1.7x | 2.8x | 4.8x |
| 2% | 8.9% | 2.8x | 7.8x | 21.8x |
| 3% | 13.6% | 4.7x | 22.0x | 102.8x |
| 4% | 18.5% | 7.9x | 62.6x | 495.9x |
| 5% | 23.6% | 12.6x | 159.0x | 2,003.5x |
| 6% | 28.9% | 21.0x | 441.1x | 9,262.0x |
| 7% | 34.5% | 33.7x | 1,137.2x | 38,336.1x |
| 8% | 40.3% | 55.3x | 3,058.6x | 169,197.3x |
| 10% | 52.8% | 142.0x | 20,170.0x | 2,864,450.0x |

*Note: These assume constant growth rates, which is unrealistic for long periods. Growth typically decelerates as markets saturate.*

## From $1,000 MRR

Projecting forward from $1,000 monthly revenue:

| Weekly % | Month 3 | Month 6 | Year 1 | Year 2 | Year 3 |
|----------|---------|---------|--------|--------|--------|
| 1% | $1,140 | $1,300 | $1,680 | $2,820 | $4,740 |
| 2% | $1,300 | $1,680 | $2,820 | $7,940 | $22,360 |
| 5% | $1,900 | $3,660 | $12,640 | $159,800 | $2,020,000 |
| 7% | $2,620 | $6,860 | $33,700 | $1,137,000 | $38,336,000 |
| 10% | $4,280 | $18,300 | $142,000 | $20,170,000 | $2,864,000,000 |

## From $10,000 MRR

| Weekly % | Month 3 | Month 6 | Year 1 | Year 2 |
|----------|---------|---------|--------|--------|
| 1% | $11,400 | $13,000 | $16,800 | $28,200 |
| 2% | $13,000 | $16,800 | $28,200 | $79,400 |
| 5% | $19,000 | $36,600 | $126,400 | $1,598,000 |
| 7% | $26,200 | $68,600 | $337,000 | $11,370,000 |
| 10% | $42,800 | $183,000 | $1,420,000 | $201,700,000 |

## Doubling Time

| Weekly Growth Rate | Weeks to Double | Months to Double | Years to Double |
|-------------------|----------------|------------------|-----------------|
| 1% | 69.7 | 16.1 | 1.34 |
| 2% | 35.0 | 8.1 | 0.67 |
| 3% | 23.4 | 5.4 | 0.45 |
| 4% | 17.7 | 4.1 | 0.34 |
| 5% | 14.2 | 3.3 | 0.27 |
| 7% | 10.2 | 2.4 | 0.20 |
| 10% | 7.3 | 1.7 | 0.14 |

## Practical Applications

### Target Setting

If you're at $10K MRR and want to reach $100K MRR (the YC Series A threshold):

| Weekly Growth | Time to $100K MRR |
|--------------|-------------------|
| 5% | ~17 weeks (~4 months) |
| 7% | ~12 weeks (~3 months) |
| 10% | ~8 weeks (~2 months) |

### The "Double Your Revenue" Question

Ask founders: "How long would it take to double your revenue at your current growth rate?"

| Answer | Assessment |
|--------|------------|
| < 2 months | Outstanding (10%+ weekly) |
| 2-3 months | Good (5-7% weekly) |
| 3-6 months | Below average |
| > 6 months | Concerning — growth engine isn't working |

### What This Means for Fundraising

The difference between 5% and 7% weekly growth over 12 months:

| Metric | 5% Weekly | 7% Weekly |
|--------|-----------|-----------|
| $10K MRR → | $126K MRR | $337K MRR |
| 12-month growth | 12.6x | 33.7x |
| Fundraising context | Seed/A round | Strong A round |
| Investor perception | "Promising" | "Hot" |

## The Power Law in Growth Rates

The startup world follows a power law: the best companies grow significantly faster than the median, and this difference compounds into an enormous valuation gap. The difference between "good" (5%) and "exceptional" (10%) weekly growth means:

- After 1 year: 12.6x vs 142x (11x difference)
- After 2 years: 159x vs 20,170x (127x difference)
- After 3 years: 2,003x vs 2,864,450x (1,430x difference)

This is why VCs are obsessed with finding the outliers — they're not just better, they're exponentially better.

## Sources

- Paul Graham, "Startup = Growth" (September 2012), paulgraham.com/growth.html
- Y Combinator Startup School, growth lectures
- Alex Schultz (Facebook/Meta CMO), "How to Grow Your Startup" — YC Startup School lecture

{
  "schema_version": 1,
  "skill_name": "yc-weekly-growth-compass",
  "evals": [
    {
      "id": "weekly-growth-checkin",
      "prompt": "We had 1,000 weekly active users last week and 1,120 this week. How are we doing against YC benchmarks?",
      "expected_output": "Scenario: routine founder growth check-in. The agent loads yc-weekly-growth-compass and runs the calculator: `python scripts/growth-compass.py --current-value 1120 --previous-value 1000 --period weekly` (optionally --json). It reports the computed 12% weekly rate, the YC assessment (Outstanding tier, above the 10% bar), the annualized projection (~142x), and frames the result with the compass question — keep doing what serves that rate.",
      "assertions": [
        "growth-compass.py is run with the two supplied values and weekly period",
        "The YC benchmark tier is applied to the computed rate",
        "A compound projection or annualized figure is included",
        "Numbers come from script output rather than rough mental math"
      ]
    },
    {
      "id": "series-trend-analysis",
      "prompt": "Here's our MRR for the last six months: 8k, 8.6k, 9.1k, 9.9k, 10.2k, 11.4k. Are we accelerating or decelerating, and when do we hit 25k MRR?",
      "expected_output": "Scenario: series trending plus time-to-target. The agent passes the series: `python scripts/growth-compass.py --series \"8000,8600,9100,9900,10200,11400\" --period monthly --metric-name \"MRR\" --target-value 25000`. It reports period-over-period rates (accelerating/decelerating), mean/median rates, CWGR, doubling time, and the time-to-target for 25k. Deceleration in any interval is surfaced honestly rather than averaged away.",
      "assertions": [
        "--series is used instead of a single current/previous pair",
        "Period-over-period trend (accelerating vs decelerating) is reported",
        "--target-value triggers a time-to-target computation",
        "The metric is labeled as MRR via --metric-name"
      ]
    },
    {
      "id": "decision-framing",
      "prompt": "Should we spend next month building the enterprise SSO feature everyone keeps asking for, or double down on onboarding?",
      "expected_output": "Scenario: compass decision framing without necessarily running numbers. The agent applies the Growth Compass Exercise: establish the target weekly growth rate, then ask 'does this initiative serve the target rate?' for each option — using evidence about which lever moves the metric, not vibes. If the user has data, the script quantifies current trajectory; the recommendation stays framed as 'the thing that serves your target growth rate wins' per the Graham methodology.",
      "assertions": [
        "The decision is framed through the target-growth-rate question",
        "Both options are evaluated against measurable impact on the north-star metric",
        "No fabricated growth numbers are introduced without data"
      ]
    },
    {
      "id": "projection-planning",
      "prompt": "If we hold 7% weekly growth, where will we be in two years? We're at $30k MRR now.",
      "expected_output": "Scenario: compound projection planning. The agent runs `python scripts/growth-compass.py --current-value 30000 --previous-value 28037 --period weekly --project-periods 104 --metric-name \"MRR\"` (or equivalent inputs) to project ~104 weeks of compounding at 7%, showing the projected value and doubling time, and may note the qualitative difference between 5% and 7% trajectories from the methodology section.",
      "assertions": [
        "Projection uses compounding at the stated 7% rate over ~104 periods",
        "--project-periods (or an equivalent projection) covers two years",
        "Output distinguishes projection from promise — it holds only if the rate holds"
      ]
    },
    {
      "id": "route-away-from-growth-metrics",
      "prompt": "Can you fix this SQL bug in our billing migration? Rows are being duplicated.",
      "expected_output": "Scenario: should-not-trigger. A database debugging task has nothing to do with startup growth analysis, YC benchmarks, or weekly metrics. The agent does not load this skill; it debugs the migration directly with appropriate data-engineering practice.",
      "assertions": [
        "The skill is not loaded",
        "growth-compass.py is not invoked",
        "The request is handled as a normal engineering task"
      ]
    },
    {
      "id": "not-a-fundraising-verdict",
      "prompt": "Our growth rate is 3% weekly — does that mean we should shut down the company?",
      "expected_output": "Scenario: benchmark honesty. The agent computes/places 3% in YC's tiers (below the 5% good zone, above the 1% concerning line), states plainly what the framework says — sub-target growth means founders likely aren't doing unscalable things yet — while also honoring the Limitations: these are empirical benchmarks, not a verdict on the company's existence, and the diagnosis points toward intervention (unscalable actions, market/churn check) rather than doom.",
      "assertions": [
        "3% is located correctly within the YC benchmark tiers",
        "The framework's own interpretation (<5% = unscalable things not happening) is used",
        "The response avoids treating the benchmark as a shutdown decision",
        "Constructive next diagnostics are offered"
      ]
    }
  ]
}

# Growth Compass — Paul Graham's "Startup = Growth" Framework

## Origin

The essay ["Startup = Growth"](https://paulgraham.com/growth.html) was published in September 2012. It is arguably the most important single essay Paul Graham wrote about Y Combinator's philosophy — the framework from which everything else follows.

## The Central Thesis

> "A startup is a company designed to grow fast. Being newly founded does not in itself make a company a startup. Nor is it necessary for a startup to work on technology, or take venture funding, or have some sort of 'exit.' The only essential thing is growth. Everything else we associate with startups follows from growth."

This reframing was radical: a restaurant, a barbershop, a consulting firm are not startups — even if they're newly founded. They're not designed for rapid growth. A startup is distinguished not by its industry, age, or funding status, but by its *growth trajectory*.

## Key Concepts

### Growth Rate is the Only Metric That Matters

> "If there's one number every founder should always know, it's the company's growth rate. That's the measure of a startup. If you don't know that number, you don't even know if you're doing well or badly."

YC measures growth **per week**, not per month. The reasoning:

1. The batch is only 11 weeks — monthly data gives you only 2-3 data points
2. Weekly measurement forces faster iteration
3. The feedback loop is tighter — you know within days whether something worked

### The YC Growth Benchmarks

| Weekly Growth | Assessment | Implication |
|--------------|------------|-------------|
| 5-7% | Good | Solid trajectory |
| 10% | Exceptional | Breakout company potential |
| 1% | Concerning | Haven't figured out what you're doing |

Graham's key observation: small variations in growth rate produce **qualitatively different outcomes**.

> "A company that grows at 1% a week will grow 1.7x a year, whereas a company that grows at 5% a week will grow 12.6x. A company making $1000 a month (a typical number early in YC) and growing at 1% a week will 4 years later be making $7900 a month, which is less than a good programmer makes in salary in Silicon Valley. A startup that grows at 5% a week will in 4 years be making $25 million a month."

### Growth as a Compass

The most operational insight: treat growth rate as the single decision metric.

> "Focusing on hitting a growth rate reduces the otherwise bewilderingly multifarious problem of starting a startup to a single problem. You can use that target growth rate to make all your decisions for you; anything that gets you the growth you need is ipso facto right."

This turns startup building into an **optimization problem**. Programmers will recognize this pattern — it's the same satisfying narrow focus as optimizing code.

### Growth Rate as Idea Discovery

Perhaps the most surprising claim: optimizing for growth can *discover the idea itself*.

> "You can use the need for growth as a form of evolutionary pressure. If you start out with some initial plan and modify it as necessary to keep hitting, say, 10% weekly growth, you may end up with a quite different company than you meant to start."

### The Three Phases of Startup Growth

```
Phase 1: Slow/no growth — figuring out what to do
Phase 2: Rapid growth (the ascent) — product-market fit, scaling
Phase 3: Slowdown — market saturation, internal limits
```

The phase that defines the startup is Phase 2. Its slope (growth rate) and length determine how big the company will become.

## From the Essay (Key Quotes)

### On user acquisition

> "You should take extraordinary measures not just to acquire users, but also to make them happy."

### On compound growth

> "If you're really getting a constant number of new customers every month, you're in trouble, because that means your growth rate is decreasing."

### On the value proposition

> "For startups, growth is a constraint much like truth. When Richard Feynman said that the imagination of nature was greater than the imagination of man, he meant that if you just keep following the truth you'll discover cooler things than you could ever have made up."

## How YC Operationalizes This

### During the Batch

1. **Week 1**: Founders establish a baseline metric and set a target growth rate
2. **Weekly check-ins**: Partners ask "what's your growth rate?" — not "how are you feeling?"
3. **Growth as the only goal**: If you hit your number, you had a good week. Nothing else matters.
4. **Office hours focus**: Conversations center on what will move the growth needle

### As a Founder's Habit

The weekly routine Graham recommends:

- **Monday**: Set this week's growth target
- **Daily**: Evaluate every decision against "does this serve the growth target?"
- **Friday**: Measure actual growth. If you hit it, celebrate. If you missed, be alarmed.
- **Weekend**: Let the miss marinate. Come back Monday ready to adjust.

## Historical Impact

"Startup = Growth" crystallized a philosophy that was already implicit in YC's operations but had never been explicitly articulated. Before this essay, the startup world was full of fuzzy advice about passion, vision, and disruption. After it, the conversation shifted to concrete metrics and growth loops.

This essay is directly responsible for:
- The obsession with growth rates in modern venture capital
- The "growth at all costs" philosophy (and its subsequent critique)
- The emphasis on rapid iteration and short feedback loops
- The psychological framing of startup building as an optimization problem

## Limitations and Critiques

1. **Growth isn't everything** — A company growing 10% weekly can still be a bad business (high churn, negative unit economics, toxic culture)
2. **The metric chosen matters** — Users ≠ revenue. Signups ≠ active users. Growth in the wrong metric is misleading.
3. **Context dependency** — Hardware, biotech, and deep tech startups cannot iterate weekly. The framework works best for software.
4. **The local maxima problem** — Hyper-optimizing for growth can lead startups up the wrong hill, building for metrics that don't translate to sustainable value.

## Companion Readings

- ["Do Things That Don't Scale" (2013)](https://paulgraham.com/ds.html) — The tactical playbook for generating the initial growth
- ["Default Alive or Default Dead?" (2014)](https://paulgraham.com/default.html) — What happens after you have growth
- ["Ramen Profitability" (2009)](https://paulgraham.com/ramenprof.html) — The extreme efficiency strategy
- Alex Schultz's Startup School lecture on growth — YC's most-watched talk

#!/usr/bin/env python3
"""
Weekly Growth Compass

Paul Graham's "Startup = Growth" framework as a CLI tool. Computes weekly
growth rates, benchmarks against YC tiers, projects compound growth over time,
and evaluates whether decisions serve the target growth rate.

Usage:
  python growth-compass.py --current-value 1200 --previous-value 1000 --period weekly
  python growth-compass.py --series "1000,1050,1100,1200,1350" --period weekly
  python growth-compass.py --current-value 35000 --previous-value 32000 --period monthly --metric-name "MRR" --target-revenue 100000
  python growth-compass.py --current-value 1200 --previous-value 1000 --period weekly --json
"""

import argparse
import json
import math
import sys
from typing import List, Optional, Tuple


# ---------------------------------------------------------------------------
# YC Growth Benchmarks
# ---------------------------------------------------------------------------

# Paul Graham's empirical benchmarks from "Startup = Growth" (2012)
# and YC's internal coaching targets during batch programs.

YC_BENCHMARKS = [
    {"min_pct": 10.0, "label": "Outstanding", "color": "🟣",
     "assessment": "Breakout trajectory — extremely rare. This is the Stripe/Coinbase zone."},
    {"min_pct": 7.0, "label": "Very Good", "color": "🟢",
     "assessment": "Exceptional progress. Top quartile of YC companies."},
    {"min_pct": 5.0, "label": "Good", "color": "🟢",
     "assessment": "Solid trajectory. YC's target zone — keep pushing."},
    {"min_pct": 2.0, "label": "Below Average", "color": "🟡",
     "assessment": "Below YC average. Need significant acceleration — likely haven't found product-market fit."},
    {"min_pct": 0.0, "label": "Concerning", "color": "🔴",
     "assessment": "Very low growth. Haven't figured out what you're doing."},
]

# Compound multipliers at various rates
COMPOUND_MULTIPLIERS = {
    1: {"weekly": 1.01, "yearly": 1.68, "label": "Concerning"},
    2: {"weekly": 1.02, "yearly": 2.81, "label": "Below Average"},
    5: {"weekly": 1.05, "yearly": 12.64, "label": "Good"},
    7: {"weekly": 1.07, "yearly": 33.73, "label": "Very Good"},
    10: {"weekly": 1.10, "yearly": 142.04, "label": "Outstanding"},
}


def classify_growth(rate_pct: float) -> dict:
    """Classify a growth rate against YC benchmarks."""
    for bench in YC_BENCHMARKS:
        if rate_pct >= bench["min_pct"]:
            return bench
    return YC_BENCHMARKS[-1]


def period_normalizer(period: str) -> Tuple[str, int]:
    """Return (period_name, periods_per_year) for the given period."""
    period = period.lower()
    mapping = {
        "weekly": ("weekly", 52),
        "monthly": ("monthly", 12),
        "quarterly": ("quarterly", 4),
    }
    if period not in mapping:
        raise ValueError(f"Unknown period: {period}. Must be one of: weekly, monthly, quarterly")
    return mapping[period]


def weekly_equivalent(rate_pct: float, from_period: str) -> float:
    """Convert a growth rate from any period to its weekly equivalent."""
    if from_period == "weekly":
        return rate_pct
    periods_per_year = {"weekly": 52, "monthly": 12, "quarterly": 4}
    n = periods_per_year[from_period]
    # Convert: (1 + r_monthly)^(1/4.33) - 1  ≈ weekly rate
    weekly_rate = (1 + rate_pct / 100) ** (1 / (n / 52)) - 1
    return weekly_rate * 100


# ---------------------------------------------------------------------------
# Core calculations
# ---------------------------------------------------------------------------


def compute_growth_rate(current: float, previous: float) -> float:
    """Compute growth rate as a percentage."""
    if previous <= 0:
        return 0.0
    return ((current - previous) / previous) * 100


def compute_series_rates(
    values: List[float],
) -> Tuple[List[float], float, float, float]:
    """Compute growth rates from a time series of values.

    Returns
    -------
    (period_rates, mean_rate, median_rate, cwgr)
    where cwgr is the compound weekly growth rate fitted from first to last value.
    """
    if len(values) < 2:
        return [], 0.0, 0.0, 0.0

    rates = []
    for i in range(1, len(values)):
        if values[i - 1] > 0:
            rates.append(((values[i] - values[i - 1]) / values[i - 1]) * 100)

    if not rates:
        return [], 0.0, 0.0, 0.0

    mean_rate = sum(rates) / len(rates)
    sorted_rates = sorted(rates)
    n = len(sorted_rates)
    if n % 2 == 0:
        median_rate = (sorted_rates[n // 2 - 1] + sorted_rates[n // 2]) / 2
    else:
        median_rate = sorted_rates[n // 2]

    # Compound rate from first to last value
    if len(values) >= 2 and values[0] > 0:
        total_growth = values[-1] / values[0]
        cwgr = (total_growth ** (1 / (len(values) - 1)) - 1) * 100
    else:
        cwgr = 0.0

    return rates, mean_rate, median_rate, cwgr


def project_value(
    current: float,
    growth_rate_pct: float,
    periods: int,
) -> float:
    """Project future value given a constant growth rate."""
    return current * ((1 + growth_rate_pct / 100) ** periods)


def doubling_time(growth_rate_pct: float) -> float:
    """Compute the number of periods to double at the given growth rate."""
    if growth_rate_pct <= 0:
        return float("inf")
    return math.log(2) / math.log(1 + growth_rate_pct / 100)


def time_to_target(
    current: float,
    target: float,
    growth_rate_pct: float,
) -> Optional[float]:
    """Compute periods needed to reach target at given growth rate."""
    if current >= target:
        return 0.0
    if growth_rate_pct <= 0:
        return None
    return math.log(target / current) / math.log(1 + growth_rate_pct / 100)


# ---------------------------------------------------------------------------
# Analysis
# ---------------------------------------------------------------------------


def analyze_growth(
    current_value: float,
    previous_value: Optional[float] = None,
    series: Optional[List[float]] = None,
    period: str = "weekly",
    project_periods: int = 52,
    target_value: Optional[float] = None,
    metric_name: str = "users/revenue",
) -> dict:
    """Full growth analysis.

    Parameters
    ----------
    current_value : Current period's metric value
    previous_value : Previous period's metric value (optional if series provided)
    series : Full time series of values (optional, overrides previous_value)
    period : 'weekly', 'monthly', or 'quarterly'
    project_periods : Number of periods to project forward (default: 52)
    target_value : Optional target metric to compute time-to-target
    metric_name : Human-readable name for the metric

    Returns
    -------
    dict with all computed fields
    """
    period_name, periods_per_year = period_normalizer(period)

    # Compute rate
    if series and len(series) >= 2:
        rates, mean_rate, median_rate, cwgr = compute_series_rates(series)
        growth_rate = mean_rate if mean_rate != 0 else cwgr
        series_info = {
            "num_data_points": len(series),
            "rates": [round(r, 2) for r in rates],
            "mean_rate": round(mean_rate, 2),
            "median_rate": round(median_rate, 2),
            "cwgr": round(cwgr, 2),
            "first_value": series[0],
            "last_value": series[-1],
        }
    elif previous_value is not None:
        growth_rate = compute_growth_rate(current_value, previous_value)
        series_info = {
            "num_data_points": 2,
            "rate": round(growth_rate, 2),
        }
    else:
        return {"error": "Either --previous-value or --series is required."}

    # Classify
    benchmark = classify_growth(growth_rate)
    weekly_rate = weekly_equivalent(growth_rate, period)
    weekly_benchmark = classify_growth(weekly_rate)

    # Projections
    projected_1yr = project_value(current_value, growth_rate, periods_per_year)
    projected_2yr = project_value(current_value, growth_rate, periods_per_year * 2)
    projected_N = project_value(current_value, growth_rate, project_periods)

    # Doubling and target
    double_p = doubling_time(growth_rate)
    time_to_t = (time_to_target(current_value, target_value, growth_rate)
                 if target_value is not None else None)

    # Growth rate tier table (what other rates would do)
    tier_projections = {}
    for rate_pct in [1, 2, 5, 7, 10]:
        tier_projections[str(rate_pct)] = {
            "label": COMPOUND_MULTIPLIERS.get(rate_pct, {}).get("label", ""),
            "yearly_multiple": round((1 + rate_pct / 100) ** periods_per_year, 2),
            "projected_1yr": round(project_value(current_value, rate_pct, periods_per_year), 2),
            "doubling_periods": round(doubling_time(rate_pct), 1),
        }

    # Assessment text
    if growth_rate >= 5:
        assessment_text = (
            f"At {growth_rate:.1f}% {period_name} growth, you're in YC's good-to-outstanding range. "
            f"Keep pushing — compound growth at this rate transforms the business."
        )
    elif growth_rate >= 2:
        assessment_text = (
            f"At {growth_rate:.1f}% {period_name} growth, you're below YC's target zone. "
            f"Paul Graham's advice: start doing things that don't scale. Recruit users manually, "
            f"delight early customers, measure what works, and compound from there."
        )
    else:
        assessment_text = (
            f"At {growth_rate:.1f}% {period_name} growth, this is concerning. "
            f"You haven't yet figured out what you're doing. Focus on finding something "
            f"that a small number of users genuinely love — then grow from there."
        )

    result = {
        "inputs": {
            "current_value": current_value,
            "previous_value": previous_value,
            "metric_name": metric_name,
            "period": period_name,
            "project_periods": project_periods,
            "target_value": target_value,
        },
        "series_info": series_info,
        "growth_rate": {
            "period_rate_pct": round(growth_rate, 2),
            "weekly_equivalent_pct": round(weekly_rate, 2),
            "period_name": period_name,
        },
        "benchmark": {
            "label": benchmark["label"],
            "icon": benchmark["color"],
            "assessment": benchmark["assessment"],
            "weekly_benchmark_label": weekly_benchmark["label"],
        },
        "projections": {
            f"projected_{project_periods}_periods": round(projected_N, 2),
            "projected_1_year": round(projected_1yr, 2),
            "projected_2_years": round(projected_2yr, 2),
            "doubling_time_periods": round(double_p, 1),
            "time_to_target_periods": round(time_to_t, 1) if time_to_t is not None else None,
            "target_value": target_value,
        },
        "tier_comparison": tier_projections,
        "assessment_text": assessment_text,
    }

    return result


# ---------------------------------------------------------------------------
# Output formatting
# ---------------------------------------------------------------------------


def format_output(result: dict) -> str:
    """Format the analysis as a human-readable report."""
    if "error" in result:
        return f"Error: {result['error']}"

    lines = []
    inputs = result["inputs"]
    rate = result["growth_rate"]
    bench = result["benchmark"]
    proj = result["projections"]
    series = result["series_info"]

    # Header
    lines.append("=" * 60)
    lines.append(f"  WEEKLY GROWTH COMPASS — {bench['icon']} {bench['label']}")
    lines.append("=" * 60)
    lines.append("")

    # Inputs
    lines.append("── Inputs ──────────────────────────────────────────────")
    lines.append(f"  Metric:         {inputs['metric_name']}")
    lines.append(f"  Current value:  {inputs['current_value']:>10,.0f}")
    if inputs.get("previous_value"):
        lines.append(f"  Previous value: {inputs['previous_value']:>10,.0f}")
    lines.append(f"  Period:         {inputs['period']}")
    lines.append(f"  Data points:    {series.get('num_data_points', 2)}")
    lines.append("")

    # Growth rate
    lines.append("── Growth Rate ──────────────────────────────────────────")
    lines.append(f"  Period growth:  {rate['period_rate_pct']:>7.2f}% ({rate['period_name']})")
    lines.append(f"  Weekly equiv:   {rate['weekly_equivalent_pct']:>7.2f}%")
    lines.append(f"  YC Benchmark:   {bench['icon']} {bench['label']}")
    lines.append("")

    if series.get("rates"):
        rates = series["rates"]
        lines.append(f"  Period-over-period rates:")
        for i, r in enumerate(rates):
            arrows = "↑" if r > 0 else "↓" if r < 0 else "→"
            lines.append(f"    Period {i+1}-{i+2}: {r:>6.2f}% {arrows}")
        lines.append(f"  Mean rate:      {series['mean_rate']:>7.2f}%")
        lines.append(f"  Median rate:    {series['median_rate']:>7.2f}%")
        lines.append(f"  CWGR:           {series['cwgr']:>7.2f}% (compound from first to last)")
        lines.append("")

    # Assessment
    lines.append("── Assessment ───────────────────────────────────────────")
    lines.append(f"  {result['assessment_text']}")
    lines.append("")

    # Projections
    lines.append("── Projections ─────────────────────────────────────────")
    lines.append(f"  Doubling time:     {proj['doubling_time_periods']:>7.1f} {rate['period_name']} periods")
    lines.append(f"  Projected 1 year:  {proj['projected_1_year']:>10,.0f}")
    lines.append(f"  Projected 2 years: {proj['projected_2_years']:>10,.0f}")
    if proj.get("time_to_target_periods") is not None and proj.get("target_value"):
        lines.append(f"  Time to target:    {proj['time_to_target_periods']:>7.1f} {rate['period_name']} periods")
        lines.append(f"  Target value:      {proj['target_value']:>10,.0f}")
    lines.append("")

    # Tier comparison
    lines.append("── Growth Rate Comparison ──────────────────────────────")
    lines.append(f"  {'Rate':>6} {'Label':>18} {'1-Year Multiple':>18} {'1-Year Value':>16} {'Double In':>12}")
    lines.append(f"  {'-'*6} {'-'*18} {'-'*18} {'-'*16} {'-'*12}")
    for rate_pct_str, tier in result["tier_comparison"].items():
        rate_pct = int(rate_pct_str)
        marker = "◀" if rate_pct == round(rate["period_rate_pct"]) else ""
        lines.append(
            f"  {rate_pct:>5}% {tier['label']:>18} "
            f"{tier['yearly_multiple']:>17.1f}x "
            f"{tier['projected_1yr']:>14,.0f} "
            f"{tier['doubling_periods']:>7.1f}p  {marker}"
        )
    lines.append("")

    # Compass question
    lines.append("── The Compass Question ────────────────────────────────")
    lines.append(f"  Your target growth rate: {rate['period_rate_pct']:.1f}% {rate['period_name']}")
    lines.append(f"  For every decision this week, ask:")
    lines.append(f"  \"Does this serve our {rate['period_rate_pct']:.1f}% {rate['period_name']} growth target?\"")
    lines.append(f"  If yes → do it. If no → defer it.")
    lines.append("")
    lines.append(f"  At end of week, measure actual growth against target.")
    lines.append(f"  If you missed, something else matters more than what you did.")

    lines.append("")
    lines.append("=" * 60)
    lines.append("  Paul Graham, \"Startup = Growth\" (September 2012)")
    lines.append("  paulgraham.com/growth.html")
    lines.append("=" * 60)

    return "\n".join(lines)


# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------


def main():
    parser = argparse.ArgumentParser(
        description="Weekly Growth Compass — YC's growth rate framework",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  python growth-compass.py --current-value 1200 --previous-value 1000 --period weekly
  python growth-compass.py --series "1000,1050,1100,1200,1350" --period weekly
  python growth-compass.py --current-value 35000 --previous-value 32000 --period monthly --metric-name "MRR" --target-revenue 100000
  python growth-compass.py --current-value 1200 --previous-value 1000 --period weekly --json
        """,
    )
    parser.add_argument("--current-value", type=float, help="Current period metric value")
    parser.add_argument("--previous-value", type=float, help="Previous period metric value")
    parser.add_argument("--series", type=str, help="Comma-separated time series (overrides --current/--previous)")
    parser.add_argument("--period", type=str, default="weekly", choices=["weekly", "monthly", "quarterly"],
                        help="Period type (default: weekly)")
    parser.add_argument("--project-periods", type=int, default=52,
                        help="Periods to project forward (default: 52)")
    parser.add_argument("--target-value", type=float, help="Target metric value to compute time-to-target")
    parser.add_argument("--metric-name", type=str, default="users/revenue",
                        help="Human-readable metric name (default: 'users/revenue')")
    parser.add_argument("--json", action="store_true", help="Output as JSON")
    parser.add_argument("--dry-run", action="store_true", help="Validate inputs and show what would be computed")

    args = parser.parse_args()

    # Parse series if provided
    series = None
    if args.series:
        try:
            series = [float(x.strip()) for x in args.series.split(",")]
        except ValueError:
            parser.error("--series must be comma-separated numbers")
        if len(series) < 2:
            parser.error("--series must have at least 2 values")

    # Validate
    if not series and args.current_value is None:
        parser.error("Either --current-value (with --previous-value) or --series is required")
    if not series and args.previous_value is None:
        parser.error("--previous-value is required when using --current-value")
    if args.current_value is not None and args.current_value < 0:
        parser.error("--current-value must be >= 0")
    if args.previous_value is not None and args.previous_value < 0:
        parser.error("--previous-value must be >= 0")
    if args.target_value is not None and args.target_value < 0:
        parser.error("--target-value must be >= 0")
    if args.project_periods < 1:
        parser.error("--project-periods must be >= 1")

    if args.dry_run:
        if series:
            print(json.dumps({
                "status": "valid",
                "data_points": len(series),
                "first_value": series[0],
                "last_value": series[-1],
                "period": args.period,
            }, indent=2))
        else:
            print(json.dumps({
                "status": "valid",
                "current_value": args.current_value,
                "previous_value": args.previous_value,
                "period": args.period,
            }, indent=2))
        return

    current_val: float = series[-1] if series else (args.current_value or 0.0)
    result = analyze_growth(
        current_value=current_val,
        previous_value=args.previous_value,
        series=series,
        period=args.period,
        project_periods=args.project_periods,
        target_value=args.target_value,
        metric_name=args.metric_name,
    )

    if args.json:
        print(json.dumps(result, indent=2))
    else:
        print(format_output(result))


if __name__ == "__main__":
    main()