Duplicate Detection

---
name: duplicate-detection
version: 1.0.0
deployment_target: plugin
status: PROPOSED
description: "Identifies duplicate accounts, contacts, and opportunities in HubSpot. Produces merge candidates with confidence scores (High/Medium/Low). Never merges autonomously — all merges require Write-tier human confirmation. Triggers: 'duplicates', 'merge candidates', 'duplicate accounts', 'duplicate contacts', 'clean up CRM duplicates'."
---

[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)

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

3. **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.

4. **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

| File | Purpose |
|------|---------|
| `references/reasoning-blueprint.md` | Problem classification taxonomy, domain heuristics, common failure modes, and expert judgment patterns for this skill |

## 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