Skip to content

v1: Overnight Brief (Karl, start here)

The first build. Read-only, no writes to Amazon, no risk. It produces the Profasee signature artifact: a daily "here is what your agents found and what it is worth" report, on data we already have. Ship this before any action mode.

Goal

Once a day, after the nightly refresh, generate one ranked brief of recommendations across demand, PPC waste, and (if the pricing read-feed exists) pricing, each line with reasoning and a dollar figure. Deliver to Discord and publish a live dashboard page.

Scope (in)

  • Demand section: top stockout risks and the reorder list, from forecasts.po_recommendations + forecasts.predictions + raw.fba_restock / raw.inventory_ledger_summary. (Demand agent, mostly a query.)
  • PPC waste section: ASINs/keywords with spend and little or no attributable sales over a trailing window, from agg.ad_spend_unified_asin_daily joined to agg.sales_daily_unified; plus under-target-ACOS scaling candidates using agg.profit_daily for true margin. (PPC agent, read-only analysis.)
  • Headline number: total dollars identified (waste to cut + stockout cost to avoid + margin opportunity), like Profasee's "+$412 overnight."
  • Per-line provenance: every figure cites ASIN + table + date range (the quantity-citation rule).

Scope (out, for v1)

  • No Amazon writes. No bid/price/keyword changes. Recommendations only.
  • No pricing competitor feed yet (add later; pricing section optional in v1).
  • No autonomy ladder UI yet; everything is observe mode by definition.

Deliverables

  1. agents/coordinator/build_brief.py (new): runs the read queries, assembles a ranked, sourced brief as structured data, writes it to a new table agents.brief_runs (one row per day) and agents.brief_items (one row per recommendation, with agent, ASIN, type, reason, dollar_impact, source).
  2. Discord delivery: post the brief summary + top items via the existing Discord webhook pattern (scripts/discord/relay.mjs / mission-control sendDiscordWebhook).
  3. Dashboard page: publish an HTML page (Cloudflare Pages, same flow as this docs site) reading agents.brief_items, showing today's brief + history. URL Ace can open.
  4. Schedule it at the end of nightly_refresh.sh, gated on pipeline_watchdog green so it never runs on failed/stale data.

Acceptance criteria

  • Runs end-to-end on real data and posts to Discord.
  • Every dollar figure is traceable to a query (no fabricated or back-calculated numbers).
  • Stockout and waste lists match spot-checks against the warehouse.
  • Dashboard URL renders today's brief and at least the prior few days.

Data access for Karl

  • Read-only DB role (karl_ro) is already provisioned; connection string from Ace. Use it for development.
  • Schema reference: Data Warehouse, Inventory Data Warehouse, and the migrations in db/migrations/.
  • Reuse helpers in scripts/lib_sticky.py (vault, DB url) and existing scripts/push_*.py for the Sheets/Discord patterns.

After v1

Add the runtime (reasoning log already partly modeled by forecasts.scores), then action mode one domain at a time per Guardrails: PPC first (bids/waste), pricing last.