auction-first-price-shading

What this skill does

# Auction First-Price Shading

## Table of Contents
- [Example](#example)
- [Workflow](#workflow)
- [Common Patterns](#common-patterns)
- [Guardrails](#guardrails)
- [Quick Reference](#quick-reference)

## Example

**Scenario**: Domain-neutral sealed-bid auction. A bidder must submit a blind bid for an item whose private value to them is 28 units of budget currency. Six other bidders are expected to compete. Values across bidders look roughly uniform. The bidder is mildly risk-averse (0.2) and has 89 units of budget remaining.

**Inputs**:
- `true_value = 28`
- `n_bidders_estimate = 6`
- `value_distribution = "uniform"`
- `risk_aversion = 0.2`
- `budget_remaining = 89`

**Core computation**:
```
shade_fraction_base = (N - 1) / N = 5 / 6 = 0.833
shaded_bid_base     = true_value x shade_fraction_base = 28 x 0.833 = 23.33
```

**Risk-aversion adjustment** (raise the bid toward true value to boost win probability):
```
shade_fraction' = shade + risk_aversion x (1 - shade) x 0.4
                = 0.833 + 0.2 x (1 - 0.833) x 0.4
                = 0.833 + 0.0133
                = 0.847
shaded_bid'     = 28 x 0.847 = 23.72
```

**Budget + safety cap**:
```
cap = min(shaded_bid', 0.9 x true_value, budget_remaining)
    = min(23.72, 25.2, 89)
    = 23.72  -> round to 24
```

**Output**:
- `shaded_bid = 24`
- `shade_fraction = 0.847`
- `rationale = "Uniform-values equilibrium shades to (N-1)/N = 0.833 at N=6. Mild risk aversion (0.2) nudges bid up to 0.847 of true value to raise win probability. Final bid capped below 0.9x true_value and well under budget. Expected to win against 5 rivals drawing values from a comparable uniform distribution."`
- `assumptions_flagged = ["uniform private-value distribution", "N=6 is an estimate, not observed", "risk_aversion=0.2 is a modeling choice"]`

## Workflow

Copy this checklist and track progress:

```
Auction Shading Progress:
- [ ] Step 1: Validate inputs (true_value > 0, 1 <= N <= 12, distribution known)
- [ ] Step 2: Compute base shade from (N-1)/N
- [ ] Step 3: Apply distribution adjustment (uniform / log-normal / empirical)
- [ ] Step 4: Apply risk-aversion adjustment
- [ ] Step 5: Apply budget and safety caps
- [ ] Step 6: Emit shaded_bid, shade_fraction, rationale, assumptions_flagged
```

**Step 1: Validate inputs**

Reject or flag bad inputs before computing. See [resources/template.md](resources/template.md#input-contract) for the full input contract.

- [ ] `true_value` is a non-negative number
- [ ] `n_bidders_estimate` is an integer, clamp to `[1, 12]`
- [ ] `value_distribution` is one of `"uniform"`, `"log-normal"`, `"empirical"`
- [ ] `risk_aversion` is in `[0, 1]` (default 0 if missing)
- [ ] `budget_remaining` is a non-negative number (if missing, treat as effectively infinite and flag)

**Step 2: Compute base shade from `(N-1)/N`**

For risk-neutral bidders drawing values from a uniform distribution on `[0, v_max]`, the symmetric Bayes-Nash equilibrium bidding strategy is `b(v) = v x (N-1)/N`. See [resources/methodology.md](resources/methodology.md#uniform-value-equilibrium-derivation) for the derivation.

- [ ] `shade_fraction = (N - 1) / N`
- [ ] Edge case `N = 1`: shade = 0, bid the minimum increment (monopsonist — no competition)
- [ ] `shaded_bid = true_value x shade_fraction`

**Step 3: Apply distribution adjustment**

Uniform values give the clean `(N-1)/N` rule. Real-world value distributions are often clustered (log-normal) or empirically lumpy. See [resources/methodology.md](resources/methodology.md#distribution-adjustment).

- [ ] If `"uniform"`: no adjustment; shade = `(N-1)/N`.
- [ ] If `"log-normal"`: values cluster around a mode with a long right tail. Shift shade toward `1 - 1/(N x spread)` where `spread >= 1` captures the coefficient of variation. Default `spread = 1.5` shifts shade up (bid closer to value) because rivals' values are less likely to be extreme.
- [ ] If `"empirical"`: distribution learned from prior auctions; pass through a shade-lookup table if available, otherwise fall back to the log-normal formula with spread inferred from observed history.

**Step 4: Apply risk-aversion adjustment**

Risk-averse bidders accept a smaller expected surplus in exchange for a higher win probability. They bid closer to true value (shade less). See [resources/methodology.md](resources/methodology.md#risk-aversion-adjustment).

- [ ] `shade_fraction' = shade + risk_aversion x (1 - shade) x 0.4`
- [ ] `risk_aversion = 0`: no change.
- [ ] `risk_aversion = 1`: shade moves 40 percent of the way from its base value to 1 (i.e., toward bidding true value).
- [ ] The 0.4 scaling factor caps the adjustment; it never closes the full gap because a fully-closed gap gives zero surplus.

**Step 5: Apply budget and safety caps**

The final bid is clamped three ways:

- [ ] `cap_value = 0.9 x true_value` — never pay more than 90 percent of what the item is worth; this preserves at least 10 percent expected surplus.
- [ ] `cap_budget = budget_remaining` — never bid more than available budget.
- [ ] `shaded_bid = min(raw_shaded_bid, cap_value, cap_budget)`.
- [ ] Flag in `assumptions_flagged` whenever a cap binds so downstream consumers know which constraint is active.

**Step 6: Emit outputs**

Return the four-field output:

- [ ] `shaded_bid` (number, rounded to the precision the caller expects — integers for most budget systems)
- [ ] `shade_fraction` (0-1, the effective shade actually used)
- [ ] `rationale` (one or two sentences explaining which rule applied and why)
- [ ] `assumptions_flagged` (string array — every assumption the downstream consumer may need to revisit)

Validate using [resources/evaluators/rubric_auction_first_price_shading.json](resources/evaluators/rubric_auction_first_price_shading.json). Minimum standard: weighted score of 3.5 or above.

## Common Patterns

**Pattern 1: Generic sealed-bid auction (uniform values, risk-neutral)**
- **When it applies**: Values are drawn from roughly the same distribution for all bidders, no unique information, no risk aversion.
- **Shade**: `(N-1)/N`. At N=2 shade to 50 percent. At N=6 shade to 83 percent. At N=8 shade to 87.5 percent.
- **Downstream examples**: Fantasy sports waiver auctions (FAAB) for private-value targets, sealed procurement bids, silent-auction pledges.

**Pattern 2: Clustered values (log-normal or empirical)**
- **When it applies**: Most bidders' valuations cluster around a shared estimate (common-value component), with a thin tail of outliers. Typical of well-known targets where public information narrows the spread of valuations.
- **Shade**: move toward `1 - 1/(N x spread)`. Higher spread means more disagreement and permits deeper shading. Low spread (tight cluster) means less room to shade — bidders must be near consensus to win.
- **Downstream examples**: FAAB bids on headline call-ups, prediction-market limit orders on well-priced contracts, M&A sealed-bid rounds with shared public data.

**Pattern 3: Risk-averse bidder**
- **When it applies**: The bidder values winning more than maximizing expected surplus — for example, a fantasy manager who must fill a lineup slot this week, or a procurement team that must secure supply.
- **Shade adjustment**: `shade' = shade + risk_aversion x (1 - shade) x 0.4`. Pushes the bid closer to true value.
- **Watch for**: never lets shade reach 1 (never bids true value), because that yields zero expected surplus. The cap at `0.9 x true_value` enforces this hard.

**Pattern 4: Budget-constrained bidder (corner solution)**
- **When it applies**: The unconstrained shaded bid exceeds `budget_remaining`. The bidder must either accept a lower win probability or forgo the auction.
- **Shade adjustment**: output equals `budget_remaining`, effective shade = `budget_remaining / true_value`. Flag that the budget constraint binds so downstream logic can decide whether to skip the auction or accept the lower probability.
- **Watch for**: If `budget_remaining < (N-1)/N x true_value`, the bidder is un