---
name: metrc-reconcile
description: >-
  Compare a Metrc active-packages CSV export with an inventory/ERP packages CSV
  export (Distru or any system with a Metrc tag column), find every mismatch by
  tag and quantity using the bundled script, then explain the most likely cause
  of each mismatch and what to check first. Use when the user says "reconcile
  Metrc", "Metrc check", "run the Metrc reconciliation", "why don't Metrc and
  inventory match", or provides two package exports and asks to compare them.
  Read-only: never proposes or performs changes in Metrc.
---

# Metrc reconciliation

Deterministic diff first, explanation second, human decides. You never compare
rows yourself; the script does that. You never change anything in Metrc or the
inventory system.

## Inputs

Ask for two CSV files if not already provided:

1. **Metrc export**: Metrc → Packages → Active → export. Must contain a tag
   (label) column and a quantity column. Unit column is helpful.
2. **Inventory export**: the ERP's active packages with the Metrc tag column
   visible. For Distru: the Packages page CSV export, or `GET /public/v1/packages`
   saved as CSV.

If the user does not know the column names, look at the header row and map
them. Common names are listed in `references/columns.md`.

## Steps

1. Confirm both files exist and have a header row. If either has fewer than
   2 rows, stop and say so.
2. Run the diff script. Do not read the full files into your own reasoning;
   only read the script output.

   ```bash
   node scripts/reconcile.mjs \
     --metrc metrc_packages.csv \
     --erp inventory_packages.csv \
     --metrc-tag "Tag" --metrc-qty "Quantity" --metrc-unit "Unit of Measure" \
     --erp-tag "Metrc Tag" --erp-qty "Quantity" --erp-unit "Unit" \
     --tolerance 0.01 \
     --out deltas.json
   ```

   Adjust the column flags to the actual headers. The script prints a summary
   line and writes `deltas.json` with three arrays: `only_in_metrc`,
   `only_in_erp`, `quantity_mismatch`.
3. If total deltas exceed 200, tell the user the exports are probably from
   different dates or licenses and ask them to confirm before continuing.
4. For each row in `deltas.json`, assign exactly one `most_likely_cause` from
   `references/causes.md`, a `confidence` of high / medium / low, and one
   `next_check` sentence. Use only the fields in the row. Do not invent
   quantities, dates, or product names.
5. Write `reconciliation-report.md` using the template below. Sort each section
   by confidence, low first, so the human reads the uncertain ones first.
6. Tell the user the counts and where the report is. Do not recommend a
   specific quantity edit. Recommend *what to check*.

## Report template

```markdown
# Metrc reconciliation: {date}

Metrc rows: {n}  ·  Inventory rows: {n}  ·  Matched: {n}
Only in Metrc: {n}  ·  Only in inventory: {n}  ·  Quantity mismatch: {n}

## Quantity mismatches
| Tag | Metrc qty | Inventory qty | Δ | Unit | Product | Likely cause | Confidence | Check first |
|---|---|---|---|---|---|---|---|---|

## Only in Metrc (not in inventory)
| Tag | Metrc qty | Unit | Product | Likely cause | Confidence | Check first |

## Only in inventory (not in Metrc active)
| Tag | Inventory qty | Unit | Product | Status | Likely cause | Confidence | Check first |

## Notes
- Anything you are unsure about, and why.
```

## Rules

- Never propose a Metrc edit, adjustment, or finish action. Say what to check.
- Never compare rows without the script. If the script fails, fix the column
  flags or report the error; do not fall back to eyeballing.
- If a unit differs between systems for the same tag, call it `unit_mismatch`
  regardless of the numbers.
- If `only_in_metrc` is large right after a delivery day, mention unaccepted
  incoming transfers as the first thing to check.
- Keep the user's data local. Do not paste full exports into any external
  service.

## Customizing for your operation

- Set `--tolerance` to what your state and lab practice justify (0.01 to 0.5
  in the package unit is typical).
- Edit `references/causes.md` to add causes specific to you (e.g., "pre-roll
  line consumes flower without a Metrc production batch until Friday").
- Add your lab's typical sample draw to `references/causes.md` so
  `unrecorded_sample` can be assigned with higher confidence.