ProcureOps Solver
Overview
This skill guides solving procurement-domain tasks backed by a shared ProcureOps
REST API. Every task provides local payloads (memos, packets, templates) that
name anchor IDs; the API is the system of record for all operational data.
Answers must be pure JSON matching the task's answer_template.json.
The ProcureOps API
The runner supplies the base URL as <TASK_ENV_BASE_URL>. All endpoints are
read-only GET. No authentication is required.
| Endpoint |
Returns |
/health |
Liveness check |
/manifest |
Endpoint listing / schema hints |
/suppliers |
Supplier records (id, name, status, risk_rating) |
/items |
Item / SKU records |
/programs |
Program records (id, owner, budget_cap) |
/contracts |
Contract records (id, program_id, supplier_id, sku, price_type, unit_price, ceiling_amount, status) |
/purchase_requisitions |
Requisition records (id, program_id, sku, supplier_id, status) |
/purchase_orders |
PO records (id, program_id, requisition_id, contract_id, supplier_id, lines with sku/qty/unit_price, status) |
/receipts |
Receipt records (id, po_id, receipt_date, lines with sku/qty received/rejected, status) |
/ap/invoices |
Invoice records (id, po_id, supplier_id, lines with sku/qty/unit_price, subtotal, freight, tax, total, status, hold_code) |
/ap/payments |
Scheduled/executed payment records (invoice_id, amount, status) |
/approvals |
Approval event records (requisition_id or contract_id, action, actor, event_date) |
/budget_snapshots |
Budget snapshot records (program_id, budget_cap, committed_amount) |
/vendor_risk_events |
Vendor risk event records (supplier_id, severity, status) |
Query conventions
- Many endpoints accept query parameters. Start with a bare GET to inspect all
records, or filter by known IDs when supported.
- IDs follow predictable prefixes:
SUP- (supplier), PRG- (program),
CR- (contract), REQ- (requisition), PO- (PO), RCV- (receipt),
AP- (invoice), VRE- (vendor risk event), APR- (approval event),
BUD- (budget snapshot), CB- (chargeback).
- Cross-reference records by following foreign-key fields:
supplier_id on contracts, POs, receipts, invoices, risk events
program_id on contracts, POs, requisitions, budget snapshots
contract_id on POs
po_id on receipts, invoices
requisition_id on POs, approvals
invoice_id on payments
sku on items, contracts, requisitions, PO lines, receipt lines, invoice lines
Program scoping
When a task targets specific programs, scope all API lookups to records
associated with those programs. A PO belongs to a program either directly
through its program_id field or through its linked contract or requisition.
An invoice belongs to a program through its PO.
Domain Model: Procurement Lifecycle
Contract -- PO -- Receipt -- Invoice -- Payment
| | | |
--- SKU ---+--------+-----------+
Requisition -- PO -- Approval events
Budget Snapshot --- Program (committed = sum of non-cancelled PO subtotals)
Vendor Risk Events --- Supplier
Key relationships:
- Contract establishes pricing (unit_price, price_type) and a spending
ceiling for a supplier+SKU+program combination.
- Purchase Order places an order under a contract or requisition with
line-item quantities. PO statuses:
open, partial_receipt,
fully_received, cancelled.
- Receipt confirms delivery. One PO can have multiple receipts. Receipt
statuses:
accepted, pending_inspection. Receipt lines record quantities
received and rejected.
- Invoice requests payment. Invoice statuses:
approved, on_hold,
pending_receipt, paid. Hold codes: QTY_VARIANCE, NO_RECEIPT,
PRICE_MISMATCH, DAMAGE_REJECTION.
- Payment records scheduled or executed payments against invoices.
- Approval events track workflow state for requisitions and contracts.
A requisition must reach
approved status before the associated PO is
fully cleared for sourcing.
- Budget snapshots track program spending:
committed_amount is the sum
of subtotals from non-cancelled POs under that program.
- Vendor risk events track supplier-level issues. Severity:
severe,
moderate, watch. Status: open, closed, monitoring. A supplier's
risk_rating on the supplier record itself is a summary (e.g., watch,
clean, flagged).
Common Workflows
1. Sourcing Nomination Readiness
For each line SKU in a nomination packet:
Supplier identification: Trace from the requisition or PO to find the
selected supplier. The requisition's supplier_id or the PO's supplier_id
is the nominated supplier.
Contract check: Look up contracts by program_id + sku + supplier_id.
A SKU with an active contract has commercial_basis_id set. Missing contract
adds missing_contract blocker.
Receipt evidence: Find receipts linked to the SKU's POs by matching
po_id and receipt-line sku. Receipt existence provides evidence.
Invoice exceptions: Find invoices linked to the SKU's POs. Check invoice
status and hold_code. An on_hold or pending_receipt invoice adds
ap_hold or pending_receipt blockers.
Risk events: Find open or monitoring risk events for the supplier
(/vendor_risk_events filtered by supplier_id). Open events add
open_supplier_risk. A supplier with risk_rating of watch or flagged
adds supplier_watch.
Due date check: Compare the PO or requisition delivery date against the
task's as_of_date. Late items add late_due_date.
Budget headroom: From /budget_snapshots, compute
remaining_budget = budget_cap - committed_amount.
Readiness decision per line:
ready: No blockers.
at_risk: Only supplier_watch or other minor blockers present.
not_ready: Any of missing_contract, open_supplier_risk, ap_hold,
pending_receipt, late_due_date present.
Nomination decision per line:
nominate: readiness is ready
conditional_nomination: readiness is at_risk
hold: readiness is not_ready
Committee action: send_to_committee is yes only when at least one line
is nominate or conditional_nomination. next_owner is the team that can
resolve the most severe blocker (ap_team for AP holds, buyer for missing
contracts, quality_ops for receipt issues, program_owner for budget).
2. Receiving-Control Closeout
Given a receipt batch ID:
Inspection summary: Pull the receipt record to get po_id, receipt_date,
warehouse_id, packing_slip, receiver. Trace to PO for supplier_id and
program_id. Trace to supplier for supplier_name.
Line reconciliation for each PO line referenced by the receipt:
ordered_qty from PO line
received_qty from receipt line (sum across all receipts for the same PO)
rejected_qty from receipt line
billed_qty from invoice line (sum across all invoices for the same PO)
short_qty_vs_po = ordered_qty - received_qty
unreceived_billed_qty = max(0, billed_qty - received_qty)
receipt_completion_ratio = received_qty / ordered_qty (round to 4 decimals)
po_unit_price from PO line
contract_unit_price from the linked contract
invoice_unit_price from the invoice line
contract_price_match = true when contract_unit_price equals invoice_unit_price
Invoice review: Check the invoice linked to the receipt batch:
exception_codes derive from the data:
INVOICE_QTY_EXCEEDS_RECEIPT when billed_qty > received_qty
PARTIAL_RECEIPT when received_qty < ordered_qty
SUPPLIER_WATCH_RISK when supplier has open risk events or watch rating
PRICE_MISMATCH when contract and invoice unit prices differ
DAMAGE_REJECTION when rejected_qty > 0
Financials:
received_goods_value = received_qty * po_unit_price
unreceived_goods_value = short_qty_vs_po * po_unit_price
invoice_subtotal, invoice_freight, invoice_tax, invoice_total from
invoice record
Decision logic:
batch_disposition:
release_full_invoice when receipt complete and no exceptions
accept_partial_hold_variance when quantity variances but no damage
reject_batch when rejected_qty > 0 (damage)
manual_recount_required when variance is unexplained
ap_action:
release_invoice when no exceptions
keep_invoice_on_hold when exceptions exist
void_invoice for extreme cases
receiving_action:
record_shortage_follow_up when short_qty_vs_po > 0
no_receiving_action when quantities match
reject_all_units when rejected_qty > 0
supplier_action:
request_credit_or_remaining_delivery when short or unreceived-billed
no_supplier_action when no discrepancy
supplier_debit_for_damage when rejected_qty > 0
3. AP Close Desk Reconciliation
Given specific invoice IDs and a close date:
Invoice decisions (one per invoice):
- Pull the invoice, its PO, all receipts for that PO, and any scheduled payments.
hold_decision:
RELEASE when three-way match holds: qty_billed == qty_received, invoice
status is approved, and no unresolved exceptions.
HOLD when qty_billed > qty_received, no receipt exists, or invoice is
on_hold/pending_receipt.
quantity_billed from invoice line
quantity_received = sum of received qty from all receipts for the PO
quantity_variance = quantity_billed - quantity_received
quantity_variance_pct = (|quantity_variance| / ordered_qty) * 100, rounded
to 1 decimal
scheduled_payment_amount = sum of payment amounts for this invoice through
the close period; 0.00 if none.
net_balance_impact = invoice_total - scheduled_payment_amount
release_to_payment = true when hold_decision is RELEASE
hold_code = invoice's hold_code field, or null when releasing
reason_codes:
APPROVED_THREE_WAY_MATCH when quantities match and invoice is approved
QTY_VARIANCE when quantity_variance > 0
NO_RECEIPT when quantity_received == 0
SCHEDULED_PAYMENT_FOUND when scheduled_payment_amount > 0
Vendor balances (one per supplier):
- Group invoice decisions by supplier.
opening_balance = 0.00 unless the task specifies otherwise.
invoice_total = sum of invoice totals for this supplier in the slice
scheduled_payments = sum of scheduled payment amounts
held_invoice_total = sum of invoice totals for HOLD decisions
releasable_invoice_total = sum of invoice totals for RELEASE decisions
close_balance = opening_balance + invoice_total - scheduled_payments
balance_status:
FULLY_SCHEDULED when close_balance == 0 and no held invoices
OPEN_HELD when held_invoice_total > 0
OPEN_APPROVED when close_balance > 0 but all invoices released
Program summary: Group by program_id. held_total = sum of HOLD invoice
totals; released_total = sum of RELEASE invoice totals.
Queues: payment_hold_queue = invoice_ids with HOLD decisions.
payment_release_queue = invoice_ids with RELEASE decisions.
total_close_balance: Sum of all vendor close_balances.
4. Change-Control Decision
Given a change memo specifying contract, SKU, supplier, program, and
requested incremental quantity:
Contract check:
noncancelled_subtotal: Sum PO subtotals (qty * unit_price per line) for
all POs under this contract, excluding cancelled POs.
headroom_before_change = ceiling_amount - noncancelled_subtotal
requested_subtotal = requested_quantity * contract unit_price
headroom_after_change = headroom_before_change - requested_subtotal
ceiling_ok = headroom_after_change >= 0
Program budget check:
- From
/budget_snapshots for the program: budget_cap, committed_amount.
remaining_budget = budget_cap - committed_amount
requested_tax = requested_subtotal * (tax_rate_percent / 100)
requested_total = requested_subtotal + requested_tax
budget_after_change = remaining_budget - requested_total
budget_ok = budget_after_change >= 0
max_quantity_with_current_budget = floor(remaining_budget / (unit_price *
(1 + tax_rate / 100)))
Approval check:
- Find the latest approval event for the source requisition, sorted by
event_date descending.
approval_ok = true when latest action is approved.
Supplier risk check:
- Find open risk events for the supplier (status ==
"open").
supplier_risk_ok = true when no open severe events exist. Supplier on
"watch" alone does not block; only an open event with severity "severe"
makes supplier_risk_ok false.
Overall decision:
release_amendment: all checks pass
hold_for_budget: only budget_ok is false
hold_for_approval: only approval_ok is false
hold_for_supplier_risk: only supplier_risk_ok is false
hold_for_budget_and_approval: both budget_ok and approval_ok are false
reject_contract_mismatch: ceiling_ok is false
required_actions: Derived from failing checks. Include
obtain_final_requisition_approval when approval_ok is false,
raise_budget_exception_or_reduce_quantity when budget_ok is false,
resolve_supplier_risk_hold when supplier_risk_ok is false.
none when all pass.
5. Receiving / AP Release File
Given target PO, receipt, and invoice IDs plus a local chargeback register:
Release decisions (one per invoice):
- Match each invoice to its PO, then find all receipts for that PO.
receipt_ids_in_scope: receipts from the task's target receipt list.
excluded_same_po_receipt_ids: receipts for same PO not in the target list.
- Check the local chargeback register:
approved_chargeback_amount = sum of basis_qty * unit_cost for chargebacks
with status approved for this invoice.
pending_chargeback_amount = sum of basis_qty * unit_cost for chargebacks
with status pending_quality_review for this invoice.
net_release_amount = invoice_total - approved_chargeback_amount (when
releasing); 0.00 otherwise.
Decision per invoice:
release_net_after_approved_chargeback: approved chargebacks exist, no
pending ones. Primary reason: approved_qty_chargeback or
approved_ap_quantity_variance.
hold_missing_receipt: no receipt at all for the PO. Primary reason:
no_receipt_on_po.
hold_pending_quality_chargeback: pending chargebacks in quality review.
Primary reason: inspection_hold_pending_chargeback.
Receiving exceptions (one per receipt in scope, plus missing-receipt
pseudo-entries for POs with no receipts):
exception_codes from chargeback register and receipt data:
Inspection Hold when chargeback is pending_quality_review
Severe Unmatched Quantity when variance is significant
Underage Quantity when received < ordered
AP Quantity Variance when billed != received
chargeback_status: approved, pending_quality_review, or not_applicable
resolution_status:
net_release_ready when approved chargeback exists, no pending
hold_for_quality_review when pending chargeback exists
accepted_no_receiving_exception when no chargeback and receipt is clean
missing_receipt when no receipt exists for the PO
Calculation Reference
Quantity formulas
| Formula |
Definition |
short_qty_vs_po |
ordered_qty - received_qty |
unreceived_billed_qty |
max(0, billed_qty - received_qty) |
quantity_variance |
quantity_billed - quantity_received |
quantity_variance_pct |
(abs(quantity_variance) / ordered_qty) * 100 |
receipt_completion_ratio |
received_qty / ordered_qty |
Dollar amount formulas (all rounded to cents)
| Formula |
Definition |
received_goods_value |
received_qty * po_unit_price |
unreceived_goods_value |
short_qty_vs_po * po_unit_price |
net_balance_impact |
invoice_total - scheduled_payment_amount |
close_balance |
opening_balance + invoice_total - scheduled_payments |
noncancelled_subtotal |
sum(qty * unit_price) for POs where status != "cancelled" |
headroom_before_change |
ceiling_amount - noncancelled_subtotal |
headroom_after_change |
headroom_before_change - requested_subtotal |
remaining_budget |
budget_cap - committed_amount |
requested_tax |
requested_subtotal * (tax_rate_percent / 100) |
requested_total |
requested_subtotal + requested_tax |
budget_after_change |
remaining_budget - requested_total |
max_quantity_with_current_budget |
floor(remaining_budget / (unit_price * (1 + tax_rate/100))) |
chargeback_amount |
basis_quantity * unit_cost |
net_release_amount |
invoice_total - approved_chargeback_amount (when releasing) |
Data Conventions
- USD rounding: Every dollar amount rounded to exactly 2 decimal places
using standard rounding (half-up).
- List sorting: When the template specifies "sorted ascending", sort ID
strings lexicographically ascending, numbers numerically ascending. When the
template says "set", treat as unordered; follow the template's declared sort.
- Null vs missing: Use
null (JSON null) for absent fields, not empty
strings. Use [] for empty lists, 0.00 for zero dollar amounts.
- Dates: Format as
YYYY-MM-DD strings.
- Enums: Use exact enum strings from the answer template. Do not invent new
values.
- Boolean fields: Use JSON
true / false, not strings.
- Reason codes and exception codes: Sort alphabetically within each list.
Record status reference
- Invoice statuses:
approved, on_hold, pending_receipt, paid, void
- Receipt statuses:
accepted, pending_inspection, rejected
- PO statuses:
open, partial_receipt, fully_received, cancelled
- Contract statuses:
active, expired, cancelled
- Supplier risk ratings:
clean, watch, flagged, blocked
- Vendor risk event severity:
severe, moderate, watch
- Vendor risk event status:
open, closed, monitoring
Solving a New Task
- Read the prompt to understand the task type and which API endpoints are
in play. Identify the
<TASK_ENV_BASE_URL> placeholder.
- Read every payload file in
input/payloads/. These name the specific
anchor IDs (programs, POs, receipts, invoices, suppliers, contracts, SKUs).
- Read the answer template (
answer_template.json) to know exactly what
keys, types, enums, and sorting rules the output must follow.
- Query the API: Start by fetching the endpoints most likely to contain
the anchor IDs. Follow foreign keys to pull related records. Fetch
supporting endpoints (suppliers, programs, budget snapshots, risk events)
for context.
- Cross-reference: Join records by
program_id, supplier_id, po_id,
contract_id, sku as needed.
- Apply the workflow rules from this skill for the task type.
- Compute derived values using the formulas above.
- Produce JSON matching the template shape, with correct types, enum
values, sorting, and rounding.
- Return only JSON -- no markdown fences, no prose outside the object.
Common Pitfalls
- Cancelled POs: Exclude POs with status
cancelled when computing
contract usage subtotals and budget commitments.
- Multiple receipts per PO: Sum receipt quantities across all receipts for
a PO when computing received_qty, not just the one named in the task.
- Multiple invoices per PO: An invoice ID may appear in the task but other
invoices for the same PO exist in the system. Only act on the target
invoices unless the template requires broader context.
- Duplicate receipt IDs: When a PO has multiple receipts and the task
targets only one invoice, receipts linked to other invoices on the same PO
should appear in
excluded_same_po_receipt_ids.
- Supplier risk "watch" vs "severe": A supplier with risk_rating
watch
or flagged is contextual but not automatically blocking for all decisions.
For nomination readiness, any open risk event adds open_supplier_risk.
For change-control, only open events with severity severe block release.
- Opening balance: Unless the task specifies otherwise, treat the opening
AP balance as 0.00 for the target suppliers within the task's slice.
- Scheduled payments: Only payments scheduled through the task's effective
period reduce the close balance.
- Tax and freight in change control: Tax applies to the line subtotal only.
Freight is excluded from contract ceiling exposure unless the change memo
explicitly provides a freight amount.
1---2name: procureops-solver3description: Solve ProcureOps procurement tasks by querying the shared REST API, cross-referencing operational records, and producing structured JSON answers using local answer templates.4metadata:5 source: https://skillmd.com/skills/prism-shadow/procureops-solver6---78# ProcureOps Solver910## Overview1112This skill guides solving procurement-domain tasks backed by a shared ProcureOps13REST API. Every task provides local payloads (memos, packets, templates) that14name anchor IDs; the API is the system of record for all operational data.15Answers must be pure JSON matching the task's `answer_template.json`.1617## The ProcureOps API1819The runner supplies the base URL as `<TASK_ENV_BASE_URL>`. All endpoints are20read-only GET. No authentication is required.2122| Endpoint | Returns |23|----------|---------|24| `/health` | Liveness check |25| `/manifest` | Endpoint listing / schema hints |26| `/suppliers` | Supplier records (id, name, status, risk_rating) |27| `/items` | Item / SKU records |28| `/programs` | Program records (id, owner, budget_cap) |29| `/contracts` | Contract records (id, program_id, supplier_id, sku, price_type, unit_price, ceiling_amount, status) |30| `/purchase_requisitions` | Requisition records (id, program_id, sku, supplier_id, status) |31| `/purchase_orders` | PO records (id, program_id, requisition_id, contract_id, supplier_id, lines with sku/qty/unit_price, status) |32| `/receipts` | Receipt records (id, po_id, receipt_date, lines with sku/qty received/rejected, status) |33| `/ap/invoices` | Invoice records (id, po_id, supplier_id, lines with sku/qty/unit_price, subtotal, freight, tax, total, status, hold_code) |34| `/ap/payments` | Scheduled/executed payment records (invoice_id, amount, status) |35| `/approvals` | Approval event records (requisition_id or contract_id, action, actor, event_date) |36| `/budget_snapshots` | Budget snapshot records (program_id, budget_cap, committed_amount) |37| `/vendor_risk_events` | Vendor risk event records (supplier_id, severity, status) |3839### Query conventions4041- Many endpoints accept query parameters. Start with a bare GET to inspect all42 records, or filter by known IDs when supported.43- IDs follow predictable prefixes: `SUP-` (supplier), `PRG-` (program),44 `CR-` (contract), `REQ-` (requisition), `PO-` (PO), `RCV-` (receipt),45 `AP-` (invoice), `VRE-` (vendor risk event), `APR-` (approval event),46 `BUD-` (budget snapshot), `CB-` (chargeback).47- Cross-reference records by following foreign-key fields:48 - `supplier_id` on contracts, POs, receipts, invoices, risk events49 - `program_id` on contracts, POs, requisitions, budget snapshots50 - `contract_id` on POs51 - `po_id` on receipts, invoices52 - `requisition_id` on POs, approvals53 - `invoice_id` on payments54 - `sku` on items, contracts, requisitions, PO lines, receipt lines, invoice lines5556### Program scoping5758When a task targets specific programs, scope all API lookups to records59associated with those programs. A PO belongs to a program either directly60through its `program_id` field or through its linked contract or requisition.61An invoice belongs to a program through its PO.6263## Domain Model: Procurement Lifecycle6465```66Contract -- PO -- Receipt -- Invoice -- Payment67 | | | |68 --- SKU ---+--------+-----------+6970Requisition -- PO -- Approval events7172Budget Snapshot --- Program (committed = sum of non-cancelled PO subtotals)7374Vendor Risk Events --- Supplier75```7677Key relationships:7879- **Contract** establishes pricing (unit_price, price_type) and a spending80 ceiling for a supplier+SKU+program combination.81- **Purchase Order** places an order under a contract or requisition with82 line-item quantities. PO statuses: `open`, `partial_receipt`,83 `fully_received`, `cancelled`.84- **Receipt** confirms delivery. One PO can have multiple receipts. Receipt85 statuses: `accepted`, `pending_inspection`. Receipt lines record quantities86 received and rejected.87- **Invoice** requests payment. Invoice statuses: `approved`, `on_hold`,88 `pending_receipt`, `paid`. Hold codes: `QTY_VARIANCE`, `NO_RECEIPT`,89 `PRICE_MISMATCH`, `DAMAGE_REJECTION`.90- **Payment** records scheduled or executed payments against invoices.91- **Approval events** track workflow state for requisitions and contracts.92 A requisition must reach `approved` status before the associated PO is93 fully cleared for sourcing.94- **Budget snapshots** track program spending: `committed_amount` is the sum95 of subtotals from non-cancelled POs under that program.96- **Vendor risk events** track supplier-level issues. Severity: `severe`,97 `moderate`, `watch`. Status: `open`, `closed`, `monitoring`. A supplier's98 `risk_rating` on the supplier record itself is a summary (e.g., `watch`,99 `clean`, `flagged`).100101## Common Workflows102103### 1. Sourcing Nomination Readiness104105For each line SKU in a nomination packet:106107**Supplier identification**: Trace from the requisition or PO to find the108selected supplier. The requisition's `supplier_id` or the PO's `supplier_id`109is the nominated supplier.110111**Contract check**: Look up contracts by `program_id` + `sku` + `supplier_id`.112A SKU with an active contract has `commercial_basis_id` set. Missing contract113adds `missing_contract` blocker.114115**Receipt evidence**: Find receipts linked to the SKU's POs by matching116`po_id` and receipt-line `sku`. Receipt existence provides evidence.117118**Invoice exceptions**: Find invoices linked to the SKU's POs. Check invoice119`status` and `hold_code`. An `on_hold` or `pending_receipt` invoice adds120`ap_hold` or `pending_receipt` blockers.121122**Risk events**: Find open or monitoring risk events for the supplier123(`/vendor_risk_events` filtered by `supplier_id`). Open events add124`open_supplier_risk`. A supplier with `risk_rating` of `watch` or `flagged`125adds `supplier_watch`.126127**Due date check**: Compare the PO or requisition delivery date against the128task's `as_of_date`. Late items add `late_due_date`.129130**Budget headroom**: From `/budget_snapshots`, compute131`remaining_budget = budget_cap - committed_amount`.132133**Readiness decision** per line:134- `ready`: No blockers.135- `at_risk`: Only `supplier_watch` or other minor blockers present.136- `not_ready`: Any of `missing_contract`, `open_supplier_risk`, `ap_hold`,137 `pending_receipt`, `late_due_date` present.138139**Nomination decision** per line:140- `nominate`: readiness is `ready`141- `conditional_nomination`: readiness is `at_risk`142- `hold`: readiness is `not_ready`143144**Committee action**: `send_to_committee` is `yes` only when at least one line145is `nominate` or `conditional_nomination`. `next_owner` is the team that can146resolve the most severe blocker (`ap_team` for AP holds, `buyer` for missing147contracts, `quality_ops` for receipt issues, `program_owner` for budget).148149### 2. Receiving-Control Closeout150151Given a receipt batch ID:152153**Inspection summary**: Pull the receipt record to get `po_id`, `receipt_date`,154`warehouse_id`, `packing_slip`, `receiver`. Trace to PO for `supplier_id` and155`program_id`. Trace to supplier for `supplier_name`.156157**Line reconciliation** for each PO line referenced by the receipt:158- `ordered_qty` from PO line159- `received_qty` from receipt line (sum across all receipts for the same PO)160- `rejected_qty` from receipt line161- `billed_qty` from invoice line (sum across all invoices for the same PO)162- `short_qty_vs_po` = ordered_qty - received_qty163- `unreceived_billed_qty` = max(0, billed_qty - received_qty)164- `receipt_completion_ratio` = received_qty / ordered_qty (round to 4 decimals)165- `po_unit_price` from PO line166- `contract_unit_price` from the linked contract167- `invoice_unit_price` from the invoice line168- `contract_price_match` = true when contract_unit_price equals invoice_unit_price169170**Invoice review**: Check the invoice linked to the receipt batch:171- `exception_codes` derive from the data:172 - `INVOICE_QTY_EXCEEDS_RECEIPT` when billed_qty > received_qty173 - `PARTIAL_RECEIPT` when received_qty < ordered_qty174 - `SUPPLIER_WATCH_RISK` when supplier has open risk events or watch rating175 - `PRICE_MISMATCH` when contract and invoice unit prices differ176 - `DAMAGE_REJECTION` when rejected_qty > 0177178**Financials**:179- `received_goods_value` = received_qty * po_unit_price180- `unreceived_goods_value` = short_qty_vs_po * po_unit_price181- `invoice_subtotal`, `invoice_freight`, `invoice_tax`, `invoice_total` from182 invoice record183184**Decision logic**:185- `batch_disposition`:186 - `release_full_invoice` when receipt complete and no exceptions187 - `accept_partial_hold_variance` when quantity variances but no damage188 - `reject_batch` when rejected_qty > 0 (damage)189 - `manual_recount_required` when variance is unexplained190- `ap_action`:191 - `release_invoice` when no exceptions192 - `keep_invoice_on_hold` when exceptions exist193 - `void_invoice` for extreme cases194- `receiving_action`:195 - `record_shortage_follow_up` when short_qty_vs_po > 0196 - `no_receiving_action` when quantities match197 - `reject_all_units` when rejected_qty > 0198- `supplier_action`:199 - `request_credit_or_remaining_delivery` when short or unreceived-billed200 - `no_supplier_action` when no discrepancy201 - `supplier_debit_for_damage` when rejected_qty > 0202203### 3. AP Close Desk Reconciliation204205Given specific invoice IDs and a close date:206207**Invoice decisions** (one per invoice):208- Pull the invoice, its PO, all receipts for that PO, and any scheduled payments.209- `hold_decision`:210 - `RELEASE` when three-way match holds: qty_billed == qty_received, invoice211 status is `approved`, and no unresolved exceptions.212 - `HOLD` when qty_billed > qty_received, no receipt exists, or invoice is213 `on_hold`/`pending_receipt`.214- `quantity_billed` from invoice line215- `quantity_received` = sum of received qty from all receipts for the PO216- `quantity_variance` = quantity_billed - quantity_received217- `quantity_variance_pct` = (|quantity_variance| / ordered_qty) * 100, rounded218 to 1 decimal219- `scheduled_payment_amount` = sum of payment amounts for this invoice through220 the close period; 0.00 if none.221- `net_balance_impact` = invoice_total - scheduled_payment_amount222- `release_to_payment` = true when hold_decision is RELEASE223- `hold_code` = invoice's hold_code field, or null when releasing224- `reason_codes`:225 - `APPROVED_THREE_WAY_MATCH` when quantities match and invoice is approved226 - `QTY_VARIANCE` when quantity_variance > 0227 - `NO_RECEIPT` when quantity_received == 0228 - `SCHEDULED_PAYMENT_FOUND` when scheduled_payment_amount > 0229230**Vendor balances** (one per supplier):231- Group invoice decisions by supplier.232- `opening_balance` = 0.00 unless the task specifies otherwise.233- `invoice_total` = sum of invoice totals for this supplier in the slice234- `scheduled_payments` = sum of scheduled payment amounts235- `held_invoice_total` = sum of invoice totals for HOLD decisions236- `releasable_invoice_total` = sum of invoice totals for RELEASE decisions237- `close_balance` = opening_balance + invoice_total - scheduled_payments238- `balance_status`:239 - `FULLY_SCHEDULED` when close_balance == 0 and no held invoices240 - `OPEN_HELD` when held_invoice_total > 0241 - `OPEN_APPROVED` when close_balance > 0 but all invoices released242243**Program summary**: Group by program_id. `held_total` = sum of HOLD invoice244totals; `released_total` = sum of RELEASE invoice totals.245246**Queues**: `payment_hold_queue` = invoice_ids with HOLD decisions.247`payment_release_queue` = invoice_ids with RELEASE decisions.248249**total_close_balance**: Sum of all vendor close_balances.250251### 4. Change-Control Decision252253Given a change memo specifying contract, SKU, supplier, program, and254requested incremental quantity:255256**Contract check**:257- `noncancelled_subtotal`: Sum PO subtotals (qty * unit_price per line) for258 all POs under this contract, **excluding** `cancelled` POs.259- `headroom_before_change` = ceiling_amount - noncancelled_subtotal260- `requested_subtotal` = requested_quantity * contract unit_price261- `headroom_after_change` = headroom_before_change - requested_subtotal262- `ceiling_ok` = headroom_after_change >= 0263264**Program budget check**:265- From `/budget_snapshots` for the program: `budget_cap`, `committed_amount`.266- `remaining_budget` = budget_cap - committed_amount267- `requested_tax` = requested_subtotal * (tax_rate_percent / 100)268- `requested_total` = requested_subtotal + requested_tax269- `budget_after_change` = remaining_budget - requested_total270- `budget_ok` = budget_after_change >= 0271- `max_quantity_with_current_budget` = floor(remaining_budget / (unit_price *272 (1 + tax_rate / 100)))273274**Approval check**:275- Find the latest approval event for the source requisition, sorted by276 `event_date` descending.277- `approval_ok` = true when latest action is `approved`.278279**Supplier risk check**:280- Find open risk events for the supplier (status == `"open"`).281- `supplier_risk_ok` = true when no open severe events exist. Supplier on282 "watch" alone does not block; only an open event with severity `"severe"`283 makes `supplier_risk_ok` false.284285**Overall decision**:286- `release_amendment`: all checks pass287- `hold_for_budget`: only budget_ok is false288- `hold_for_approval`: only approval_ok is false289- `hold_for_supplier_risk`: only supplier_risk_ok is false290- `hold_for_budget_and_approval`: both budget_ok and approval_ok are false291- `reject_contract_mismatch`: ceiling_ok is false292293**required_actions**: Derived from failing checks. Include294`obtain_final_requisition_approval` when approval_ok is false,295`raise_budget_exception_or_reduce_quantity` when budget_ok is false,296`resolve_supplier_risk_hold` when supplier_risk_ok is false.297`none` when all pass.298299### 5. Receiving / AP Release File300301Given target PO, receipt, and invoice IDs plus a local chargeback register:302303**Release decisions** (one per invoice):304- Match each invoice to its PO, then find all receipts for that PO.305- `receipt_ids_in_scope`: receipts from the task's target receipt list.306- `excluded_same_po_receipt_ids`: receipts for same PO not in the target list.307- Check the local chargeback register:308 - `approved_chargeback_amount` = sum of basis_qty * unit_cost for chargebacks309 with status `approved` for this invoice.310 - `pending_chargeback_amount` = sum of basis_qty * unit_cost for chargebacks311 with status `pending_quality_review` for this invoice.312- `net_release_amount` = invoice_total - approved_chargeback_amount (when313 releasing); 0.00 otherwise.314315**Decision** per invoice:316- `release_net_after_approved_chargeback`: approved chargebacks exist, no317 pending ones. Primary reason: `approved_qty_chargeback` or318 `approved_ap_quantity_variance`.319- `hold_missing_receipt`: no receipt at all for the PO. Primary reason:320 `no_receipt_on_po`.321- `hold_pending_quality_chargeback`: pending chargebacks in quality review.322 Primary reason: `inspection_hold_pending_chargeback`.323324**Receiving exceptions** (one per receipt in scope, plus missing-receipt325pseudo-entries for POs with no receipts):326- `exception_codes` from chargeback register and receipt data:327 - `Inspection Hold` when chargeback is pending_quality_review328 - `Severe Unmatched Quantity` when variance is significant329 - `Underage Quantity` when received < ordered330 - `AP Quantity Variance` when billed != received331- `chargeback_status`: `approved`, `pending_quality_review`, or `not_applicable`332- `resolution_status`:333 - `net_release_ready` when approved chargeback exists, no pending334 - `hold_for_quality_review` when pending chargeback exists335 - `accepted_no_receiving_exception` when no chargeback and receipt is clean336 - `missing_receipt` when no receipt exists for the PO337338## Calculation Reference339340### Quantity formulas341342| Formula | Definition |343|---------|------------|344| `short_qty_vs_po` | ordered_qty - received_qty |345| `unreceived_billed_qty` | max(0, billed_qty - received_qty) |346| `quantity_variance` | quantity_billed - quantity_received |347| `quantity_variance_pct` | (abs(quantity_variance) / ordered_qty) * 100 |348| `receipt_completion_ratio` | received_qty / ordered_qty |349350### Dollar amount formulas (all rounded to cents)351352| Formula | Definition |353|---------|------------|354| `received_goods_value` | received_qty * po_unit_price |355| `unreceived_goods_value` | short_qty_vs_po * po_unit_price |356| `net_balance_impact` | invoice_total - scheduled_payment_amount |357| `close_balance` | opening_balance + invoice_total - scheduled_payments |358| `noncancelled_subtotal` | sum(qty * unit_price) for POs where status != "cancelled" |359| `headroom_before_change` | ceiling_amount - noncancelled_subtotal |360| `headroom_after_change` | headroom_before_change - requested_subtotal |361| `remaining_budget` | budget_cap - committed_amount |362| `requested_tax` | requested_subtotal * (tax_rate_percent / 100) |363| `requested_total` | requested_subtotal + requested_tax |364| `budget_after_change` | remaining_budget - requested_total |365| `max_quantity_with_current_budget` | floor(remaining_budget / (unit_price * (1 + tax_rate/100))) |366| `chargeback_amount` | basis_quantity * unit_cost |367| `net_release_amount` | invoice_total - approved_chargeback_amount (when releasing) |368369## Data Conventions370371- **USD rounding**: Every dollar amount rounded to exactly 2 decimal places372 using standard rounding (half-up).373- **List sorting**: When the template specifies "sorted ascending", sort ID374 strings lexicographically ascending, numbers numerically ascending. When the375 template says "set", treat as unordered; follow the template's declared sort.376- **Null vs missing**: Use `null` (JSON null) for absent fields, not empty377 strings. Use `[]` for empty lists, `0.00` for zero dollar amounts.378- **Dates**: Format as `YYYY-MM-DD` strings.379- **Enums**: Use exact enum strings from the answer template. Do not invent new380 values.381- **Boolean fields**: Use JSON `true` / `false`, not strings.382- **Reason codes and exception codes**: Sort alphabetically within each list.383384### Record status reference385386- **Invoice statuses**: `approved`, `on_hold`, `pending_receipt`, `paid`, `void`387- **Receipt statuses**: `accepted`, `pending_inspection`, `rejected`388- **PO statuses**: `open`, `partial_receipt`, `fully_received`, `cancelled`389- **Contract statuses**: `active`, `expired`, `cancelled`390- **Supplier risk ratings**: `clean`, `watch`, `flagged`, `blocked`391- **Vendor risk event severity**: `severe`, `moderate`, `watch`392- **Vendor risk event status**: `open`, `closed`, `monitoring`393394## Solving a New Task3953961. **Read the prompt** to understand the task type and which API endpoints are397 in play. Identify the `<TASK_ENV_BASE_URL>` placeholder.3982. **Read every payload file** in `input/payloads/`. These name the specific399 anchor IDs (programs, POs, receipts, invoices, suppliers, contracts, SKUs).4003. **Read the answer template** (`answer_template.json`) to know exactly what401 keys, types, enums, and sorting rules the output must follow.4024. **Query the API**: Start by fetching the endpoints most likely to contain403 the anchor IDs. Follow foreign keys to pull related records. Fetch404 supporting endpoints (suppliers, programs, budget snapshots, risk events)405 for context.4065. **Cross-reference**: Join records by `program_id`, `supplier_id`, `po_id`,407 `contract_id`, `sku` as needed.4086. **Apply the workflow rules** from this skill for the task type.4097. **Compute derived values** using the formulas above.4108. **Produce JSON** matching the template shape, with correct types, enum411 values, sorting, and rounding.4129. **Return only JSON** -- no markdown fences, no prose outside the object.413414## Common Pitfalls415416- **Cancelled POs**: Exclude POs with status `cancelled` when computing417 contract usage subtotals and budget commitments.418- **Multiple receipts per PO**: Sum receipt quantities across all receipts for419 a PO when computing received_qty, not just the one named in the task.420- **Multiple invoices per PO**: An invoice ID may appear in the task but other421 invoices for the same PO exist in the system. Only act on the target422 invoices unless the template requires broader context.423- **Duplicate receipt IDs**: When a PO has multiple receipts and the task424 targets only one invoice, receipts linked to other invoices on the same PO425 should appear in `excluded_same_po_receipt_ids`.426- **Supplier risk "watch" vs "severe"**: A supplier with risk_rating `watch`427 or `flagged` is contextual but not automatically blocking for all decisions.428 For nomination readiness, any open risk event adds `open_supplier_risk`.429 For change-control, only open events with severity `severe` block release.430- **Opening balance**: Unless the task specifies otherwise, treat the opening431 AP balance as 0.00 for the target suppliers within the task's slice.432- **Scheduled payments**: Only payments scheduled through the task's effective433 period reduce the close balance.434- **Tax and freight in change control**: Tax applies to the line subtotal only.435 Freight is excluded from contract ceiling exposure unless the change memo436 explicitly provides a freight amount.