RevOps workflow design

Writes the revenue workflow from first touch to closed deal and renewal as one spec every team and the CRM admin can work from, or audits the running workflow against it from change history. It proposes files and a change list; nothing in the CRM changes.

When to use

Use this skill when:

• Lifecycle stages, MQL, SAL and SQL entry criteria, lead status or opportunity stages need defining.
• A handoff SLA or an MQL count is disputed between teams, or work stalls between marketing, sales and customer success.
• Lifecycle stage or owner keeps changing back, or records move backwards.
• Closed-won deals reach customer success without context, or renewals are missed.
• A routing tool, scoring model, enrichment source, billing sync or second CRM is about to write workflow fields.
• A CRM is handed over and nobody can say what each stage means or who sets it.

Use something else when (named skills apply only if installed):

• Who gets a request (distribution, territories, capacity, availability), one inbound queue that is slow or unassigned, or round robin that breaks: lead-routing-and-speed-to-lead. Both skills use the clock fields and compliance rule in references/clocks-and-slas.md; this skill owns those definitions for every handoff and audits them with S01 to S07. Until that skill is installed, the same file holds the minimum routing contract.
• Signal, enrichment and outbound workflows into the CRM (Clay, Apollo, sequencers): gtm-workflow-design. Score weights: lead-scoring-model. A sync overwriting values: martech-integration-engineering does the repair, crm-audit FLD-02 gives the evidence, and this skill says who may set lifecycle, stage or owner fields (references/field-ownership.md).
• A whole-CRM health check: crm-audit. Duplicates: crm-data-hygiene-audit. A new HubSpot portal: hubspot-implementation-plan first. PQLs and billing data: product-and-billing-data-in-crm. Journeys: journey-spec-and-qa.

Inputs

Read first if they exist: martech-context/stack.md (CRM and edition, connected tools, owners), metrics.md and data-dictionary.md (funnel, SLA and field definitions with writers), decisions.md and tracking-plan/ (the request events that start clocks).

Then gather:

• Mode, motions in scope (inbound, trial or product-qualified, outbound, partner, expansion, renewal), CRM and edition (the leads object, rotation and stage calculated properties depend on it).
• Current definitions with internal values: lifecycle options, lead statuses or lead stages, pipelines and stage IDs, customer state and renewal fields.
• Every writer of those fields: forms, workflows, routing, enrichment, reverse ETL, billing and product syncs, imports, users.
• A coverage calendar per team (IANA zone, hours, holidays), any response promise made to buyers, and a named owner per handoff, field and system.
• For an audit: read-only history of the workflow fields for the audit window plus the 90 days before it, request timestamps, and billing states if Customer depends on billing. Routes: references/reading-the-crm.md.

Ask for record IDs, values, timestamps and change sources. Contact names, emails, phone numbers and free text are removed before files are shared; keep the change source column, because user emails there become role labels through the source map. Never ask for, print or store credentials, tokens or keys.

Procedure

1. Choose the mode and scope

• Audit when the CRM holds at least 90 days of workflow records; otherwise design. A rescue is an audit, then a redesign of the deltas.
• One spec per CRM, one transition list per motion. Write the decision each handoff serves in one sentence, and cut any stage nobody acts on.

2. Separate the four state fields and fix the units

