past-sales-agent

name

past-sales-agent

description

Use to log a completed used-machinery sale and to generate monthly / quarterly performance reports. Logs every detail of a blind co-broker deal — seller, third-party dealer, buyer, equipment (brand/model/year/serial/type), dimensions & weight, rigger, trucker, haul type, origin/destination, sale price, costs, gross margin — into the shared Sales tab of the dealer's Google Sheet. On request, generates a branded monthly PDF report aggregating by equipment type, party, geography, margin, and rigger/trucker mix. Triggers on "log this sale", "log the Krauss-Maffei sale", "month-end report", "monthly sales report", "Q1 numbers", "how many machines did I move", "what was my margin last month", "who was my best rigger this quarter", or any retrospective question about the dealer's book. NOT for prospective sales drafting (that's sales-agent).

Past Sales Agent

The dealer's permanent record. Every completed deal gets logged with enough detail to reconstruct it months later — including the blind co-broker structure (who held it, who bought it, who was in the middle). Monthly reports aggregate the data into insights the dealer actually uses: best margins by equipment type, top riggers, freight cost trends, geographies that are hot.

When this fires

Logging

• "Log the Krauss-Maffei deal — sold to Midwest Molding, ABC was the seller, Bayshore rigged it"
• "Closed the Engel sale today, $52k, freight was $3,400"
• "Add to past sales: 2008 CX 160, blind, profit $8,200"

Reporting

• "Run the monthly report"
• "What did I sell in April?"
• "Show me Q1 numbers"
• "Which rigger ran the most loads last month?"
• "Best margin machine type this year?"
• "Generate the past-sales PDF for the board"

Setup

Uses the same Google Sheet as sales-agent. If .dealer_sales_sheet.json doesn't exist, point the dealer at sales-agent for bootstrap. Both skills read/write the same Sales tab.

Sales tab columns (full schema)

Column	Notes
sale_id	Auto: S-YYYYMMDD-####
sale_date	ISO date
seller	Holder of the machine — the originating party (e.g. "ABC Equipment Inc.")
third_party_dealer	The middle dealer if blind (the dealer running this skill, in most cases)
buyer	End buyer
blind_transaction	TRUE / FALSE — is this a blind co-broker deal?
equipment_brand	Krauss-Maffei, Engel, Haitian, Arburg, etc.
equipment_model	CX 160, Victory 200, Mars II, etc.
equipment_type	injection_molding, cnc, presses, extrusion, blow_molding, robots, heavy_general
year, serial
dimensions_lwh	e.g. 186" L × 64" W × 78" H
weight_lbs	Integer
rigger_company, rigger_id	rigger_id links to the rigging-agent database
trucker_company, trucker_contact
haul_type	step_deck / RGN / flatbed / van / lowboy / expedited / multiple
origin_city_state, destination_city_state
sale_price, cost_basis, rigging_cost, freight_cost	USD
gross_margin	Auto-computed as sale_price - cost_basis - rigging_cost - freight_cost if not provided
currency	Default USD
proposal_number	Cross-ref to the sales-proposal PDF if applicable
notes

Logging flow

1. Gather facts — ideally pull from the relevant sales-proposal PDF (if there's one with a matching proposal number) plus the dealer's verbal account. Confirm each detail before writing.
2. Validate — equipment_type must be enum, dimensions/weight should be numeric. Surface anything fuzzy and ask.
3. Compute margin — if gross_margin not provided, compute sale_price - cost_basis - rigging_cost - freight_cost. Surface it for sanity check before saving.
4. Link the rigger — if the rigger isn't already in the rigging-agent database, prompt to add them. If they are, set rigger_id and call rigging-agent's log_use() to update last-used-date and append history.
5. Write the row — scripts/log_sale.py appends to the Sales tab. Echo back the sale_id.

Reporting flow

scripts/monthly_report.py produces a branded PDF (matches the dark/gold aesthetic of the other dealer skills) covering:

• Header KPIs — # of sales, total revenue, total margin, average margin %, blind-deal % of book
• By equipment type — count, revenue, average margin per machine
• Top performers — best margin deal, fastest close, highest-revenue deal
• Logistics mix — top 3 riggers (count + total $), top 3 truckers, haul-type breakdown
• Geography heat — origin/destination state mix
• Trendline — vs. last month, vs. same month last year, YTD
• Parties — top 5 buyers, top 5 sellers (with blind-deal flag count)
• Watch list — anything margin-negative, anything over 90 days from sale-to-payment (if payment tracking is added later)

Output: /mnt/user-data/outputs/past_sales_<YYYY-MM>.pdf and a summary that goes in the conversation.

Quarterly and YTD reports use the same template with date-range parameter.

Anti-patterns

• ❌ Logging without confirming margin math — if the dealer says "margin was $8k" but the numbers don't add up, surface the discrepancy ("you said $8k but sale - cost - rig - frt = $7,150 — which is right?").
• ❌ Forgetting the blind_transaction flag — this is the whole point of the dealer's book. Default to TRUE if third_party_dealer is set.
• ❌ Skipping rigger_id linkage — losing the connection back to rigging-agent means the rigger's ratings/history degrade over time.
• ❌ Generating a report on a stale sheet — read fresh on every report run; don't cache.
• ❌ Reporting on a partial month without labeling it ("April so far" not "April final").

File map

• scripts/log_sale.py — append a sale row + update related rigger record
• scripts/monthly_report.py — generate the branded PDF + plain-text summary
• scripts/report_metrics.py — pure-function aggregations (so the report can be embedded in other skills if needed)
• references/report_template.md — what each section of the PDF looks like

Companion skills

• sales-agent — shares the same sheet (Customers + Leads + Outreach Log live there too)
• rigging-agent — sale logging calls log_use() to refresh the rigger's last-used info
• sales-proposal — links via proposal_number so you can jump from a sale row back to the executed PDF