{{command_prefix}}roi
Closes the loop on cost: {{command_prefix}}budget forecasts spend, this shows the return. It joins per-cycle
cost with the commits that actually stuck, so you can see cost-per-shipped-commit and which cycles
were worth it. Read-only - it reads git log + cost telemetry and prints a table. Contract +
the "shipped" definition: ../../reference/cost-governance.md.
Invocation
| Command | Behavior |
|---|---|
{{command_prefix}}roi | ROI table across all cycles with cost telemetry (14-day stick window). |
{{command_prefix}}roi --since <date> | Only cycles since <date>. |
{{command_prefix}}roi --window-days N | "Shipped" = a commit surviving ≥ N days (default 14). |
Steps
-
Check telemetry exists. No
.design/telemetry/costs.jsonl(or zero rows) → printroi: no cost telemetry yet — run a cycle first.and exit. -
Per-cycle cost. Group
est_cost_usdincosts.jsonlbycycle. -
Per-cycle shipped / reverted. For each cycle, use
git logto count, in that cycle's date range: commits still present inmainand older than the window = shipped; commits that a laterrevertremoved (or that were reverted within the window) = reverted. (A commit younger than the window is "too new to score" - exclude it, don't count it as shipped.) -
Join + compute via the pure helper - never hand-compute:
bashnode -e ' const { computeRoi, roiTableMarkdown } = require("./scripts/lib/budget/roi.cjs"); const cycles = JSON.parse(process.argv[1]); // [{cycle,costUsd,commitsShipped,commitsReverted},...] console.log(roiTableMarkdown(computeRoi(cycles))); ' "$CYCLES_JSON" -
Render the markdown table (cycle · cost · shipped · reverted · $/shipped · stick rate) plus the TOTAL row. A high
$/shippedwith a low stick rate is the signal that a cycle burned budget without lasting output. -
Do not act. Reporting only - never revert, re-run, or change budget.
Output
End with:
## ROI COMPLETE
