savings-tracking

name	savings-tracking
description	The run state schema and how to compute and report the monitored result (dollars and percent saved, time elapsed). Use to read/write run state and to produce the hero metric the dashboard displays.

Savings Tracking (the monitored result)

The whole project is judged on a believable, verified saving. This skill defines the single source of truth and the math.

State file: state/run-<id>.json

{
  "id": "run_001",
  "need": { "product": "Ergonomic office chairs", "quantity": 500,
            "specs": "...", "region": "EU", "targetPrice": 74, "budgetPrice": 90 },
  "status": "sourcing|rfq_sent|quoting|negotiating|voice|done",
  "startedAt": "ISO", "finishedAt": "ISO",
  "suppliers": [
    { "id": "sup_1", "name": "...", "contact": "...", "source": "web|seed", "fitScore": 88,
      "rfq": { "subject": "...", "body": "...", "createdAt": "ISO" },
      "quote": { "unitPrice": 84, "quantity": 500, "leadTime": "3w",
                 "paymentTerms": "net-30", "freight": "FOB", "landedUnit": 86, "receivedAt": "ISO" },
      "negotiationRounds": [
        { "channel": "email", "offer": 71, "counter": 80, "ts": "ISO", "rationale": "..." },
        { "channel": "voice", "offer": 73, "counter": 76, "ts": "ISO" }
      ],
      "floorPrice": 72
    }
  ],
  "baselineTotal": 43000,
  "ranking": ["sup_1", "sup_3", "sup_2"],
  "deal": { "supplierId": "sup_1", "finalUnit": 74, "finalTotal": 37000,
            "savings": 6000, "pct": 0.14, "verified": true },
  "metrics": { "suppliersContacted": 5, "quotesReceived": 4, "rounds": 3,
               "elapsedMs": 360000, "humanBaselineHours": 24 }
}

floorPrice is supplier-simulator-internal. Never surface it in buyer-facing output.

Math

• landedUnit = unitPrice + freight-per-unit + payment-term cost adjustment.
• baselineTotal = min(best initial landed total across suppliers, budgetPrice x quantity).
• finalTotal = finalUnit x quantity (+ landed adjustments).
• savings = baselineTotal - finalTotal; pct = savings / baselineTotal.
• elapsed = finishedAt - startedAt. Compare to humanBaselineHours for the "X days -> Y min" line.

Verification (always before reporting)

Recompute savings from raw fields; confirm finalUnit appears in the last negotiation round; confirm quantity unchanged; set deal.verified=true only if it all reconciles. Otherwise flag.

Dashboard hero metrics

$ saved (animated counter), % off baseline, elapsed vs human, plus live counts of suppliers / quotes / rounds. The Next.js dashboard polls this file (or its DB mirror) every ~1s.