bulk-data-hygiene

Bulk Data Hygiene

Audits a CRM board for data gaps, lets the user pick which gaps to fix, then runs a bounded write loop to fix them. The "do" sibling to board-diagnosis's "report." Designed for the recurring "my CRM is messy" pain — Sidekick's #1 negative-sentiment JTBD.

Flow: Trigger → Audit → User picks gaps → Plan writes → Execute (bounded, idempotent) → Summary.

Input

• Optional: board name/ID via argument.
• Optional: pre-declared mode (Default / Silent / Proactive).

Output

• α (default): Bounded write loop on the chosen board. Normalizes phone/country/email; can also batch-set owner / source / last-touch / stage when the user explicitly picks those gap types and signals are clean. A Hygiene fix — <Mon DD> doc lists every change with Generated by Claude footer + <!-- claude-skill-id: bulk-data-hygiene -->.
• β (opt-in): A "before/after" snapshot doc (preserves the prior state for ~30 days, in case a pass over-corrected).
• Proactive extension: Out of scope — bulk-data-hygiene is already a write skill; proactive doesn't change its behavior. Default mode + batched confirm is the only write surface.

Knowledge

• Gap taxonomy + audit rules (§ Step 3).
• Normalization recipes (§ Step 5).
• Shared artifact conventions (§ Shared patterns).

Tools (MCP)

• get_user_context, list_workspaces, search, get_board_info, get_column_type_info, get_board_items_page, board_insights — Gather.
• change_item_column_values — the core write. Loop with bounded concurrency.
• create_doc / create_update — publish summary + before/after snapshot.
• all_monday_api — escape hatch for column types not exposed by change_item_column_values (e.g., bulk write of country columns).

Cross-skill handoffs

• From board-diagnosis: the diagnosis report ends with "run /monday-crm:bulk-data-hygiene to fix" — this skill is the natural handoff target.
• From morning-briefing: if morning brief flags >N hygiene issues, suggest this skill.
• To morning-briefing / forecast-dashboard: clean data feeds them — point user there once hygiene is done.

Step 0: Connector check

Goal: Fail fast if the user has no monday MCP connection — no partial writes, no guessing.

1. Try mcp__monday__get_user_context.
2. If the tool is missing, returns an auth-style error, or the user has no accessible workspace: print "I don't see the monday connector active on this session. Install it from https://monday.com/mcp, then run this skill again." and stop.
3. If it works, cache user.id + user.name for artifact metadata.

Step 1: Detect mode

