Budget Tracking skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Budget Tracking"
  short_description: "Every variance explained, owned and forecast"
  default_prompt: "$budget-tracking Set up a budget vs actual tracker in Google Sheets from our approved budget and the Xero P&L export"

#!/usr/bin/env python3
"""Budget vs actual variance report with materiality flags.

Input CSV columns (header required):
  line     budget line, e.g. "Marketing - Paid search"
  type     revenue | expense  (decides whether over-budget is favourable)
  month    YYYY-MM
  budget   budgeted amount for the month (blank = 0)
  actual   actual amount for the month (blank = not yet closed; month is skipped)

Usage:
  python3 variance_report.py budget_vs_actual.csv
  python3 variance_report.py budget_vs_actual.csv --month 2026-09 --pct 10 --abs 5000

A line is flagged when |variance| >= --abs AND |variance %| >= --pct, for the month
or year to date. Exit code 0 = no flags, 2 = flags found, 1 = bad input.
"""
import argparse
import csv
import sys
from collections import defaultdict
from decimal import Decimal, InvalidOperation


def num(value, where):
    value = (value or "").strip().replace(",", "")
    if value == "":
        return None
    try:
        return Decimal(value)
    except InvalidOperation:
        print(f"error: {where}: not a number: {value!r}", file=sys.stderr)
        sys.exit(1)


def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("csv")
    ap.add_argument("--month", help="report month YYYY-MM (default: latest month with actuals)")
    ap.add_argument("--pct", type=Decimal, default=Decimal("10"), help="percent threshold (default 10)")
    ap.add_argument("--abs", type=Decimal, default=Decimal("1000"), help="absolute threshold (default 1000)")
    args = ap.parse_args()

    rows = defaultdict(dict)   # (line, type) -> month -> (budget, actual)
    closed = set()
    with open(args.csv, newline="", encoding="utf-8-sig") as fh:
        reader = csv.DictReader(fh)
        need = {"line", "type", "month", "budget", "actual"}
        if not reader.fieldnames or not need <= set(reader.fieldnames):
            print(f"error: CSV needs columns {sorted(need)}, got {reader.fieldnames}", file=sys.stderr)
            sys.exit(1)
        for n, r in enumerate(reader, start=2):
            kind = r["type"].strip().lower()
            if kind not in ("revenue", "expense"):
                print(f"error: line {n}: type must be revenue or expense, got {r['type']!r}", file=sys.stderr)
                sys.exit(1)
            b = num(r["budget"], f"line {n} budget") or Decimal(0)
            a = num(r["actual"], f"line {n} actual")
            month = r["month"].strip()[:7]
            rows[(r["line"].strip(), kind)][month] = (b, a)
            if a is not None:
                closed.add(month)
    if not closed:
        print("error: no actuals found", file=sys.stderr)
        sys.exit(1)
    month = args.month or max(closed)
    year = month[:4]

    def var(kind, b, a):
        v = a - b if kind == "revenue" else b - a      # positive = favourable
        p = (v / b * 100) if b else None
        return v, p

    def flag(v, p):
        return abs(v) >= args.abs and (p is None or abs(p) >= args.pct)

    hdr = f"{'line':<34}{'type':<9}{'budget':>12}{'actual':>12}{'var':>11}{'var%':>8}{'YTD bud':>13}{'YTD act':>13}{'YTD var':>11}{'YTD%':>8}  flag"
    print(f"Variance report for {month} (positive variance = favourable)\n")
    print(hdr)
    print("-" * len(hdr))
    flagged = 0
    totals = defaultdict(lambda: [Decimal(0)] * 4)
    for (line, kind), months in sorted(rows.items()):
        b, a = months.get(month, (Decimal(0), None))
        if a is None:
            a = Decimal(0)
        ytd = [(bb, aa) for m, (bb, aa) in months.items() if m[:4] == year and m <= month and aa is not None]
        yb = sum((x for x, _ in ytd), Decimal(0))
        ya = sum((y for _, y in ytd), Decimal(0))
        v, p = var(kind, b, a)
        yv, yp = var(kind, yb, ya)
        marks = []
        if flag(v, p):
            marks.append("MONTH")
        if flag(yv, yp):
            marks.append("YTD")
        flagged += bool(marks)
        t = totals[kind]
        t[0] += b; t[1] += a; t[2] += yb; t[3] += ya
        fp = lambda x: f"{x:7.1f}%" if x is not None else "    n/a"
        print(f"{line[:33]:<34}{kind:<9}{b:>12,.0f}{a:>12,.0f}{v:>11,.0f}{fp(p):>8}{yb:>13,.0f}{ya:>13,.0f}{yv:>11,.0f}{fp(yp):>8}  {' '.join(marks)}")
    print("-" * len(hdr))
    for kind, (b, a, yb, ya) in sorted(totals.items()):
        v, _ = var(kind, b, a)
        yv, _ = var(kind, yb, ya)
        print(f"{'TOTAL ' + kind:<43}{b:>12,.0f}{a:>12,.0f}{v:>11,.0f}{'':>8}{yb:>13,.0f}{ya:>13,.0f}{yv:>11,.0f}")
    print(f"\n{flagged} line(s) flagged at >= {args.pct}% and >= {args.abs:,} absolute")
    sys.exit(2 if flagged else 0)


if __name__ == "__main__":
    main()