---
name: kpi-oracle
description: Predict future KPI values from hourly operational snapshots using pure JavaScript linear regression. Forecasts milestones, detects patterns, alerts on resource depletion.
allowed-tools: Bash(node *)
---

# Predictive KPI Oracle

Zero dependencies beyond Node.js. Reads hourly snapshots, produces forecasts with R-squared confidence, milestone dates, pattern detection, and depletion alerts.

## Prerequisites
- Node.js 18+
- JSON-lines file with hourly snapshots (this skill generates sample data)

## Step 1: Generate sample chronicle data
```bash
node << 'GENERATE'
const fs = require('fs');
const lines = [];
const now = Date.now();
for (let h = 0; h < 168; h++) {
  const ts = new Date(now - (168-h)*3600000).toISOString();
  const day = Math.floor(h/24);
  const isWeekend = new Date(ts).getDay() % 6 === 0;
  const tools = 7000 + Math.floor(day*27 + Math.random()*5);
  const enriched = Math.floor(500 + day*8 + Math.random()*3);
  const contentRate = isWeekend ? 4 : 12;
  const published = Math.floor(80 + day*contentRate + Math.random()*3);
  const queueDepth = Math.max(5, 60 - Math.floor(day*8 + Math.random()*5));
  const health = Math.min(100, 38 + day*1.2 + Math.random()*2);
  lines.push(JSON.stringify({ts, tools:{total:tools, enriched}, content:{published, queued:queueDepth}, health: Math.round(health*10)/10}));
}
fs.writeFileSync('/tmp/chronicle.jsonl', lines.join('\n'));
console.log('Generated ' + lines.length + ' hourly snapshots (7 days)');
GENERATE
```
Expected output: 168 hourly snapshots generated

## Step 2: Run the oracle forecast
```bash
node << 'ORACLE'
const fs = require('fs');
const lines = fs.readFileSync('/tmp/chronicle.jsonl','utf8').trim().split('\n');
const snapshots = lines.map(l => JSON.parse(l));
console.log('Loaded ' + snapshots.length + ' snapshots');

function linreg(points) {
  const n = points.length;
  if (n < 2) return null;
  let sX=0,sY=0,sXY=0,sXX=0;
  for (const p of points) { sX+=p.x; sY+=p.y; sXY+=p.x*p.y; sXX+=p.x*p.x; }
  const slope = (n*sXY - sX*sY)/(n*sXX - sX*sX);
  const intercept = (sY - slope*sX)/n;
  const yMean = sY/n;
  let ssRes=0,ssTot=0;
  for (const p of points) { const pred=slope*p.x+intercept; ssRes+=(p.y-pred)**2; ssTot+=(p.y-yMean)**2; }
  const r2 = ssTot===0 ? 0 : 1 - ssRes/ssTot;
  return {slope, intercept, r2, lastY: points[n-1].y};
}

const daily = {};
for (const s of snapshots) { const day=s.ts.split('T')[0]; if(!daily[day]) daily[day]=[]; daily[day].push(s); }
const days = Object.keys(daily).sort();

function dailyMetric(extract) {
  return days.map((d,i) => {
    const vals = daily[d].map(extract).filter(v => v!=null);
    return {x:i, y: vals.length ? vals[vals.length-1] : 0};
  });
}

const metrics = {
  tools_total: dailyMetric(s => s.tools?.total),
  enriched: dailyMetric(s => s.tools?.enriched),
  content_published: dailyMetric(s => s.content?.published),
  queue_depth: dailyMetric(s => s.content?.queued),
  health: dailyMetric(s => s.health),
};

console.log('\n=== FORECASTS ===');
const MILESTONES = {tools_total:[8000,10000,15000], enriched:[1000,2000,5000], content_published:[200,500,1000], health:[50,60,80,90]};

for (const [name, points] of Object.entries(metrics)) {
  const reg = linreg(points);
  if (!reg) continue;
  const conf = reg.r2>=0.8?'HIGH':reg.r2>=0.5?'MEDIUM':'LOW';
  const p7=Math.round(reg.lastY+reg.slope*7), p30=Math.round(reg.lastY+reg.slope*30), p90=Math.round(reg.lastY+reg.slope*90);
  console.log(name+': current='+reg.lastY+' rate='+reg.slope.toFixed(2)+'/day R²='+reg.r2.toFixed(3)+' ('+conf+')');
  console.log('  7d='+p7+' | 30d='+p30+' | 90d='+p90);
  for (const target of (MILESTONES[name]||[])) {
    if (reg.slope<=0) { console.log('  → '+target+': never at current rate'); continue; }
    const days=Math.round((target-reg.lastY)/reg.slope);
    if (days<0) { console.log('  → '+target+': already reached'); continue; }
    const date=new Date(Date.now()+days*86400000).toISOString().split('T')[0];
    console.log('  → '+target+': '+date+' ('+days+' days)');
  }
}

// Weekend dip detection
const byDow = {};
for (const s of snapshots) { const dow=new Date(s.ts).getDay(); if(!byDow[dow]) byDow[dow]=[]; byDow[dow].push(s.content?.published||0); }
const wdVals=[1,2,3,4,5].flatMap(d=>byDow[d]||[]), weVals=[0,6].flatMap(d=>byDow[d]||[]);
if (wdVals.length && weVals.length) {
  const wdAvg=wdVals.reduce((a,b)=>a+b,0)/wdVals.length, weAvg=weVals.reduce((a,b)=>a+b,0)/weVals.length;
  const ratio=wdAvg>0?weAvg/wdAvg:1;
  console.log('\n=== PATTERNS ===');
  if (ratio<0.5) console.log('Weekend dip: content drops '+Math.round((1-ratio)*100)+'% on Sat-Sun');
  else console.log('No significant weekend dip (ratio: '+ratio.toFixed(2)+')');
}

// Depletion alert
const qReg = linreg(metrics.queue_depth);
console.log('\n=== DEPLETION ALERTS ===');
if (qReg && qReg.slope<0) {
  const daysLeft = -qReg.lastY/qReg.slope;
  console.log('Discovery queue: '+qReg.lastY+' items, depletes in '+daysLeft.toFixed(1)+' days');
  if (daysLeft<2) console.log('ALERT: Queue depletes within 48 hours!');
} else { console.log('Discovery queue: stable or growing'); }

fs.writeFileSync('/tmp/oracle-forecast.json', JSON.stringify({computed:new Date().toISOString(), snapshots:snapshots.length}, null, 2));
console.log('\nForecast written to /tmp/oracle-forecast.json');
ORACLE
```
Expected output: Per-metric forecasts with R² and milestone dates, pattern detection, depletion alerts.