Playbook: Build an Overnight Reconciliation Agent

The numbers in your warehouse system and the numbers in your ERP are supposed to agree. They almost never do — not exactly. There is always some drift: in-flight transactions, batch lag, manual adjustments somebody forgot to mirror in the other system. Most of the time the drift is small enough not to matter. Some of the time it represents a real problem — a missed receipt, a mis-keyed adjustment, a duplicate transaction.

The trouble is, by the time anyone notices, days have passed. Finance discovers it during the monthly close. Somebody spends half a day tracing the discrepancy. By the time it is fixed, three new ones have appeared, and nobody can tell whether the new ones are different problems or the same problem still oscillating.

This playbook walks you through building a scheduled subagent that runs every night, takes a snapshot of inventory from your WMS and your ERP, diffs them, and keeps a running log of every discrepancy — what is new, what is still open, what got resolved. You wake up to a clean report and a real audit trail.

What you will build

By the end of this playbook, you will have:

  • A subagent called Overnight Reconciliation that runs unattended every night.
  • Custom tools that pull a canonical inventory snapshot from both systems.
  • A private filesystem on the agent that stores every snapshot, every diff, and a running open-discrepancies log.
  • A scheduled trigger that fires at 2 AM in your finance team's timezone.
  • A morning Slack post in #finance-ops summarizing what changed overnight.

What you need before you start

  • An Assist workspace with your AI client connected via MCP.
  • Read API access to your WMS and ERP. Use a read-only credential — the reconciliation agent should never be able to mutate either system.
  • A canonical SKU list. You may not want to track every part number — pick the ones that matter financially.
  • An understanding of acceptable variance. Some drift is normal. You will set a threshold below which the agent does not flag a discrepancy.
  • The Slack bot in your #finance-ops channel.

Step 1: Design the file layout

Before you build anything, decide how the agent will keep its records on disk. Open a chat with your AI client and work it out:

"We are going to build a reconciliation agent that takes nightly snapshots of inventory from our WMS and ERP. I want to keep:

  • Each night's raw snapshots, dated, so we can reconstruct any day's state.
  • A diff file per night that shows every SKU where the two systems disagreed.
  • A single running file of currently open discrepancies, sorted by oldest first.
  • An append-only log of resolved discrepancies, with the date they were resolved and how.

Propose a file layout."

The client will propose something like:

  • /snapshots/wms/<YYYY-MM-DD>.jsonl — one JSON object per SKU.
  • /snapshots/erp/<YYYY-MM-DD>.jsonl — same shape, ERP version.
  • /diffs/<YYYY-MM-DD>.md — markdown diff for that night.
  • /open.md — the current open-discrepancies list.
  • /closed.md — append-only log of resolved items.

Iterate until you are happy with it. Lock the layout in writing — the agent will rely on it for every run.

Step 2: Build the snapshot tools

You need two tools, one for each system. Build them in /tools/new, test them on the edit page, and publish each one before moving on. If you haven't built workspace tools before, the shared toolbox playbook walks through the build/test/publish flow end to end — especially important here, since these tools are going to run unattended every night.

Each blockquote below is the spec for one tool:

wms_inventory_snapshot — takes no parameters. Calls GET https://wms.internal.company.com/api/inventory with bearer token auth using the secret WMS_READ_TOKEN. Returns an array of objects with the shape {sku, on_hand, location, snapshot_at}. Include the WMS server timestamp from the response header.

erp_inventory_snapshot — takes no parameters. Calls GET https://erp.internal.company.com/api/inventory/current with the secret ERP_READ_TOKEN. Returns the same shape: {sku, on_hand, location, snapshot_at}. Our ERP uses underscores in SKUs (A_7321) but the WMS uses hyphens (A-7321) — normalize the ERP output to use hyphens so they match.

Test each tool on its edit page. Confirm you get back a sensible row count (it should match the number of SKUs you stock, give or take in-flight items). Confirm the SKU formats line up. Spot-check a few specific SKUs against what you can see in the source systems' UIs. Then publish each tool so the subagent can use it.

Step 3: Create the subagent

