Change order generator

Change Order Generator

Convert scope delta — new deliverables, extra revisions, rushed timelines, added channels, unplanned complexity — into documented, defensible, billable change orders with pricing options that respect the margin floor (6% minimum).

How This Skill Orchestrates

This skill sits at the end of the commercial pipeline. It consumes context from upstream skills:

1. scope-audit → identifies what's out of scope and what triggers the CO
2. fte-capacity-sizing → provides hour benchmarks, AI rates, and FTE cost data
3. margin-simulation → validates that the CO pricing maintains commercial viability

The engine (scripts/co_pricing_engine.py) calculates costs and pricing deterministically. Claude reads the upstream context, assembles the change items, frames the rationale, and generates the contract language from templates (references/co_language_templates.md). The Visualizer renders the CO summary as an actionable card.

No ML models are used here. This is a pricing problem, not a prediction problem: hours × rate × (1 + margin) = price. The 70/30 AI model is embedded — only the human portion of incremental hours drives cost.

Quick Reference

Resource	Purpose	Usage
scripts/co_pricing_engine.py	Pricing engine — takes change items, applies AI rates, calculates cost, generates economy/standard/premium pricing options with margin floor enforcement	python co_pricing_engine.py --input changes.json --rate 45 --client "AcmeAuto MX" --output co.json
references/co_language_templates.md	CO document template, scope delta patterns, pricing rationale language, approval workflow, client communication templates, upstream context integration guide	Read for contract language and client-facing communication

How to Use the Script

import sys
sys.path.insert(0, "<skill-path>/scripts")
from co_pricing_engine import ChangeOrderPricer

change_items = [
    {"description": "Weekly competitive analysis report", "change_type": "new_deliverable",
     "quantity": 4, "hours_per_unit": 6, "task_type": "competitive_monitoring",
     "discipline": "strategy", "seniority": "senior", "is_recurring": True},
    {"description": "2 extra revision rounds on creative", "change_type": "extra_revisions",
     "quantity": 2, "hours_per_unit": 3, "task_type": "creative_adaptation",
     "discipline": "creative", "seniority": "mid", "is_recurring": False},
]

pricer = ChangeOrderPricer(
    change_items=change_items,
    client_name="AcmeAuto MX",
    original_scope="12-month social + media retainer, $25K/mo",
)
result = pricer.calculate()
# result.pricing_options, result.recommended_price, result.change_items, etc.

Upstream integration: If fte-capacity-sizing or margin-simulation were run earlier in the conversation, use their outputs to inform the change items. The script's blended_rate parameter can be set from the capacity model's cost data. The margin simulation's current margin level determines which pricing tier is appropriate — if margin is already tight (< 15%), never offer economy tier.

Trigger Conditions

Activate this skill when:

• A client request has been classified as out-of-scope or requires-change-order by scope-audit or agency-request-intake-router
• The user identifies scope creep and wants to formalize it
• The user asks how to bill for extra work, new requests, or rushed timelines
• margin-simulation identifies leakage that needs contractual protection
• The user needs to generate CO language for a specific change

Change Order Process

Step 1 — Identify Original Scope

Establish the baseline — what was agreed. Sources:

• Direct from the user ("our SOW covers X")
• From scope-audit results (explicit deliverables list)
• From the conversation history (if previous skills captured it)

If the original scope isn't available, ask the user for the relevant section or note the assumption.

Step 2 — Define the Delta

For each change, classify it into one of these types:

Type	Risk multiplier	Description
New deliverable	1.0×	Something not in the SOW
Additional volume	1.0×	More units of existing deliverable
Accelerated timeline	1.25×	Faster than originally scoped
Extra revisions	1.0×	Beyond the revision cap
New channel / platform	1.10×	Adding a platform
New stakeholder	1.15×	Additional approver/reviewer
Data / tech dependency	1.20×	New integration or data requirement
Extra reporting	1.0×	More frequent or new reports
Scope expansion	1.10×	Broad expansion
Emergency / crisis	1.50×	Unplanned urgent work

Step 3 — Estimate Incremental Effort

For each change item, estimate:

• Gross hours: quantity × hours per unit (use benchmarks from fte-capacity-sizing/references/hour_benchmarks.md)
• Human hours: gross × (1 - AI rate) — only the human portion drives cost
• AI hours: gross × AI rate — covered by existing AI infrastructure

