Margin Analyzer

Status: MVP draft · Owner: JJ · Version: 1.1.0 Category: Finance & Ops · Phase: V2

Quick start

When an SMB owner asks "should I raise my prices?" or "are my margins okay?", this skill:

1. Identifies what to analyze — which products/services are in scope
2. Pulls cost data from QuickBooks (COGS, direct expenses)
3. Pulls revenue data from PayPal or Square (transaction history)
4. Computes unit economics — revenue, COGS, gross margin, margin % per item
5. Benchmarks against context — inflation, cost changes, industry norms if available
6. Builds pricing scenarios — shows what happens to revenue and margin at +5%, +10%, +15% price changes, using historical correlation where data allows
7. Presents the analysis — no price recommendation; the owner decides

The output equips the owner to make their own pricing call with real data behind it.

Workflow

Step 1: Pre-flight check

QuickBooks: Call company-info to verify the industry field is populated. If it's missing or "Unknown", ask: "I need your business category to pull relevant benchmarks. What industry are you in?" Then call quickbooks-profile-info-update.

PayPal: No pre-flight needed, but PayPal rate-limits on rapid calls — see reference/gotchas.md.

No connectors: Offer CSV upload as a fallback. The skill can work from exported transaction and expense data. The expected CSV schema is in reference/csv-schema.md.

Step 2: Clarify scope

Ask the owner two questions:

1. "Which products or services do you want to analyze?"

   • All of them, or a specific subset?
   • If they say "all," confirm the connector has enough data to be meaningful before pulling everything.

2. "What metric matters most to you?"

   • Gross margin (revenue minus direct costs)?
   • Net margin (after all expenses)?
   • Revenue per unit?
   • Their answer shapes how you present the output.

Step 3: Pull cost data (QuickBooks)

Fetch from QuickBooks using profit-loss-quickbooks-account:

• Date range: Last 12 months (or full history if less is available)
• Extract: Cost of goods sold by product/service line, direct expenses

If QuickBooks isn't connected, ask the owner for:

• A cost breakdown by product/service line (materials, labor, direct delivery costs per item)
• Any known cost changes in the last 6–12 months

If QuickBooks is connected but COGS = $0 across all periods, do not use $0 as the cost input. Surface this to the owner:

"QuickBooks shows no cost of goods sold recorded for this period. To compute meaningful margins, I need a cost breakdown by product or service line — not a single average for the whole business. For each item you want analyzed, what does it cost you to deliver it? Materials, direct labor, any direct expenses per item. Even rough figures work."

Flag this limitation in the Data Quality Notes section of the final output.

Step 4: Pull revenue data (PayPal / Square)

Fetch from list_transactions (PayPal) or make_api_request (Square):

• Date range: Match the cost data window (last 12 months)
• Extract: Transaction amount, item/service name, date, quantity if available

If you hit PayPal rate limits, pause 30 seconds and retry once. If still blocked, offer: "PayPal is temporarily rate-limited. Want to switch to Square or upload a CSV instead?"

If only one data source is available, note the limitation in the output.

Step 5: Compute unit economics

For each product/service in scope, calculate:

…