• Default — confirm before each batch (not each item) of writes.
• Silent — skip batch confirms; still publishes the summary doc.
• Proactive — same as Default for this skill (proactive doesn't make sense — every write is intentional). If user pre-declared Proactive, treat it as Default and note in chat.

Hard safety rail regardless of mode: no deletes, no amount-column writes, no cross-workspace moves, no normalization on columns the user didn't pick. Stage / owner / source / last-touch edits ARE allowed when the user explicitly selected that gap type at Step 4 — bulk-data-hygiene is the canonical place for board-wide column rewrites that other skills point users at.

Step 2: Resolve board

Goal: Land on a single boardId before reading any data.

1. If the user passed a board via argument: numeric → use as boardId directly; string → mcp__monday__search with searchType: "BOARD". One match → use it; multiple → AskUserQuestion.
2. If no argument: get_user_context → scan relevantBoards + favorites for names matching deals|opportunities|pipeline|leads|sales|contacts|accounts. One candidate → use it; multiple → AskUserQuestion; zero → list_workspaces → search. Still zero → stop with "I don't see a CRM-shaped board in your workspaces. Tell me the board name or ID, or run /monday-crm:workspace-builder to create one."

Step 3: Audit — surface the gaps (Gather + Synthesize)

Goal: Compute a gap report grouped by fix-type, with a concrete count per type.

Pull all items via get_board_items_page (paginated up to 5000, then sample with disclosure). For each item, check:

Resolve columns by type, not English name (same rule as morning-briefing). Skip gap types where the matching column doesn't exist.

Produce the audit summary in chat:

## Audit — <board name>

**Items scanned:** N
**Gaps found:**
- ✅ Fixable (column normalization): <N> phone formats · <N> mixed-case emails · <N> missing country codes · <N> guessable missing emails
- ✅ Fixable (bulk-set within picked scope): <N> missing owners · <N> stale last-touch · <N> missing sources · <N> stage drift
- ⚠️ Flag-only: <N> missing phones (no source) · <N> missing amounts (forecast integrity rail)

Pick which fixable gaps to run, or "all". Flag-only items list in the summary doc — no writes.

Step 4: User picks (Synthesize)

AskUserQuestion, multiSelect:

• "Phone formats (N items)"
• "Mixed-case emails (N items)"
• "Country codes from phone/email (N items)"
• "Guess missing emails from company domain (N items) — heuristic, may miss"
• "Bulk-assign owner (N items) — requires picking a scope (group / status filter) and a target owner"
• "Backfill stale last-touch (N items) — will only fill empty or older-than-90d cells; never overwrites recent dates"
• "Bulk-set source (N items) — requires picking a scope and a source value"
• "Normalize stage drift (N items) — requires picking a scope and target stage"
• "All column-normalization fixes" (the first four — bulk-set ones still need their per-fix scope picker)

For each bulk-set option, after Step 4 selection, run a scope picker sub-prompt: "Which group / status filter should this apply to? Pick a target value.". Never bulk-set across the entire board without scoping.

If user picks "Guess missing emails", surface a strong warning: "Email guessing uses <first>.<last>@<companydomain> heuristic. ~60% accuracy in our testing. Recommend running only on a Leads board where invalid sends are tolerable, not a Customers board. Continue?"

Hard rule: no fix runs without an explicit Step 4 selection (and a scope-picker confirm for bulk-set options). Empty selection → stop with summary-only.

Step 5: Plan + execute (Publish)

Goal: Bounded, idempotent loop. Every write is undoable.

For each picked gap type, build a write plan: list of (itemId, columnId, oldValue, newValue, reason).

Normalization recipes

• Phone format → E.164:
  • Strip non-digit/+ characters.
  • If no leading + AND country column is populated → prepend dial code per country.
  • If no leading + AND country empty AND phone starts with a known country prefix (e.g., 1 for US, 44 for UK) → prepend +.
  • Edge case: phone is too short (<7 digits) or too long (>15 digits) → skip with reason "unparseable".
• Email lowercase: value.toLowerCase(). Only write if changed.
• Country code from phone: parse leading dial code → ISO-2 country code → write to country column.
• Country code from email CCTLD: if email ends in .uk / .de / .fr etc. and country empty → infer.
• Email guess: for items with name + company-domain present, try <firstname>.<lastname>@<domain> lowercase. Add a Source = guessed status flag on the item so the user can filter and verify later. If a source/status column is missing, prompt the user once to add one — never write the email without a verifiability flag.
• Bulk-set owner / source / stage: within the user-confirmed scope (group / status filter from Step 4 sub-prompt), apply the chosen target value via change_item_column_values. Never extend beyond the picked scope.
• Backfill stale last-touch: set to today's date only on items where last-touch is (a) empty, or (b) older than 90 days AND user explicitly picked the "stale last-touch" gap type. Never overwrite a more-recent date.

Bounded execution

1. Cap total writes at 500 per run. Above that, prompt: " writes planned, capped at 500 per run. Run first 500 now and re-trigger for the rest, or narrow your selection?"
2. Execute via change_item_column_values, batched by item (one call per item updates multiple columns at once). Concurrency: 5 in flight max to avoid rate limits.
3. Confirm before write (Default mode) — single batched plan:
   • "Plan: phone normalizations · email lowercase · country fills · owner assignments (scope: ) · source backfills (scope: ) · stale-last-touch fills · stage drift fixes (scope: → ). Proceed? (yes / show 3 examples per fix-type / no)."
4. After each batch of 50 writes, print progress: Updated 50/500. Continuing....

# Hygiene fix — <board name> · <Mon DD>

<!-- claude-skill-id: bulk-data-hygiene -->

## Writes executed (<N>)
| Item | Column | Old → New | Scope / reason |
|---|---|---|---|
| ... | ... | ... | ... |

## Skipped (<N>)
| Item | Column | Reason |
|---|---|---|

## Flag-only (no writes)
- N items missing phone (no source — manual entry required)
- N items missing amount (forecast integrity rail — review manually)

## Undo
Every write here is reversible. The "Old" column above shows the prior value. To revert, copy the rows you want undone into a follow-up run with `--undo` (coming in v0.2; for v0.1, restore manually using the Old values).

---
Generated by Claude · <ISO timestamp>