cpq-builder

What this skill does

# CPQ Builder Skill

## What This Skill Does

This skill defines patterns for building **Configure-Price-Quote**-shaped tools — systems where users configure inputs, the system applies rules to calculate results, and the output is a formatted deliverable that may require review/approval.

CPQ is NOT limited to product pricing. The same structural pattern covers:

| Domain | "Configure" | "Calculate" | "Output" |
|---|---|---|---|
| **Equipment sales** | Select product, pick options | Apply markup, calculate totals | Sales quote PDF |
| **Legal calculators** | Enter case details (income, duration) | Apply guideline formulas | Summary report with estimates |
| **Insurance estimators** | Enter coverage details | Apply rate tables | Premium estimate document |
| **Loan qualification** | Enter financial details | Apply lending criteria | Qualification letter |
| **Benefits eligibility** | Enter personal details | Apply eligibility rules | Benefits summary |
| **Service proposals** | Select services, set scope | Apply labor rates | Service proposal |

The builder reads this skill, reads the DOMAIN.md for the specific domain terminology and rules, and generates a working prototype. The DOMAIN.md determines whether the tool is about crane quotes or divorce calculations; this skill provides the structural pattern that fits.

**The patterns in this skill are defaults, not mandates.** When the actual workflow deviates from the canonical CPQ shape — has fewer stages, has a different layout, produces a different output — adapt the patterns. Each major section names the deviations explicitly.

---

## Customer Context

Customware's CPQ customers span many domains: industrial equipment dealers, custom apparel and signage shops, food/beverage wholesalers, professional services firms (legal, consulting, design), IT and managed service providers, construction and trades businesses, manufacturers, distributors. The CPQ pattern fits all of them.

**Examples in this skill rotate across multiple domains** — industrial equipment, services, consumer goods, software, custom goods. This is deliberate. The patterns are domain-agnostic; the examples illustrate by analogy. When applying this skill, ignore the specific domain in any given example and pull out the structural pattern. Your DOMAIN.md determines the specific vocabulary, products, rules, and roles for the build.

A "single girder crane requires a motor" rule has the same shape as "custom hoodie requires a printing method" or "managed service contract requires a tier" or "dog treat order requires a packaging size." The rule is "parent product requires child component selection." Build that pattern; let DOMAIN.md fill in the words.

### The customer profile

Customware's CPQ customers are typically **SMB businesses (5-50 employees)** going through growing pains. They are NOT migrating from another CPQ system. They are migrating from:

- Excel spreadsheets that have grown unwieldy (multiple tabs, copy-paste errors, broken formulas)
- Word document quote templates that get manually edited per customer
- Email-based approval workflows where the boss approves a quote in a reply-all thread
- Tribal knowledge about which products require which accessories, which lives in the senior rep's head
- Hand-keyed pricing where margin gets eroded through inconsistent discounting

The prototype's job is to feel **dramatically better than spreadsheets** without feeling **enterprise-overcomplicated**. A small team that's been quoting in Excel for 5 years should look at the prototype and immediately think "this is so much faster" — not "this looks complicated."

This positioning shapes every design decision in this skill:

- Inline line editing IS the comparison point. Excel users expect a grid they can edit directly.
- Live totals matter. Customers have been doing math in formulas; they expect to see numbers update as they change inputs.
- Role gating is impressive. Customers have never had "only the owner can approve over $50K" enforced by software — it was a verbal rule that got broken.
- Branded PDF output is impressive. Customers have been hand-formatting Word docs.
- Customer-facing portals, AI suggestions, e-signature integrations are NOT impressive at this stage. They're enterprise complexity that solves problems the customer doesn't have yet.

Build for the customer who's tired of broken Excel formulas, not the customer migrating from Salesforce.

---

## Is This Even CPQ?

Before applying any pattern in this skill, confirm the workflow is actually CPQ-shaped. The CPQ pattern fits when ALL FOUR of these hold:

1. **The user collects structured inputs** that determine the outcome (configuration choices, customer details, requirements, financial data, case details).
2. **Business rules or calculation logic transforms those inputs** into a deliverable (markup formulas, guideline calculations, rate tables, eligibility rules).
3. **A review or approval gate exists** between input and finalization, OR the deliverable goes through some kind of stakeholder review (preparer/reviewer pattern).
4. **The work product feels like it gets handed off** — to a customer, an internal stakeholder, a regulatory body, a downstream system.

If criterion 1 is missing → it's a dashboard or display tool, not CPQ. Bail.
If criterion 2 is missing → it's a data entry form, not CPQ. Bail.
If criterion 3 is missing → it's "intake-and-deliver" — apply CPQ patterns but skip the Approve section.
If criterion 4 is missing → it's a personal calculator/utility, not CPQ. Bail.

**Common false positives:**
- A "stock quote viewer" — has the word "quote" but is a display tool (criterion 1 missing)
- A "tax calculator" with no review step — utility, not CPQ (criterion 3 + 4 missing)
- A "product catalog" with prices — display, not CPQ (criterion 2 + 3 missing)
- A "feedback form" — data entry, not CPQ (criterion 2 missing)

If the four criteria don't hold, do not force-fit the patterns below. Build from the task description and DOMAIN.md using frontend-design's principles instead.

---

## Domain Type

Most CPQ-shaped workflows fall into one of two domain types. Identify which type the build is before applying patterns:

**Product domain.** The user configures sellable products/services. Pricing is the central calculation. Output is a quote document with line items, totals, tax, and terms. Examples: equipment sales, custom apparel orders, food/CPG wholesale, service proposals (consulting bids, managed services), software licensing, custom packaging.

**Calculator/intake domain.** The user enters case/applicant details. Calculation applies guidelines/rules/rate tables. Output is a summary report with inputs, calculated values, and disclaimers. Examples: spousal support calculators (Clarity Legal), insurance estimators, loan qualification, benefits eligibility.

The skill's patterns adapt to both. When a section or rule is domain-specific, this skill says so explicitly.

---

## Minimum Standards

Every CPQ build MUST meet Tier 1 standards. Tier 2 standards are built when DOMAIN.md signals the need. Tier 3 capabilities are mentioned in the completion summary as future work but not built in the prototype.

### Tier 1 — Non-negotiable (every CPQ build)

These are the capabilities that make the prototype feel dramatically better than Excel + Word. If any are missing, the build is incomplete regardless of how clean the UI looks.

**1. Direct inline line-item editing.** A spreadsheet-style table where users add rows, edit any cell, and see totals update live. NOT a "Configure form → Add to Quote → Build Quote table → Edit" round trip. The line items table IS the workspace. See "Section Pattern" below for the canonical implementation.

**2. Bundle / required-child products with appropriate configurator pattern.** When a parent product requires a child component (e.g., "industrial unit requires a motor selection," "custom hoodie requires a printing method," "managed service c