Scope audit

Scope Audit

Systematically examine any agency scope document — RFP, SOW, brief, retainer, proposal, or informal client ask — to surface hidden work, missing assumptions, delivery risks, unpriced obligations, and change-order opportunities before the agency commits resources.

Quick Reference

Resource	Purpose	Usage
scripts/scope_audit_engine.py	Core audit engine — regex-based ambiguous language detection, missing item checks, implicit scope inference, risk scoring, verdict generation	python scope_audit_engine.py --input scope.txt --client "AcmeAuto MX" --output audit.json
references/risk_scoring.md	Risk scoring framework — severity scale, heat score formula, verdict matrix, industry benchmarks	Read when you need scoring definitions or to validate risk band thresholds
references/ambiguous_patterns.md	Comprehensive catalog of contractual red flags with regex patterns, examples, and safe replacement language	Read when you need to explain a specific pattern to the user or suggest contract rewording

How to Use the Script

When the user provides a scope document (pasted text, uploaded file, or excerpt), run the audit engine first to get quantitative results, then layer your qualitative analysis on top:

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

# text = content from uploaded file or pasted scope
auditor = ScopeAuditor(text, client_name="Client Name")
result = auditor.run_full_audit()

# Use result fields for the visual widget and markdown report:
# result.risk_score, result.risk_band, result.verdict
# result.ambiguous_phrases, result.missing_items, result.implicit_deliverables
# result.findings, result.change_order_triggers, result.risk_breakdown

The script handles Steps 2-4 and 6-7 programmatically. You still perform Step 1 (context extraction), Step 5 (dependency mapping), and the qualitative layer (interpreting results, adding domain judgment, recommending specific actions) yourself. The script's output is a starting point — always validate its findings against your understanding of the document and add findings the regex can't catch (e.g., pricing adequacy, team composition gaps, competitive dynamics).