Go to Subagents > New Agent and fill in:

  • Label: Overnight Reconciliation

  • Description: Runs nightly. Snapshots inventory from WMS and ERP, diffs them, maintains an open-discrepancies log, and posts a morning summary to #finance-ops.

  • Job Description:

    You are the overnight reconciliation agent. You run unattended every night. Your job is to keep a faithful, time-ordered record of inventory drift between our WMS and our ERP, and to surface anything that needs human attention.

    You are read-only. You may never call any write operation against the WMS or ERP. The only writes you do are to your own filesystem and to Slack.

    Each run, you do the following:

    1. Call wms_inventory_snapshot and erp_inventory_snapshot. Save each result as a .jsonl file at /snapshots/wms/<today>.jsonl and /snapshots/erp/<today>.jsonl.
    2. Compare the two snapshots SKU by SKU. A discrepancy is any SKU where the on-hand counts differ by more than 5 units OR by more than 1% of the larger value, whichever is larger.
    3. Read the previous /open.md. For every existing discrepancy, check whether it is still present in today's diff. If it is, leave it open. If it is not, append a "resolved" entry to /closed.md with today's date.
    4. For every new discrepancy not in the previous /open.md, add it to today's /open.md with a first_seen date of today.
    5. Write today's full diff to /diffs/<today>.md in human-readable markdown — group by warehouse, show SKU, WMS count, ERP count, delta, and how long the discrepancy has been open.
    6. Post a one-paragraph summary to #finance-ops: how many discrepancies are now open, how many are new today, how many were resolved overnight, and the three biggest open ones by absolute dollar impact (use a fixed standard cost lookup if needed — for now, just use unit count).

    Be terse. The morning Slack message is the only thing the team will read most days.

  • Model: pick a capable model — this is reasoning-heavy work.

  • Projects: leave empty.

  • Tools: wms_inventory_snapshot, erp_inventory_snapshot, plus slack_send_message from slack_v1. Filesystem tools are added automatically when you turn on the filesystem in the next step.

Save the agent.

Step 4: Turn on the filesystem

Open the agent's edit page. Find the filesystem toggle and turn it on. The agent now has a private set of fs_* tools and a private text-file store.

The first run will create the directories. You do not need to seed anything.

Step 5: Do a manual test run

Open a chat with the agent and tell it to do exactly what its job description says, but for today only:

"Do a full reconciliation run for today. Walk me through what you do, but actually do it — write the snapshots, write the diff, populate /open.md, and post the Slack message. If anything looks off, stop and ask."

The first run is where you discover all the things the prompt left implicit. The agent might:

  • Ask whether to include zero-quantity SKUs (decide and write the answer into the prompt).
  • Find that the timestamps from the two systems are in different timezones (decide a canonical timezone and tell the agent to convert).
  • Surface 4,000 open discrepancies on the first run because nothing has ever been reconciled (decide whether to mark them all "pre-existing" with today's date or leave them as-is).

Iterate. It is easier to get the first run right than to fix it later.

Step 6: Schedule it

Once the manual run is clean, schedule it. From the agent's chat:

"Schedule yourself to run every day at 2:00 AM America/New_York with the prompt 'Do a full reconciliation run for today.' Call the trigger 'Nightly Reconciliation'."

The agent confirms and creates the trigger. Verify the trigger appears on the agent's card on the Subagents page.

Step 7: Watch the first three nights

Open /agent-tasks each morning for the next three days. For each run, check:

  • Did the run complete successfully?
  • Did the morning Slack post arrive at a reasonable time?
  • Did the open-discrepancies count make sense compared to yesterday?
  • Are the discrepancies the agent flags actually real discrepancies, or noise?

If discrepancies are noisy, tighten the threshold in the system prompt (> 5 units OR > 1% — adjust both sides). If real ones are getting missed, loosen it.

Step 8: Add a resolution loop

Right now the agent passively notices when discrepancies disappear. To close the loop, give the team a way to mark a discrepancy as "investigated and explained" so the agent can move it to /closed.md even when it is still present.

Open the agent's chat and talk it through:

"Add a new behavior: when somebody posts in #finance-ops saying 'mark SKU X as resolved' or 'investigated SKU X — pre-existing batch lag', remove that SKU from /open.md and append to /closed.md with the message text as the resolution note."

This needs the channel mapping you set up in the ops concierge playbook, or you can add a separate #finance-ops channel mapping and let the same agent handle both nightly runs and ad-hoc team messages.

What you built

You have a reconciliation agent that:

  • Runs every night without anyone remembering to trigger it.
  • Builds an immutable, dated audit trail of every snapshot and every diff.
  • Maintains a clean "currently open" view that finance can act on.
  • Distinguishes pre-existing drift from new drift, so attention goes to what actually changed.
  • Runs in a managed environment — every tool call is logged, the credentials live in the workspace not on someone's laptop, and the entire history is retrievable.

What used to be a quarter-end fire drill is now a five-minute morning skim.

Where to go from here

  • Add cost weighting. Plug in standard costs and have the agent rank discrepancies by dollar impact.
  • Compare across more systems. Add a third snapshot tool (your physical count system, your 3PL portal) and fold it into the diff.
  • Build a sandcastle dashboard. Link the agent to a sandcastle app where finance can see the open-discrepancies list, click to assign owners, and mark items resolved with a note. The agent reads from and writes to the sandcastle's state collection instead of (or in addition to) the markdown files.
  • Trend analysis. Add a weekly subagent that reads the last seven /diffs/*.md files and reports whether reconciliation drift is getting better or worse.

Related guides