• Four questions, four fields: relationship (lifecycle stage), follow-up (lead status or a request record's stage), opportunity (deal stage per pipeline), customer state (billing or contract state, plus a renewal cycle record for negotiated or annual contracts). Recycled, disqualified, churned, trial and in-sequence never go in lifecycle.
• Name each transition's unit (person, request, account, opportunity, renewal cycle), and the roll-up rule wherever a funnel changes unit.
• A hand-raise is a request with its own ID and received time. Lifecycle counts first qualification only; count repeats on request records (HubSpot leads, Salesforce Leads, Attio list entries) or a ledger, one per buyer action.
• A custom lifecycle stage needs the five conditions in references/stage-model.md.

3. Write the transition table

• Per transition, deal stages included: from, to, evidence, field and value, one writer, entry timestamp, exits (advance, recycle, disqualify or lost) and correction path (assets/workflow-spec-template.md).
• Evidence is a committed fact (recorded acceptance, a deal with amount, close date and contacts, a paid invoice), never an email open, page view or booked meeting alone.
• MQL = fit gate AND (engagement threshold OR hand-raise). A hand-raise skips the score, never the exclusions (customer, open opportunity, partner, competitor, test, spam), each routed to a named path.
• Rejections and lost deals each take one of at most 12 reasons; if "other" exceeds 10%, fix the list. Recycle sets status, reason and recycle date; re-entry needs new evidence after that date; more than 2 entries into a stage in 90 days is a loop.
• Customer needs closed-won evidence or the paid invoice the spec names (invoice status paid, read from the invoice). Stripe active is not payment: send_invoice subscriptions start active with the first invoice unpaid, and ACH-type payments are active while processing.
• Backward moves go only through the correction path, with a reason. HubSpot imports, forms, the API, workflows and the Salesforce integration move lifecycle forward only (an earlier value needs clear, then set); Salesforce conversion cannot be undone. Mechanics: references/platform-mechanics.md.

4. Inventory writers and assign one owner per field

• List writers from configuration and from history sources. The observed list wins.
• One automated writer per field, per value where it matters (who may set Customer); others propose through a field or a task. Two automated writers without written precedence is a FAIL. Last write wins only when arrival order equals authority. State what a blank input means and how a real clear is sent.
• Traps: two-way HubSpot to Salesforce owner mapping; Salesforce REST writes run the active assignment rule unless they send Sforce-Auto-Assign: FALSE; a HubSpot rotation with overwrite on reassigns on every re-enrollment. Register: assets/field-ownership-register.csv; detail: references/field-ownership.md.

5. Place routing and define the clocks

• Route the request, not the person: relationship owners first (open opportunity, then account; a Salesforce Lead needs its account matched before assignment rules run), then eligibility, segment, distribution and a monitored fallback. Each outcome writes rule ID, reason, owner and assigned time.
• Clock fields: received_at (source system, not CRM creation), crm_seen_at, assigned_at (first person or staffed queue), last_assigned_at, first_response_at (a relevant human attempt, never an auto-reply, task change, alert or booking), disposition_at; meeting_booked_at and first_connected_at sit beside them. A request booked at submission is its own class.
• The buyer clock runs from received_at, never resets, and is the SLA. The owner clock runs from the current assignment: HubSpot's Lead response time report is one (it resets on reassignment and counts marking a task in progress), and the leads object's Time to First Touch starts at lead creation.
• Business minutes come from the owning team's calendar; report wall-clock minutes beside them. HubSpot's business-days delay counts whole days, so a minute timer needs a deadline datetime property and an "Until a date property" delay.

6. Write the SLA and handoff contracts

• Per handoff: trigger, packet, receiver obligation, start and stop fields, calendar, target, breach action, report (assets/sla-register.yaml, assets/handoff-packet-checklist.md).
• Baseline = median business minutes over every due request in the class for at least 8 full weeks, unanswered ones at their age, not-yet-due left out. First target = the baseline, or the buyer promise if tighter; a median target starts near 50% compliance, so the first S02 FAIL is expected. Under 30 due requests, use labelled proposals: hand-raise 15 business minutes (escalate at 60), MQL disposition 1 business day, closed won accepted in 2 business days, renewal owned 120 days before the decision date or 30 before the notice deadline, whichever is earlier. Tighten after two months at 90% or better; never use a published benchmark.
• Compliance = on time / (eligible - not yet due); unanswered requests stay in. Reassignment never restarts the buyer clock, and each breach routes to a named person.
• HubSpot documents required stage properties for manual creates and moves in the UI only, so a daily exception view guards the packet. Renewals and self-serve exceptions: references/handoffs-and-renewals.md.

7. Fix scoring's place in the workflow

• Exclusions and hand-raises sit outside the score. Fit and engagement stay separate, each input with a source, writer, window and freshness. Email opens are not evidence; unknown is not poor fit.
• A score may set MQL (with the fit gate) and queue priority, never an owner change, Customer or a backward move.

8. Define the report pack

• Each report states question, unit, cohort timestamp, numerator, denominator, exclusions, maturity window and owner. Minimum set, R01 to R10: conversion, velocity, SLA compliance, clock split, aging, reasons and loops, writer conflicts, pipeline by source, closed-won acceptance, renewal coverage.
• Count entries, not occupancy. Report a cohort only once mature. Sum amounts once per deal ID. Keep an unknown group. Every number reproduces from a record ID list. Definitions and SQL: references/report-pack.md.

9. Audit the running workflow

• Read history without write access: HubSpot Export property history with Include Source Information (UTC; 45 revisions per contact property, 20 elsewhere), hubspot objects history --type <object> --properties <property> --include-ui, Salesforce sobject-reads over history objects, or the warehouse copy. Build requests.csv with the per-CRM recipe in references/reading-the-crm.md.
• Work in a folder the user names, never the skill folder. Copy assets/workflow-config.json there and fill it from steps 2 to 6 (rank order, terminal values, gates, skips, dwell limits, value-level writers, correction prefixes, conversions, team calendars, one class per measurable SLA). Call the scripts by path:

S=path/to/revops-workflow-design
python3 "$S/scripts/normalize_history.py" wide --in lifecycle_history.csv --out transitions.csv \
  --object contacts --field lifecyclestage --id-column "Record ID" --group value,time,source \
  --source-map source-map.csv
python3 "$S/scripts/workflow_audit.py" transitions --config workflow-config.json \
  --transitions transitions.csv --as-of <export read time> --since <first day of audit window>
python3 "$S/scripts/workflow_audit.py" sla --config workflow-config.json \
  --requests requests.csv --as-of <export read time>

• Rules T01 to T10 and S01 to S07, config keys, thresholds and denominators: references/reading-the-crm.md. Exit 1 means at least one FAIL, 2 bad input. Without Python, apply the rules to a sample and label the audit "script not run".
• FAIL is a wrong owner, stage or customer state, a lost or unmeasured request, or a writer the register does not allow; WARN needs a decision. Every finding carries a count, a rate and an example ID, and each FAIL is confirmed on one record in the CRM before it is reported.
• Check what files cannot show: lifecycle automation and form settings, the workflow inventory (the CLI lists v4 flows only), stage calculated property toggles, assignment rules per creation path, calendars and Away status, Sensitive Data.

10. Propose the files and the change list

• Save as new files in the working folder: the spec, both registers, the report pack, the audit (assets/audit-report-template.md), the change list (assets/change-list-template.md) with the rehearsal plan in each request's Test field, and proposed martech-context/ additions. Only the CRM admin changes the CRM; martech-context/ waits for the user's approval.

11. Hand over the rehearsal

• Map each change request to cases in assets/acceptance-test-cases.csv (23 cases), with expected values from the spec and named test recipients.
• The CRM admin runs them after approval, in a sandbox or on flagged test records with the user's explicit approval and outbound limited to test recipients. Never submit forms, create, move or import records, or trigger workflows or syncs yourself; compare the recorded results with the expected values using reads only.

Common failure modes

• Lifecycle carries follow-up state, so MQLs double count (T02, T03, T10); two writers fight over one field (T05, T06, S05).
• The SLA runs on the owner clock, from CRM creation or over answered requests only (S02 to S07); Customer is set before payment (T04, T06). Catalogue: references/failure-modes.md.

Worked example

Acme Analytics, a fictional B2B SaaS on HubSpot Professional with Stripe billing, audits Q3 2026 inbound. From the skill folder (fixtures only):

python3 scripts/workflow_audit.py transitions --config assets/workflow-config.json \
  --transitions assets/example-acme-transitions.csv --as-of 2026-09-30T20:00:00Z
python3 scripts/workflow_audit.py sla --config assets/workflow-config.json \
  --requests assets/example-acme-requests.csv --as-of 2026-09-30T20:00:00Z

The runs end 11 FAIL, 7 WARN, 9 PASS and 5 FAIL, 4 WARN, 6 PASS: hand-raise compliance is 40.0% of 10 due while the owner clock shows 7 of 8 on time. Output, handling, change requests and a Salesforce fixture: references/worked-example.md. Redesigned spec: assets/example-acme-spec.md.

Acceptance checks

• Units: every motion names its unit and roll-up rule. Pass: no transition without a unit.
• State fields: lifecycle holds no follow-up, product or churn values. Pass: a reviewer answers "is this a customer", "is someone working this request", "how far is this deal" and "is the invoice paid" from one field each.
• Transitions: evidence, field and value, one writer, entry timestamp, exits and correction path for each, deal stages included. Pass: no placeholder and no activity-proxy evidence.
• Ownership: one automated writer per workflow field (per value where restricted). Pass: zero observed writers missing from the register or the findings.
• SLAs: start and stop fields, calendar, target, breach action and report per handoff. Pass: the buyer clock never resets, compliance keeps unanswered requests and separates not yet due, and each target names its baseline or says proposal.
• Report pack: unit, cohort timestamp, numerator, denominator, maturity window and owner per report. Pass: a reviewer recomputes one number from its record ID list.
• Audit, when run: command, config, files, row counts, calendars and as-of recorded; each FAIL has a count, a rate and an example ID confirmed in the CRM; outside checks done or listed with a reason. Pass: no finding without evidence.
• Change list: entity, current setting, change, risk, test, approver, rollback and what rollback does not undo. Pass: a CRM admin applies it without asking a question.
• Rehearsal plan: each change request names its cases and expected results; after the admin's run, the actual result and evidence per case. Pass: all match, every run outside a sandbox names its approval and no message reached a real person; or the check is marked pending with the admin named.
• Safety: no write to the CRM or any connected tool, and no credential or personal data in outputs. Pass: the tool log shows reads only and martech-context/ is unchanged without approval.

Boundaries

• Read-only, with no live side effects: the agent never changes stages, statuses, owners, workflows, assignment rules, scores, properties, pipelines or integrations, and never submits forms, creates test records, imports or moves deals. Every change leaves as a draft for human approval.
• Named owners approve definitions: marketing, sales and customer success leads per handoff, RevOps for the spec, finance for billing-derived state, the privacy owner for contact rules. Historical corrections go in the change list with the cohort, a before-export and an approver.
• Hand-offs, read-only first (routes in references/reading-the-crm.md):
  • HubSpot remote MCP server: allow only get_user_details, get_properties, search_properties, search_crm_objects, get_crm_objects, search_owners, query_crm_data and tool_guidance (call it before the first query), and deny every other tool. No history or workflow tool.
  • HubSpot Agent CLI reads: hubspot objects history (step 9), hubspot workflows list and get (v4 flows only). Approved record changes go through HubSpot's agent-cli-skills dry-run, digest and confirm flow.
  • Salesforce hosted sobject-reads server, turned on by an admin: getObjectSchema, soqlQuery, find, getUserInfo, listRecentSobjectRecords, getRelatedRecords. Never the mutations, deletes or all servers.
  • Attio MCP server: reads only; never the write attribute values endpoints, which replace an attribute's whole history.
  • Warehouse: a read-only role; Fivetran's sales-pipeline-analysis skill once definitions are agreed. Approved writes through any MCP server: agent-write-safety.

Live docs

Platform settings, limits and menu paths change. Before stating any parameter name, limit, quota or UI path:

• Fetch the current page from the vendor docs MCP server or llms.txt listed in sources.yaml, or open the canonical URL.
• If the live page disagrees with this skill, follow the live page and tell the user what changed.
• Cite the URL you used.

Most used: HubSpot lifecycle, leads, rotation, history and stage properties; Salesforce assignment and sobject-reads; Stripe statuses (dates in references/platform-mechanics.md).