1// Detects per-day billing spikes by inspecting usage.breakdown.data[] (daily granularity).2// Fires when any single day's total bill > 2× the window mean, OR a single SKU's day value > 3× its window mean.3// Emits one candidate per spiking SKU (or 'total' when the spike is broad).4// Degrades gracefully when daily data is unavailable — common path because the skill prefers --group-by project, which omits daily breakdown.5export const metadata = {6 id: 'usage_spike_triage',7 threshold: 'any-day total > 2x mean OR any-day SKU > 3x SKU mean',8 billingDimension: 'mixed',9 scope: 'account',10 sourceCitation:
12 'A single day in the billing window deviates sharply from the window baseline. Triage branches: bot or AI crawler spike, viral moment, pricing-model migration (legacy SKU → new), code regression. Without daily-granularity data, this gate stays dormant.',
13};
14
15const TOTAL_MULTIPLIER = 2;
16const SKU_MULTIPLIER = 3;
17const MIN_BILLED_FLOOR = 5; // skip spikes whose absolute value is too small to matter
18
19export function gate(signals) {
20 const days = signals?.usage?.breakdown?.data;
21 if (!Array.isArray(days) || days.length < 3) return [];
22
23 const dayTotals = days.map(dayTotal);
24 const mean = dayTotals.reduce((a, b) => a + b, 0) / dayTotals.length;
60 reason: 'total billed cost on one day exceeds 2× the window mean',
61 question: 'Which workload generated the day-over-day spike — bot or AI-crawler traffic on a cacheable route, a viral event, a pricing-model migration, or a code regression?',
62 evidence: {
63 metric: 'usage.breakdown.data.total',
64 spikeDay: peak.idx,
65 spikeBilled: peak.value,
66 windowMean: mean,
67 multiplier: peak.value / mean,
68 skuName: 'total',
69 },
70 });
71 }
72 // Up to 3 SKU-specific candidates; the rest fold into 'multiple SKUs spiking' framing.
82 reason: `${spike.name} on one day exceeds 3× its window mean`,
83 question: `${spike.name} spiked ${spike.multiplier.toFixed(1)}× on day ${spike.dayIndex}. Which event (bot traffic, viral content, deploy regression, integration sync) drove it, and is the spiking SKU one the skill already covers?`,