Calibration note: The script uses regex pattern matching and tends to over-flag well-bounded SOWs (e.g., "Up to 2 rounds" may trigger asymmetric_commitment even though it's a cap). Always review the script's ambiguous phrase detections against the actual document context and dismiss false positives. The risk score should be treated as a ceiling — your qualitative assessment may lower it. For clean SOWs with minor script-flagged patterns, adjust the verdict accordingly.

Why This Exists

Agencies lose margin in the gaps between what's written and what's expected. A SOW says "monthly reporting" but the client expects weekly calls. A brief requests "social content" but doesn't specify rounds of revision or platform adaptation. A retainer covers "CRM support" but the client assumes a full loyalty program build. This skill reads the document the way a skeptical CFO would — looking for everything that could cost time, money, or goodwill that isn't explicitly priced or bounded.

Trigger Conditions

Activate this skill when:

• The user shares a scope document (SOW, RFP, brief, proposal, retainer, contract excerpt) for review
• The user asks whether something is priced correctly or missing from a scope
• The user wants to assess delivery risk on a commitment
• The agency-request-intake-router routes a request here because scope status was unclear, out-of-scope, or requires-change-order
• The user asks "what are we missing?" or "what could go wrong?" in the context of a client engagement
• The user pastes a client email or brief and wants to know the implications before responding

Input Requirements

The skill works best with a document or description that contains some combination of:

• Deliverables (explicit or implied)
• Timeline or milestones
• Pricing, fees, or retainer structure
• Team composition or FTE allocation
• SLAs, KPIs, or performance commitments
• Technology platforms or tools mentioned

If the user provides only a brief summary or partial information, proceed with what's available, flag gaps in the audit, and recommend the user provide the full document for a complete assessment.

Audit Process

Work through all seven steps. Each step builds on the previous one — do not skip steps or reorder.

Step 1 — Extract Explicit Scope

Read the document and list every deliverable, service, or obligation that is explicitly stated. For each item capture:

• What it is (deliverable name)
• Quantity or frequency if stated (e.g., "4 reports per month", "1 campaign per quarter")
• Any quality or format specifications
• Who owns it (agency vs. client vs. third party)

This is the baseline — everything the agency has explicitly agreed to do.

Step 2 — Infer Implicit Scope

This is where margin disappears. For every explicit deliverable, ask: "What work is required to produce this that isn't mentioned?" Common sources of implicit scope:

Explicit deliverable	Commonly hidden work
"Campaign concept"	Strategy brief, internal review rounds, client presentation, revision cycles
"Monthly report"	Data extraction, dashboard maintenance, insight narrative, client call prep
"Social content"	Platform-specific adaptation, copy variations, hashtag research, community management
"Email campaign"	Template design, list segmentation, A/B testing, deliverability QA
"Media plan"	Audience research, competitive analysis, platform setup, trafficking, optimization cycles
"CRM flows"	Journey mapping, data integration, template builds, QA across devices
"Website updates"	Staging, QA, browser testing, stakeholder review, deployment
"Brand guidelines"	Research, competitive audit, stakeholder interviews, revision rounds
"Analytics setup"	Tag plan, GTM configuration, QA validation, documentation
"Localization"	Translation management, cultural adaptation, local QA, regulatory review

List each inferred item and estimate effort range in hours where possible.

Step 3 — Identify Missing Items

Look for obligations that are absent from the scope but are typically required for the type of engagement. Common gaps:

• Project management: Status calls, timelines, resource coordination — rarely priced, always consumed
• Revision rounds: If not capped, assume unlimited client revisions
• QA and testing: Cross-browser, cross-device, accessibility compliance
• Reporting cadence: If "reporting" is mentioned without frequency, it becomes whatever the client expects
• Stakeholder management: Multiple approvers create hidden meeting and revision loops
• Data and privacy: GDPR/LFPDPPP compliance, consent management, data handling procedures
• Training and documentation: Handoff docs, client training sessions, runbooks
• Transition / offboarding: Knowledge transfer at contract end

Step 4 — Detect Ambiguous Language

Scan the document for language patterns that create scope exposure. These phrases are risk signals because they allow the client to expand expectations without a formal change order:

Pattern	Risk	Example
"As needed" / "on demand"	Unlimited volume	"Ad hoc reporting as needed"
"Support" / "assist" / "help with"	Undefined effort	"Support the client's digital transformation"
"Including but not limited to"	Open-ended list	"Services including but not limited to strategy, creative, media..."
"Reasonable" / "best efforts"	Subjective standard	"Reasonable response times"
"Ongoing" / "continuous"	No end date	"Ongoing optimization of campaigns"
"Up to" without a floor	Asymmetric commitment	"Up to 4 campaigns per quarter" (client expects 4, agency priced for 2)
"Strategic" as an adjective	Inflates expectations	"Strategic creative direction" vs. "creative production"
"Partnership" / "collaboration"	Blurs accountability	"A collaborative approach to content development"
"Optimization" without KPIs	Goalpost shifting	"Continuous optimization of ad performance"
"Innovation" / "thought leadership"	Unbounded effort	"Quarterly innovation sessions with senior team"
No revision cap	Infinite rework	Any deliverable without "up to N rounds of revision"
No approval SLA	Client-side delays	Deliverables dependent on client approval without timelines

Flag each instance with the exact quote, its location in the document, and the risk it creates.

Step 5 — Map Dependencies and Obligations

Identify everything the agency needs from the client or third parties to deliver:

Client dependencies:

• Asset delivery (logos, brand guidelines, product images, copy inputs)
• Access and credentials (ad accounts, CMS, CRM, analytics platforms)
• Approvals and feedback (who approves, how many stakeholders, SLA for turnaround)
• Data feeds (product catalogs, pricing, inventory, CRM extracts)
• Legal and compliance review (regulated industries: pharma, finance, alcohol, tobacco)

Third-party dependencies:

• Platform vendors (MarTech, AdTech, CRM)
• Media partners (publishers, networks, influencers)
• External production (photography, video, print)
• Technology integrations (APIs, data pipelines, SSO)

For each dependency, note whether the SOW includes a reciprocal SLA from the client. If not, this is a risk — the agency is on the hook for deadlines even when the client creates the delay.

Step 6 — Risk Classification

Evaluate every finding from Steps 1-5 against these risk dimensions. Assign a severity (Low / Medium / High / Critical) to each:

Dimension	What to assess
Financial	Underpricing, unpriced work, margin erosion, scope creep without CO mechanism
Operational	Capacity strain, skill gaps, tool/platform dependencies, unrealistic timelines
Legal / Contractual	Liability clauses, IP ownership gaps, penalty clauses, termination terms, data compliance
Client management	Expectation misalignment, stakeholder complexity, relationship risk, escalation history
Data / Technology	Integration complexity, platform access, data quality assumptions, migration risk
Timeline	Hard deadlines with no buffer, seasonal pressures, dependency chains with no slack

Produce a risk heat score — count of findings by severity:

• Critical findings: each scores 4 points
• High findings: each scores 3 points
• Medium findings: each scores 2 points
• Low findings: each scores 1 point

Sum the total. This gives a single risk score for the engagement:

• 0-5: Green — proceed with minor notes
• 6-12: Yellow — proceed with documented mitigations
• 13-20: Orange — renegotiate before committing
• 21+: Red — reject or fundamentally restructure

Step 7 — Recommendation

Based on the full audit, issue one of four verdicts:

Verdict	Meaning	Action
Approve	Scope is clean, risk is manageable, pricing is adequate	Proceed; document minor notes for account lead
Approve with conditions	Scope is acceptable but specific gaps need closing	List conditions that must be met before execution begins
Renegotiate	Material risks or unpriced work exist	Produce a change-order recommendation with specific line items and pricing
Reject	Risk is unacceptable relative to revenue, or scope is fundamentally unbounded	Explain why and recommend alternative structure if possible

Output Format

Produce the audit in TWO forms: first as an inline visual artifact (rendered in chat via the Visualizer), then as a structured markdown report below it for copy-paste, archival, and downstream consumption.

Visual Artifact (Primary)

Render the scope audit as an inline HTML widget using the Visualizer. The widget should display:

• A header bar color-coded by the overall risk heat score: green (0-5), amber/yellow (6-12), orange (13-20), red (21+)
• The verdict badge (Approve / Approve with conditions / Renegotiate / Reject) prominently in the header
• A risk heat score as a large metric (e.g., "14 / Orange")
• A 4-card metric grid showing: explicit deliverables count, hidden scope items found, change-order triggers, client dependencies flagged
• A risk breakdown bar — horizontal stacked bar showing count of Critical / High / Medium / Low findings, color-coded (red / orange / amber / green)
• A top 3 findings section — the three highest-severity findings with brief descriptions
• A change-order triggers list — each trigger as a compact row with estimated hours and billable flag
• An action footer with sendPrompt() buttons:
  • "Generate change order for [client] — [summary]" → routes to change-order-generator
  • "Run margin simulation for [client] with scope adjustments" → routes to margin-simulation
  • "Check FTE capacity for [deliverables]" → routes to fte-capacity-sizing

Use CSS variables for light/dark mode theming. Keep the widget compact — it should feel like a risk assessment card, not a multi-page report.

Markdown Report (Secondary)

After the visual artifact, produce the full structured audit as markdown:

## 🔍 SCOPE AUDIT — [Client / Project Name]

### Executive summary
[2-3 sentences: verdict, risk score, most critical finding, key recommendation]

### Scope included
[Numbered list of explicit deliverables extracted from the document]

### Scope not included (but expected)
[Items the document does NOT cover that are typically required for this type of engagement]

### Hidden scope
[Implicit work inferred from Step 2 — the deliverables behind the deliverables]

### Missing assumptions
[Assumptions the document relies on but does not state — things that could break if untrue]

### Ambiguous language
[Table: exact quote | location | risk created | recommended fix]

### Client dependencies
[What the agency needs from the client to deliver, and whether reciprocal SLAs exist]

### Risk matrix
[Table: finding | dimension | severity | mitigation]

### Risk heat score
[Score calculation: N critical × 4 + N high × 3 + N medium × 2 + N low × 1 = total → color band]

### Change-order triggers
[Each trigger: description | estimated hours | estimated cost | priority]

### CEO recommendation
[Verdict + rationale + specific conditions or next steps]

When Information Is Incomplete

If the user provides a partial document or verbal summary:

• Audit what's available with the same rigor
• Mark sections where insufficient information prevents assessment with ⚠️ Insufficient data — [what's needed]
• Explicitly recommend providing the full document for a complete audit
• Do not fill gaps with optimistic assumptions — if something isn't stated, flag it as a risk, not a non-issue

Examples

Example 1 — Clean retainer:

User shares a 12-month retainer SOW for social content management with clear deliverable counts, revision caps, monthly reporting, and defined team allocation.

→ Verdict: Approve · Risk score: 4 (Green) · Minor notes: no client approval SLA, recommend adding 3-business-day turnaround clause.

Example 2 — Dangerous RFP:

User pastes an RFP that says "end-to-end digital transformation including but not limited to CRM, media, creative, analytics, and innovation" with a fixed annual fee.

→ Verdict: Reject · Risk score: 28 (Red) · "Including but not limited to" makes scope unlimited. No revision caps, no deliverable counts, no exclusions list. Every service line is exposed. Recommend responding with a phased approach and explicit exclusions.

Example 3 — Scope creep in progress:

User says: "The client keeps asking for weekly strategy calls and competitive reports. Our SOW only covers monthly reporting. Is this in scope?"

→ Verdict: Renegotiate · Risk score: 14 (Orange) · Two change-order triggers: weekly calls (~4 hrs/week × rate) and competitive reports (~8 hrs/report). Route to change-order-generator.

Skill Chaining

This skill frequently routes to:

Condition	Next skill
Change-order triggers found	change-order-generator
Capacity concerns raised	fte-capacity-sizing
Margin risk identified	margin-simulation
Request needs leadership escalation	executive-growth-memo
Approved and ready for execution	campaign-launch-qa (if campaign) or direct execution