AR aging action plan

The collections morning routine, formalized

Before this workflow, AR collections meant Mike opened the NetSuite AR aging report, mentally sorted customers into "need to call" / "send statement" / "escalate", drafted a few emails, and lost the rest of the morning. The AR aging action plan formalizes that into a daily cron that does the grouping, drafts the emails, and surfaces the priority queue.

Contract: workflow_definitions WHERE workflow_type='ar_aging_action_plan' — trigger is cron (weekdays 7am ET), risk level 3, expected duration 30 minutes including two HITL gates.

The defining property: lagging indicator. AR aging is what happens after a customer disengages. The proper leading-indicator pairing is the customer health substrate. This workflow handles the "already in the bucket" cases; customer health handles the "about to fall in" prediction.

Trigger conditions

• Daily cron at 7am ET — the default trigger. Mike sees the action plan at his desk.
• Manual trigger when a large customer crosses 90 days mid-cycle.
• After a payment batch posts and we want to recompute who's still owing.
• End-of-month close — Mike wants the full picture before booking the period.

The four tiers and their actions

Cardinal $5K invoice goes 90+

The four beats

1. 01

   Aging snapshot (auto)

   get_ar_aging_summary queries ar_aging (refreshed nightly from NS), buckets by 30/60/90/120, and computes per-customer totals. The result is materialized into ar_action_snapshots for the day so the rest of the workflow operates against a stable read.

   Reads ar_aging, customers, invoices

   Writes ar_action_snapshots

   Time ~400ms
2. 02

   Prioritize + draft (auto + HITL)

   Each customer in the snapshot gets a recommended action based on its highest bucket. Strategic-account overrides apply. The AI drafts the corresponding email/phone-prompt with full context — invoices, dates, amounts, last contact attempt. Drafts land in proposed_actions with action_type='collection_email' or 'phone_prompt'.

   Writes proposed_actions

   HITL step 2
3. 03

   Mike reviews + approves (HITL)

   The morning queue is sorted by bucket severity (120 → 90 → 60 → 30). Mike can bulk-approve all 30-day reminders (low risk) and single-decide the 90/120 cases. R560 atomic claim prevents double-fire.

   Reads proposed_actions filtered by daily action plan

   HITL step 3 (per-action)
4. 04

   Send + record (HITL approve → auto execute)

   Approved emails go via Email Routing. Phone-prompt rows land on Mike's task list. Order holds (if approved) write to customer_holds. Events ar.collection_sent and ar.hold_placed are emitted so customer health can react.

   Writes outbound_email_log, customer_holds, events

   Emits ar.collection_sent, ar.hold_placed

What's different after the workflow runs

• Every customer with past-due AR has either an action taken or a deliberate skip recorded.
• ar_action_snapshots retains the daily bucket distribution for trend analysis.
• Customer health signals receive the ar.bucket_moved event and adjust risk scores.
• Strategic accounts get individualized treatment per their override.
• Mike's collections morning is now ~15 minutes of review, not 90 minutes of building.

What can go wrong and how to recover

Adjacent workflows + diagrams

Code paths + invariants

Dated trail · spot stale claims

Dated trail of when this doc was last touched, what changed, and what to look at if it feels stale.

The machine-readable spec

Canonical fields, table names, endpoint signatures. What code should match, what tests should assert. workflow_type · ar_aging_action_plan · risk_level · 3.

Inputs (required + optional)

D1 tables written

Endpoints called

Events fired

It broke at 2am — what now

Different from "how do I use this." This is the page Mike pulls up when something is wrong: logs to check, recovery steps, who to escalate to.

Logs to check

• workflow_run_log · top-level run audit
• workflow_step_log · per-step trace
• workflow_verify_results · post-window verify outcomes
• cron_locks · stuck cron lock detection
• events · workflow.completed / workflow.failed event trail
• reflexion_log · per-run narrative (if reflexion_enabled)
• npx wrangler tail · live Worker logs

Kill switch · emergency stop

If this workflow is misbehaving in a high-impact way (creating bad proposed_actions in volume, pushing wrong things to NS), flip a kill switch:

• kill:ns_writes · stops every NS push platform-wide
• kill:proposed_apply · stops HITL approvals from executing fan-out
• kill:high_risk_ops · stops risk_level >= 4 fan-out

See kill-switches-state-machine.html for the full state machine + recovery procedure.

Escalation

Primary: Mike Levine (single-admin) · mikelevine@globalfoodsolutions.co. For prolonged outage during business hours, notify warehouse lead + accounting lead so they can defer dependent work.

What's not done · what's uncertain

What's not done, what's uncertain, what we punted. Captured so it survives context switches and doesn't die in someone's head.

• STUB
  loop_over_aging kind not implemented in runner

  draft_per_tier emits status='stub'. Real implementation needs the loop to iterate per aging bucket and stage a draft per tier.

• STUB
  flag kind not wired

  pause_on_hold_check is documented but not executable; Mike manually flags holds today.

• STUB
  hitl_email_draft kind not wired

  sales_rep_notify documented but emails are drafted via separate chat tool, not the runner.

• OPEN
  Tiered escalation thresholds

  Today thresholds are static (90d + $25K). Should be configurable per customer (DOE has 60-day terms, commercial has 30).

• DECISION
  Cron timing — daily or weekly?

  Daily means 30 nags for same delinquent customer. Weekly means 4. Mike's call.

• DEFER
  Service hold enforcement at SO creation

  Today service_hold is a flag but doesn't block SO creation. Needs a precondition in propose_sales_order.