Template: vendor follow-up

(needs modelrig 0.13.0 or newer) Grade a drafted follow-up to a vendor about a purchase order — an overdue delivery, a missing confirmation, an unanswered quote — before an employee sends it. This page is one of the use-case templates: a starting point, not a finished grader. The draft is usually one step of a process that wakes up each time the vendor answers or a reminder falls due, and an employee approves, edits or rejects it from your own dashboard — each verdict teaches the grader and, through the task's review gate, earns the draft less review over time. The machine-readable source is node_modules/modelrig/templates/vendor-followup.json (0.13.0 or newer).

Does this task fit?

Vendor follow-ups fit the shipped teach → calibrate → grade → optimize loop when four conditions hold. (1) Each draft is recorded under one task (for example po-followup-draft) — usually as a step of a process opened with rig.process each time the follow-up wakes up — and an employee approves, edits or rejects it from your own dashboard with rig.approval, which is what teaches the grader. (2) Your purchasing team can write down what a correct follow-up says and must never say (which facts it may quote, who may agree to new terms), which is the grading guide below. (3) The draft is grounded in data your code passes in — the PO number, line items, dates and amounts from your purchasing system — so the grader can check the facts against them. (4) Enough follow-ups go out that approvals add up: the review gate can only reduce review once the grader is calibrated against your employees. This template is a starting point for each of those, not a claim that vendor management is solved — fill in your own policies before you rely on it. Your code sends the email; ModelRig never does.

Starter schema

Replace every TODO with your own taxonomy; the enum slots ship without values on purpose, so an unfilled template refuses to look finished.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$comment": "STARTER SCHEMA for ONE drafted vendor follow-up. Replace every TODO with your own values before use. The template runs as-is: free-text fields validate immediately. TODO markers show where adding your own enum values tightens grading to your process; do not copy example words from the docs.",
  "title": "VendorFollowup",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "to_vendor_ref",
    "po_number",
    "subject",
    "body",
    "ask"
  ],
  "properties": {
    "to_vendor_ref": {
      "type": "string",
      "description": "Your own opaque reference for the vendor the draft is addressed to (the id in your purchasing system) — the grader checks it against the PO's vendor."
    },
    "po_number": {
      "type": "string",
      "description": "The purchase order the follow-up is about, exactly as your system writes it."
    },
    "subject": {
      "type": "string",
      "description": "The email subject line."
    },
    "body": {
      "type": "string",
      "description": "The email body as it would be sent."
    },
    "ask": {
      "type": "string",
      "description": "What the vendor is asked to do (confirm a date, send a corrected invoice, ship the balance). TODO(enum): constrain this to YOUR own ask types by adding an \"enum\": [ ... ] here. It runs as free text immediately.",
      "$comment": "TODO(enum): add your ask types as the enum for this field."
    },
    "needs_human": {
      "type": "boolean",
      "description": "True when the draft touches something an employee must decide (new prices, penalties, cancelling the order). Pairs with the no-commitments criterion in the grading guide."
    }
  }
}

Starter grading guide

The starter criteria run as written — sharpen each one in your team's own words as you grade. They are in the exact jsonb shape the set_task_settings write path validates — binary checks, each with a one-sentence pass and fail. There is no pass_threshold here: that lives in the route's grade: block.

correct_counterparty — Addressed to the right vendor about the right order

• Pass: the draft is addressed to the vendor on the purchase order and names that order, with no other vendor's name, contact or order in it.
• Fail: The draft names the wrong vendor or contact, mixes in another vendor's order, or would reach someone outside the order.

accurate_po_facts — Quotes the order's facts correctly

• Pass: every PO number, line item, quantity, date and amount in the draft matches the order data your code passed in, and nothing is invented.
• Fail: A number, date, item or amount in the draft differs from the order data, or the draft states a fact the data does not contain.

clear_ask — Makes one clear ask with a reply-by date

• Pass: the draft asks for one specific thing the vendor can do and says by when, so the vendor knows exactly how to answer.
• Fail: The draft is vague about what the vendor should do, asks for several unrelated things at once, or gives no date.

polite_firm_tone — Polite and firm

• Pass: the tone is courteous and professional and still makes plain that the order is overdue or incomplete, in the voice your purchasing team uses.
• Fail: The draft is rude, threatening or sarcastic, or so apologetic that the delay reads as acceptable.

no_commitments_beyond_policy — Promises nothing your policy does not allow

• Pass: the draft agrees to no new price, payment term, penalty waiver, cancellation or delivery change unless your written policy allows the sender to offer it.
• Fail: The draft offers or accepts a change in price, terms, penalties or scope that only an authorised employee may agree to.

The guide's escalation band starts at epsilon: 0.1: a grade within that distance of the route's pass threshold is treated as judge-uncertain and sent to a human. It is a starting band — tune it as your grader calibrates.

Golden checklist

Roughly twenty examples that cover:

• One ordinary follow-up per common reason — a late delivery, a missing order confirmation, an unanswered quote — done right.
• A draft that quotes a wrong quantity, date or amount from the order, so the guide learns to check facts against the data.
• A draft addressed to the wrong vendor contact, or one that mentions another vendor's order.
• A draft that quietly accepts a new price, a later date or waives a penalty — the golden sends it to a person.
• A second or third reminder on the same order, so the tone stays firm without becoming hostile.
• A vendor reply that changes the situation (partial shipment, cancelled line) and the follow-up that answers it correctly.
• Aim for roughly twenty goldens total, weighted toward the cases above rather than the easy first reminder.

Escalation starter

Start by keeping every draft in front of a person while the grader learns: set the task's review gate to always, or to earned so it only reduces review once the grader is calibrated against your employees' approvals. Send to a person regardless of the gate any draft that sets needs_human, any third reminder, and any order above an amount your team chooses. The machine-side band lives in starter_guide.escalation.epsilon: a grade within that distance of your task's pass threshold is treated as grader-uncertain and sent to the human queue. The 0.1 here is a starting band — widen it while you build trust, narrow it as your grader calibrates.

Apply it

By hand: record each draft under one task — tags: { step: "po-followup-draft" } on the call, inside rig.process — and write the starter criteria into that task's grading guide in your purchasing team's words. When an employee decides in your dashboard, record it with rig.approval({ task, subject, verdict, edited?, reviewer }). Ask rig.reviewDecision({ task, subjectKey }) before anything goes out; your code sends the email, ModelRig never does.

From a coding agent: scaffold_skill_receipts drafts this guide for a skill whose description mentions vendors and purchase orders; set_task_settings (the task-settings scope) applies it, and set_review_gate sets the policy. See Make a skill measurable.