Apply the risk multiplier from Step 2 to the cost (not the hours).

Step 4 — Calculate Pricing Options

Run the pricing engine to generate three tiers:

Tier	Margin	When to use
Economy (6%)	Floor	Strategic accounts, relationship investment, client under pressure
Standard (25%)	Recommended	Normal operations, healthy relationship
Premium (40%)	Complex/rush	Rush timelines, high complexity, emergency requests

Margin floor rule: Never price below 6% margin. If the client pushes back, reduce scope — not margin.

Step 5 — Validate Against Current Margin

If margin-simulation was run earlier, check that the CO price maintains overall account viability:

• If account margin is already < 15%, do NOT offer economy tier
• If account margin is negative, the CO should be priced at premium tier (the agency is already losing money)
• Show the client the margin impact of each option

Step 6 — Generate CO Document

Use the template from references/co_language_templates.md to produce the formal change order. Claude fills the template; the human reviews and sends.

Step 7 — Determine Approval and Present Options

Based on price threshold, assign approval level. Present the CO with all three pricing options and a clear recommendation.

Output Format

Produce the change order in TWO forms: first as an inline visual artifact (rendered in chat via the Visualizer), then as a full CO document in markdown.

Visual Artifact (Primary)

Render the CO summary as an inline HTML widget using the Visualizer. The widget should display:

• A header bar with CO number, client name, and urgency badge (Normal = gray, Rush = amber, Emergency = red)
• A change items list — each item as a compact row with type badge, description, human hours, and cost
• A pricing options grid — 3 cards side-by-side (Economy / Standard / Premium) with price, margin %, and monthly cost if recurring. The recommended option should have an accent border (border: 2px solid var(--color-border-info))
• A totals row: total hours (human + AI split), total cost, recommended price
• An approval badge: who needs to sign off and estimated turnaround
• An action footer with sendPrompt() buttons:
  • "Run margin simulation with CO pricing applied for [client]" → validates the CO doesn't break the account
  • "Draft client email presenting change order CO-[number]" → generates client-facing communication
  • "Check team capacity to absorb this change" → routes to fte-capacity-sizing

Use CSS variables for light/dark mode.

Markdown CO Document (Secondary)

After the visual artifact, produce the full formal change order using the template from references/co_language_templates.md. This is the document the account lead will review, adjust, and send to the client.

When Information Is Incomplete

If the user provides only a partial description of the change:

• Estimate using benchmarks from the hour_benchmarks reference
• Mark estimated fields with ⚠️ Estimated — confirm with [team/data source]
• Generate the CO with available data and note what needs validation
• Never block the CO on missing information — produce a draft and iterate

Examples

Example 1 — Extra revisions:

User: "The client wants 3 more rounds of creative review on the campaign concept. Our SOW only includes 2 rounds."

→ 3 extra rounds × 5.6 hrs/round (creative_adaptation, 50% AI) × 1.0 risk = 8.4 human hours. Cost: $268. Standard price: $357. Approval: Account Lead (same day).

Example 2 — Rushed timeline with new channel:

User: "Client needs us to add TikTok to the social scope AND move the launch up by 2 weeks."

→ Two CO items: (1) New channel TikTok: setup 8h + monthly adaptation 6h/mo, 1.10× risk. (2) Timeline acceleration: 1.25× rush premium on all affected deliverables. Combined standard price: $2,800 one-time + $580/mo. Approval: Account Manager.

Example 3 — Emergency from scope-audit findings:

Conversation flow: scope-audit found "client requesting weekly competitive reports not in SOW" → routed to change-order-generator.

→ 4 reports/month × 6h × 80% AI rate = 4.8 human hrs/mo. Cost: $154/mo. Standard: $205/mo recurring. CO references scope-audit finding and includes contract language.

Skill Chaining

Direction	Skill	How it connects
Upstream	scope-audit	Provides CO triggers — findings that identified out-of-scope work
Upstream	fte-capacity-sizing	Provides hour benchmarks, AI rates, and current utilization
Upstream	margin-simulation	Provides current margin level to validate CO pricing tier
Downstream	margin-simulation	Re-run with CO pricing applied to verify account viability
Downstream	fte-capacity-sizing	Check if team has capacity to absorb the CO workload
Downstream	executive-growth-memo	Summarize the CO and its impact for leadership
Downstream	campaign-launch-qa	If CO is approved and involves campaign changes