WFDASH-WEBAPP/docs/sops/quote-operator.md

Quote Operator — SOP

Owns: the full quote pipeline — inbound RFQ intake, item-level pricing (sprint or manual), approval submission, sending, and follow-up. The sprint queue is one part of the pricing piece; the operator owns the whole pipeline from "new quote" to "customer replied".

Tools: /quotes, /quotes/[id], /sprint, /quotes/approvals, /quotes/email-monitor, dashboard widgets.

Entry points (where a quote can come from):

• Inbound email (n8n ingests RFQ → quote lands in new)
• Walk-in (operator types "make me a quote for John" — no email)
• Template (re-using a previous quote as a scaffold)
• Sprint (item-level pricing queue — items from the above that need a price from you)

Handoffs:

• From Email Intake (n8n) → quote lands in new status.
• To Approver → when status flips to approval_pending.
• To Order Operator → when customer accepts (quote becomes an order).
• To Customer → outbound email + inbound reply tracking.

---

1. Daily / Weekly Checklist

Every working day (start of shift, 08:30 SAST)

• Open /quotes?tab=new — every quote that came in via email overnight must have an owner. Either claim it (you'll work it), or pass to a colleague. Quotes older than 1 working day in new are a process bug.
• Open /sprint — clear the "UNCLAIMED" filter. Look for items you can claim in your strongest categories first. (If the inbound-email intake has already pre-priced most items, the sprint queue may be small today — that's the goal.)
• Open /quotes/email-monitor — scan for any failed sends from the last 24h. If any, retry or escalate (see Decision Tree §3.5).
• Open /quotes?tab=claimed — pick up any of your items whose 30-min claim is about to expire.
• Open dashboard → "Follow-ups Due" — every quote you own with a follow_up_due date of today or earlier must get a follow-up action today (call, email, or set a new follow_up_due).

Every working day (end of shift, 17:00 SAST)

• Release any sprint items you can't finish — the 30-min claim expires automatically, but it's polite to leave a pricing_notes breadcrumb on what's been tried.
• Confirm every quote you sent today has moved out of sending — if any are stuck in sending for >5 min, see §3.5.
• Set follow_up_due for every quote you sent without a reply expected inside 5 working days. Default: today + 5 working days.

Every Monday morning

• Review your KPIs (see §4). Look for any that are trending down vs last week. Note them in #quote-ops with a one-line reason.
• Clear the /quotes/approvals queue if you have items there from Friday. Approvals older than 1 working day are a process bug — surface to the approver.

Every Friday afternoon

• Close out the week — every quote in claim by you with no activity for 3+ days must either be priced, sent, or problem-ed. Don't leave zombies for Monday.

---

2. Step-by-Step Procedures

The procedures are ordered by the quote lifecycle:

#	Procedure	Entry point
2.1	Process an inbound email quote	RFQ email arrives via n8n
2.2	Create a walk-in quote	Phone / face-to-face / WhatsApp
2.3	Create a quote from template	Repeat customer, similar items
2.4	Claim a sprint item	Unpriced item from §2.1, §2.2, or §2.3
2.5	Price a line item	Inside the line editor
2.6	Submit a quote for approval	Every line priced
2.7	Send the quote to the customer	Approver has approved
2.8	Follow up on a sent quote	follow_up_due reached
2.9	Partial approval / split a quote	Customer accepts some, rejects others

2.1 Process an inbound email quote

When: a customer sends an RFQ email. n8n ingests it, the AI extracts items, and a new quote appears in /quotes?tab=new with status new. You'll see a 📨 icon on the dashboard's "New Quotes" widget.

1. Open /quotes?tab=new. Find the new quote.
2. Sanity-check the AI extraction (open the quote detail):
   • Customer — did the AI match it to a known customer? If it landed on Unknown Sender, see Decision Tree §3.7.
   • Company — same check. Wrong company = wrong letterhead on the PDF.
   • Items — are the descriptions readable? Are the quantities right? If a line is missing or wrong, edit it.
   • Attachments — is the customer's original RFQ attached? The buyer needs to be able to compare our quote against their ask.
3. Check pricing_source on each line:
   • ai or catalogue → already priced. Verify the price against the AI's reasoning (if shown). If sane, move on.
   • manual or empty → unpriced. These lines will land in the sprint queue (see §2.4).
4. Claim the quote by clicking Claim on the header (or it'll auto-claim on first edit). Status flips to claimed.
5. Triage unpriced lines: if the sprint queue has unpriced lines from this quote, claim them in §2.4.
6. If everything is priced, jump to §2.6 (submit for approval).

Don't:

• Don't submit a quote with Unknown Sender — the customer needs to exist first (see §3.7).
• Don't edit the AI's prices without a pricing_notes breadcrumb explaining why.

2.2 Create a walk-in quote

When: a customer calls / walks in / WhatsApps with an RFQ that didn't come through email. No inbound message to extract from — you build the quote from scratch.

1. Open /quotes/new (or click "+ New Quote" on the quotes list).
2. Pick or create the customer in the customer picker.
   • If they exist, pick them. The letterhead, rep, and email template default from the customer record.
   • If they don't exist, type the name. The system creates a draft customer row with that name — the supervisor completes the rest of the fields later.
3. Pick the company (which letterhead). CNL vs ISHERWOOD etc — match what the customer is used to.
4. Set the validity (default 30 days).
5. Add the description — the free-text subject of the RFQ (e.g. "M16 hex bolts, grade 8.8, zinc, 2000 units"). Goes on the PDF header.
6. Add items in the line editor:
   • One row per SKU / spec combo the customer asked for.
   • Each row needs at minimum description. Add quantity and unit.
   • If you know the price (e.g. the customer named a SKU that is in the catalogue), set cost_price and markup — selling_price is auto-derived.
   • If you don't know the price, leave it blank and the lines will land in the sprint queue (§2.4).
7. Save. The quote lands in new status.
8. If items are unpriced, go to §2.4. If everything is priced, go to §2.6.

Don't:

• Don't pick a company / letterhead you don't recognise — ask the supervisor.
• Don't save with quantity = 0 — that's a placeholder, not an order. If the customer is uncertain about qty, write "TBD" in the description and price the line anyway, or mark the line as "Re-quote later" (split it out — §2.9).

2.3 Create a quote from a template

When: a customer asks for something we've quoted before with the same line items / similar scope. Re-using a template saves the line-item re-entry.

1. Open /quotes?tab=templates. Pick the template that matches.
2. Click Create from Template. A new quote is spawned with:
   • Same customer, company, letterhead.
   • Same line items (descriptions + quantities).
   • Status: new.
   • Prices reset (templates don't carry live pricing — you re-price from the current catalogue).
3. Update description to reflect the new RFQ (date, customer reference, anything that's changed since the template was made).
4. Update quantities if the customer wants different amounts.
5. Re-price the lines from the current catalogue (or leave them for sprint if the SKU / supplier has changed).
6. Continue from §2.6 (or §2.4 if items are unpriced).

Don't:

• Don't send a template quote without verifying the prices against today's catalogue. Supplier cost changes, and template-stored prices go stale fast.
• Don't re-use a template for a new customer without confirming the markup policy applies. Strategic accounts may have different markups.

2.4 Claim a sprint item

When: an item lands in the sprint queue and you have capacity.

1. Open /sprint. The "UNCLAIMED" tab shows available items.
2. Prefer items you can resolve in <30 min — known SKUs, items with attachments, or items in your strongest category.
3. Click Claim. The 30-min TTL starts. The item moves to your Claimed filter.
4. Within 30 min: price the item (see §2.5), or release by simply not saving (the claim auto-expires).

Don't:

• Don't claim more than 3 items at once. The 30-min TTL is per item; the bottleneck is your attention.
• Don't claim items you'll need a supplier call for. Sprint is for pricing from known data, not for sourcing.

2.5 Price a line item

When: you've claimed an item and you're at the line editor.

1. Read the description. If the AI provided a match (look for matched_price_list_id filled in), use it.
2. Decide pricing source:
   • Catalogue (pricing_source: "catalogue") — the matched catalogue row has a valid cost_price and markup. Use it.
   • AI (pricing_source: "ai") — the AI agent pre-filled a suggested price. Verify against the catalogue or supplier list before saving. Never save an AI price blind.
   • Manual (pricing_source: "manual") — no match. You need to find a price yourself (see §3.1).
3. Set cost_price and selling_price. Selling price is auto-derived from cost_price × (1 + markup/100) if you set the markup — pass selling_price explicitly only when the catalogue has a stored selling price you want to preserve.
4. Set pricing_source to the source you actually used.
5. Add a pricing_notes breadcrumb (e.g. "matched JEI catalogue row, ZAR excl VAT, 30% markup per August 2026 policy").
6. Click Save. The item drops off the sprint queue. The linked quote_item flips to user_edited: true.

Don't:

• Don't save with cost_price = 0 and selling_price = 0. That's a sign you didn't find a price — see §3.1.
• Don't override a catalogue price without a pricing_notes reason.

2.6 Send a quote for approval

When: every line on a quote has selling_price > 0.

1. Open the quote detail (/quotes/[id]).
2. Click Submit for Approval. The status flips to approval_pending. Idempotent — if it's already in approval_pending, nothing changes.
3. If the submit returns unpriced_items with offendingItemIds:
   • Open each offending line.
   • Either price it (see §2.5) or move it to a "Re-quote" group (see §2.9).
4. Wait for the approver. The quote is now in their queue at /quotes/approvals.

Don't:

• Don't bypass submit by calling Send Email directly. The pre-send validator will reject with invalid_status for new quotes.

2.7 Send the quote to the customer

When: the approver has flipped the quote to approved.

1. Open the quote detail.
2. Click Send Email. The email modal opens.
3. Verify the recipient(s):
   • To — the customer's primary email.
   • CC — usually the customer rep (rep on the customer row).
   • BCC — internal archive address (already pre-filled).
4. Edit subject/body if needed. Default subject is Quote {number} — {description}. Don't remove the quote number — the inbound reply tracker uses it.
5. Attachment picker: the quote PDF is auto-included. Add any supporting docs (datasheet, authorisation letter) the customer asked for.
6. Click Send. Status flips to sending → n8n takes over the SMTP send → callback records emailed or mail_failed.
7. Set follow_up_due to today + 5 working days.

Don't:

• Don't send without verifying the recipient. Wrong customer = lost quote.
• Don't include internal-only files. The customer sees everything in the attachment picker.

2.8 Follow up on a sent quote

When: a sent quote has a follow_up_due date of today or earlier.

1. Open the quote detail. Check the Reply chip — green if a reply is logged, red if not.
2. If no reply:
   • Phone first (faster than email). Log the call in quote.notes.
   • If no answer, send a follow-up email: keep it short, reference the original quote number, ask one direct question (e.g. "Are the JEI prices workable?").
   • Update follow_up_due to today + 5 working days.
3. If replied: open the reply in /quotes/email-monitor, read it, then either:
   • Customer accepted → hand off to the Order Operator (create an order from quote). Mark the quote approved if not already.
   • Customer wants changes → see §3.3.
   • Customer rejected → flip to rejected. Move on.

2.9 Partial approval / split a quote

When: a customer says "yes to lines 1, 2, 5; no to 3, 4".

1. Open the quote.
2. Click Partial Approve. For each line, mark approved or rejected. Add a note for each rejection.
3. Click Split Quote (in the action bar). A new quote is created with the rejected lines.
4. Re-price the new quote if needed (the prices inherit but sometimes a re-quote justifies a different markup).
5. Send the new quote following §2.7.

---

3. Decision Tree

3.1 I can't find a price for an item

Is the item in the catalogue (search /pricelist)?
├── Yes → use the catalogue row, set pricing_source="catalogue"
└── No
    ├── Is there a recent price_list upload from the supplier?
    │   ├── Yes → open /pricelist, find the upload, check if the
    │   │        item is in the extracted list (sometimes AI misses
    │   │        lines)
    │   └── No → call the supplier
    └── Supplier not reachable / no price available
        → Set the line to "Re-quote" group (separate it from the
          rest of the quote). Don't hold up the rest of the quote.
        → Or, if the customer is waiting urgently, price the item
          at your best guess with a high margin (40%+) and add a
          pricing_notes disclaimer.

3.2 The AI price looks wrong (too low / too high)

Is the catalogue price within 10% of the AI price?
├── Yes → accept the AI price, set pricing_source="ai"
└── No
    ├── Low (< catalogue - 10%) → reject, use catalogue price,
    │                              add pricing_notes "AI underpriced
    │                              by X%, used catalogue per policy"
    └── High (> catalogue + 10%) → reject, use catalogue price,
                                    escalate to approver if the
                                    customer has a standing
                                    discount you don't know about

3.3 Customer wants changes to a sent quote

Are the changes only pricing/markup?
├── Yes → re-price the affected lines, save, regenerate the PDF,
│         send a "Revised quote" email referencing the original
│         number.
└── No (changes to scope, qty, items)
    ├── Customer wants fewer lines → Partial Approve (§2.9) + Split
    ├── Customer wants more lines → Add the lines, re-price, send
    │                                as "Revised quote"
    └── Customer wants different items entirely → Clone the quote
                                                  as a new RFQ,
                                                  mark old as
                                                  `rejected`

3.4 The 30-min sprint claim is about to expire

Have you made progress (found a price, just not saved)?
├── Yes → save your work, even if partial. The claim can be re-claimed.
└── No
    ├── Item is too hard → release (just don't save). It returns
    │                       to the pool.
    └── Item needs supplier input → add to your "needs supplier"
                                    personal list, release the claim.

3.5 Email send failed

What's the failure reason (check n8n log)?
├── SMTP / network error
│   └── Click Retry on the quote. If it fails again, escalate to
│       IT. The quote stays in `mail_failed` until retried.
├── "Recipient rejected"
│   └── Check the email address. If typo, fix and resend. If
│       genuine reject (mailbox full, domain dead), phone the
│       customer for a new address.
├── "PDF render failed"
│   └── Escalate to the Order Operator / dev. Don't retry — the
│       PDF will fail again until the bug is fixed.
└── Unknown
    └── Capture the full n8n log. Escalate with the log attached.

3.6 Customer escalates (calls you directly to push for a discount)

Is the customer a strategic account (rep = senior staff)?
├── Yes → call the approver before quoting anything. Don't
│         promise a discount over the phone.
└── No
    ├── Discount < 5% → apply it. Log in pricing_notes with the
    │                    reason.
    ├── Discount 5-15% → apply it, but flag the approver in the
    │                     quote notes.
    └── Discount > 15% → don't apply. Tell the customer it's
                          above your authority, escalate to the
                          approver. Don't bluff.

3.7 An inbound email looks like a new RFQ but lands in Unknown Sender

Is the sender a known customer (search /customers)?
├── Yes → reassign the quote to the right customer via the
│         customer picker on the quote detail.
└── No
    ├── Is the sender domain one we recognise (e.g. a known
    │   customer at a new branch)?
    │   └── Yes → ask the supervisor to create the customer, then
    │             reassign.
    └── No → it's a real new customer. Hand to the supervisor to
             create the customer record. Don't price the quote
             until the customer exists — the foreign key chain
             breaks otherwise.

3.8 The AI extracted the quote wrong

What's wrong?
├── Wrong company / letterhead
│   └── Re-pick the company on the quote header. The PDF will
│       re-render with the right letterhead on the next send.
├── Wrong items (missing lines, extra lines, wrong description)
│   ├── Missing line → add it manually, price it.
│   ├── Extra line (AI hallucinated) → delete it. Log in
│   │                                  quote.notes: "removed
│   │                                  hallucinated line X".
│   └── Wrong description → edit the description. The SKU
│                            and matched_price_list_id may
│                            need re-linking.
├── Wrong quantities
│   └── Cross-check the original RFQ email attachment
│       (quote.attachments). If the customer typed qty=200
│       and the AI read qty=20, fix it. If the AI hallucinated
│       the qty, delete and re-add.
└── Wrong unit (each / pack / metre)
    └── Edit per line. Note: until PB adds the `unit` column
        (see `quote-items` AGENTS.md), this is stored in the
        description, not a structured field.

3.9 A walk-in customer has no account yet

Do you have a contact name and a way to follow up?
├── Yes (phone, email, name) → create the quote. The system
│   creates a draft customer with the name you typed; the
│   supervisor completes the address / VAT / contact fields
│   later. Don't block the quote on missing customer data.
└── No (anonymous, cash-on-delivery) → ask the supervisor
    before creating. We may need a different flow for
    cash customers (e.g. a "Cash" pseudo-customer).

---

4. KPIs

All KPIs are measured in working days (Mon–Fri, SAST). The dashboard's "Quote Pipeline" widget is the source of truth for most of these.

KPI	Target	How it's measured
Sprint claim → priced turnaround	< 30 min median	now - claim_expires_at for resolved items, where resolution = pricing_source set + user_edited: true
Quote first-touch turnaround	< 2 working days	now - created for quotes whose status has left new
Quote send turnaround (priced → emailed)	< 4 working hours after approval	emailed_at - approved_at
Follow-up rate	100% of overdue quotes actioned same day	count of quotes with follow_up_due <= today AND last_action < today (should be zero)
Approval rate	> 70% of approval_pending quotes approved within 1 working day	approved_at - submitted_at
Sprint abandonment rate	< 10% of claims released without save	released_claims / total_claims
Mail-failure rate	< 2% of sent emails	mail_failed / (mail_failed + emailed) over rolling 30 days
AI pricing override rate	< 15% of pricing_source="ai" lines changed before save	operator save of a different price on an AI-pre-priced line
Win rate	> 35% of emailed quotes become orders	orders.quote -> quotes.id join, over rolling 90 days
Quote value captured	tracked per rep, monthly	sum of selling_price on quotes in emailed/approved/complete status, attributed to claimed_by

How KPIs feed into your review

• Weekly (Monday standup): the supervisor pulls a one-pager showing each quote operator's KPIs. Red flags = items below target for 2+ weeks.
• Monthly (1st of month): the supervisor writes a 1-page review per operator covering the four KPIs they're weakest on and agreeing on a 30-day improvement action.
• Quarterly: above-target on all KPIs for 2 consecutive months = eligible for the markup-authority bump (you can approve your own quotes up to 10% discount without supervisor sign-off).

What the system does NOT measure (yet)

• Customer satisfaction (no NPS in WFDASH yet)
• Cross-sell effectiveness (no line-item upsell tracking)
• Catalogue coverage of your claims (you might be claiming a lot of items that the catalogue doesn't cover — that's a catalogue problem, not a you problem, but it's worth flagging)

If you think a KPI is unfair or misleading, raise it in #quote-ops. The supervisor can adjust targets, but the metric stays.