# Data Model And Sync > Use before any list build, enrichment run, or CRM integration, or when the user says "what counts as an account", "our data model", "field mapping", "the sync is broken", "records are duplicating", "which system is the source of truth", "parent child accounts". Defines the object model, keys, field-level direction of truth, and sync rules. Writes workspace/data/object-model.md and a data dictionary. - Skill: `guerrilla2799/data-model-and-sync` (Agent Skill) - Install (CLI): `npx skillmds@latest add guerrilla2799/data-model-and-sync` - Raw SKILL.md: https://api.skillmd.com/api/skills/guerrilla2799/data-model-and-sync/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: guerrilla2799 (https://skillmd.com/u/guerrilla2799) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/guerrilla2799/data-model-and-sync --- # 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`. | Property | Why it matters | |---|---| | **Definition** | One sentence. If two people would fill it differently, it is not defined | | **Allowed values** | A picklist, a format, or a range. Free text fields become unusable within a quarter | | **Direction of truth** | Which system or which human wins on conflict. This is the field that prevents the overwrite disaster | | **Freshness window** | How long the value stays valid. A field with no window is never refreshed or always refreshed, both wrong | **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: → Objects: Direction: one-way / bidirectional (prefer one-way, always) Trigger: Field map: Conflict rule: Failure mode: Alerting: Owner: ``` **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