t0ddc3by/claude-for-customer-success/duplicate-detection

[PROPOSED]

Duplicate Detection

Merge candidates with confidence scores. High-confidence duplicates batch- presented for bulk approval. No autonomous merges — ever.

Reference: Governance tiers → ../../../shared/revops-domain-model.md §9 Config reads: crm_system

Pre-flight

Read ~/.claude/plugins/config/claude-for-customer-success/rev-ops/CLAUDE.md and ~/.claude/plugins/config/claude-for-customer-success/company-profile.md.

If either is missing or contains [PLACEHOLDER] markers, stop and prompt for /rev-ops:cold-start-interview.

Note from config: crm_system

G-code dependency: All G-code guardrails referenced in this skill (G1–G9) are defined in the CLAUDE.md config loaded above. If Pre-flight halts or config is missing, G-codes are undefined — do not proceed with partial config.

Use when

• CRM contacts, companies, or deals need duplicate scanning before a data import or merge
• Duplicate records are suspected to be inflating pipeline or distorting metrics
• Data hygiene sprint includes deduplication as a required step

Do NOT use for

• Full CRM hygiene audit (use crm-hygiene-audit)
• Field completion monitoring (use field-completion-monitoring)
• Merging records autonomously (outputs are proposals — G9 applies)

Typical Activation

"Find duplicates", "duplicate detection", "deduplicate the CRM", "flag duplicate contacts/companies", "duplicate scan before import"

Reasoning Protocol

Before generating output, apply these primers:

1. CLASSIFY: What type of duplicate detection request is this?

• Single object scan (accounts, contacts, or opportunities — merge candidates for one object type)
• Multi-object sweep (full CRM across all three object types)
• Pre-import deduplication (scan before data load — flag conflicts before they enter CRM)
• Merge candidate review (user reviewing previously surfaced candidates — confirm or dismiss)

1. CONSTRAINTS: What limits the solution space?
2. Confirm activation — user requesting duplicate detection or merge candidates
3. Check HubSpot connector — read access to accounts, contacts, opportunities required; declare fallback if absent
4. Confirm object scope before pulling data: accounts / contacts / opportunities / all
5. Apply G6 — data-as-of on all HubSpot reads
6. Apply G9 — no autonomous merges; all merge actions require explicit Write-tier human confirmation
7. Present High-confidence candidates in batch approval format; Medium and Low require individual review

1. EXPERT CHECK: What would a veteran RevOps data hygiene analyst verify first?

• Is the matching signal quality sufficient for the confidence tier assigned? A single

name-similarity match without corroborating signals should never reach High confidence — over-confident scoring causes legitimate record merges.

• Is data freshness confirmed before scoring? Stale connector reads may miss recent

record updates that resolve apparent duplicates — declare data age before presenting candidates.

• Are High-confidence candidates reviewed for merge risk before batch approval? Even

High-confidence pairs can carry legitimate differences (e.g., separate subsidiaries with similar names) — surface any anomalies before queuing for bulk merge.

• Is the object scope confirmed before running? A full multi-object sweep on a large CRM

may return partial data — scope the scan and declare any data limits upfront.

1. ANTI-PATTERNS: Common mistakes to avoid:

• Merging records autonomously without Write-tier human confirmation (G9 violation)
• Surfacing HubSpot reads without data-as-of timestamp (G6 violation)
• Assigning High confidence based on a single matching signal without corroboration
• Running a multi-object sweep without declaring scope and data volume limits

After execution, verify:

• G6 data-as-of label applied to all HubSpot reads
• G9 Write-tier qualifier present: all merges require explicit human confirmation before execution
• Confidence tier (High/Medium/Low) correctly assigned per matching signal count and quality
• Confidence: High when HubSpot is connected and data is current; Moderate when data is stale or connector is unavailable
• Confidence: [High] when HubSpot is connected and data is current / [Medium] when data is stale or connector is unavailable / [Low] if all inputs are manual or unverified

Matching Criteria

Accounts:

• Domain match (company email domain)
• Company name similarity >85% (fuzzy match)
• Same billing address

Contacts:

• Email address match (exact)
• First + last name + company match
• LinkedIn URL match (if field populated)

Opportunities:

• Same account + same product + close date within 30 days + ACV within 20%

Confidence Scoring

• High — 2+ matching signals, no conflicting signals
• Medium — 1 strong signal, some field differences that may be legitimate
• Low — Partial match; requires human judgment before any action

Output

DUPLICATE DETECTION — [Object type] — [Date]
[HubSpot ✓ live — as of YYYY-MM-DD] [Confidence: High]
 
HIGH confidence merge candidates ([N] pairs):
  [Company A] ←→ [Company A Inc]  Signals: domain match + name match
  [Contact X] ←→ [Contact X]      Signals: email match + LinkedIn match
  → Batch approval: confirm to queue all High for merge
 
MEDIUM confidence ([N] pairs):
  [Company B] ←→ [Company B Ltd]  Signals: name match | Diff: billing address
  → Review individually before merging
 
LOW confidence ([N] pairs):
  [Contact Y] ←→ [Contact Z]      Signal: name similarity only
  → Human judgment required
 
[Write-tier: All merges require human confirmation before execution]
[No autonomous merges will be performed]

Reference Files

Security & Permissions

Network access: None direct — all external data access is mediated by host-provided MCP connector tools (HubSpot, CS platform, Slack, Linear). This skill makes no direct outbound HTTP calls. Filesystem scope: None — this skill does not read or write local files. All data is provided at runtime via parameters or MCP connector responses. Subprocess execution: None. Dynamic code execution: None — pseudocode in this skill represents the logic contract and is not executed at runtime. Data sensitivity: Inputs may contain confidential customer, deal, and operational data. Handle with RevOps-level confidentiality.

Trust & Verification

Input trust model: All user-provided parameters are treated as untrusted at intake. Numeric inputs are validated for plausible range before use in calculations. String inputs are not evaluated as code. Output trust model: All outputs are proposals or analytical inputs — no outputs constitute approved decisions, revenue commitments, or system actions without explicit human confirmation. Connector data: Data retrieved via MCP connectors is treated as read-only observed state. Timestamps and data-as-of labels are applied to all connector-sourced values per G6. Write-tier confirmation: Any proposed write to HubSpot, Linear, or Slack is surfaced as a draft requiring explicit user confirmation before execution.

Guardrails

• G9: No autonomous merges — always proposals
• G6: Data-as-of required