Data Model and Sync

Define what an account is before building anything that counts accounts. This is the first artifact in any engagement and the one most often skipped.

When to use

• Before the first list build
• Before connecting any enrichment or agent write access to a system of record
• When account-level reporting is incoherent
• After an acquisition, a merge, or a CRM migration

Inputs

• Needs from user: CRM object list and custom fields, a sample export of 200 account records, the list of systems that write to the CRM, and the intended segmentation
• Reads: workspace/audit/systems-audit.md if it exists

Workflow

1. Answer the four definitional questions

In writing, with a named decision maker. These are one-way doors and reversing them later means a migration.

What is an account? The buying entity. Options are legal entity, operating company, division or business unit, or domain. There is no universally right answer, and the right one depends on how you sell. If you sell to divisions independently, the division is the account and the parent is a relationship, not a record.

What is the account key? The field that makes a record unique. Normalized primary domain is usually the best available answer. Company name is never acceptable as a key.

How do parents and children relate? Explicit hierarchy field, or flat with a group label. Pick one. Reporting rolls up differently under each and the choice cannot be silently changed later.

What is a contact, and what does it belong to? Person-level, keyed on verified email, attached to exactly one account. A person at two accounts is two records.

2. Normalize before you do anything else

Domain normalization is the single highest-return hour in this whole repo.

Strip protocol, www, trailing slash, query strings
Lowercase
Resolve known redirects and rebrand domains
Map country TLDs to the primary domain where the entity is the same
Flag free-mail and generic domains as never-an-account
Flag known aggregators, resellers, and staffing firms for review

Then count collisions. Collisions are the duplicates that were invisible before normalization, and there are always more than expected.

3. Write the data dictionary

Every field that matters, with four properties. Fill in templates/data-dictionary-template.csv.

Direction of truth is the one people skip and the one that costs the most. A vendor refresh that overwrites a hand-verified contact silently degrades the best data you have. Decide per field: human wins, system wins, or newest wins.

4. Design the sync

For every pair of systems that exchange data:

SYNC: <system A> → <system B>
Objects:          <what moves>
Direction:        one-way / bidirectional  (prefer one-way, always)
Trigger:          <event or schedule>
Field map:        <field: field, with transforms>
Conflict rule:    <which side wins, per field>
Failure mode:     <what happens when it fails>
Alerting:         <error rate AND distribution anomaly>
Owner:            <name>

Prefer one-way. Bidirectional sync is two systems each believing they are authoritative, and the resolution logic is where records go to diverge quietly.

Alert on distribution, not only on errors. The dangerous failure is a sync that succeeds while writing the wrong value, usually a default. If a field's value distribution shifts more than 20% week over week, something upstream changed.

5. Write the suppression file

One place that lists what never gets touched: current customers where relevant, active open opportunities, do-not-contact requests, competitors, partners, investors, and your own domains.

Every list build and every agent reads this before acting. Without it, somebody will eventually prospect an open deal or a board member.

Output

• Writes: workspace/data/object-model.md, workspace/data/data-dictionary.csv, workspace/data/suppression.csv
• Uses: templates/object-model-template.md, templates/data-dictionary-template.csv
• Prints: the four definitions with decision maker, the collision count found by normalization, the sync map, and the suppression rules

Rules & quality bar

• Company name is never a key. Normalized domain, or a vendor ID, or nothing
• Normalize before counting anything. Every pre-normalization count is wrong
• Direction of truth per field. Not per system, per field
• One-way sync unless there is a specific reason. Then document the reason
• Suppression file exists before the first list build. Not after the first incident
• Named decision maker on all four definitions. An undecided definition gets re-litigated every month

Related skills

• Hands off to: data-hygiene for the cleanup, then tam-and-sourcing
• Feeds: every skill in the data plane, plus agent-guardrails for the conflict check
• See also: docs/architecture.md on seams