# AI Data Quality Guardian

_AI Features_

Continuous monitoring of CRM data hygiene. Weekly Monday-3am report identifies duplicates, incomplete records, stale contacts, conflicting data, and invalid data — each with one-click fixes where possible. Mostly rule-based (low AI cost), with AI-prioritized recommendations on top.

## Steps
1. Sidebar > Tools > Insights > Data Quality. Top of the page shows the overall score gauge (0-100) with trend arrow vs the previous report.
2. Five category cards: Duplicates / Incomplete / Stale / Conflicting / Invalid. Each shows count + dominant severity. Click into any category for the issue list.
3. Each issue shows: description, affected record count, severity, "Fix" button (if a fix action is wired), or "View Affected" link.
4. Fix actions: merge (calls the existing merge engine), update_status (bulk email status / unsubscribe), archive (move to CHURNED), fill_field (set a default).
5. "Fix All" button per category — runs the action on every issue in that category. Confirmation modal first.
6. AI Recommendations section (one light-tier call per report): top 5 prioritized actions ranked by impact + effort. Each links to the relevant fix.
7. Score trend chart shows the last 6 weekly reports — useful for proving data hygiene improvements over time.
8. Worker fans out to every org with ≥10 contacts on Monday at 3:15am UTC.

## Tips
- Score formula: start at 100; deduct duplicates × 3, incomplete × 1, stale × 0.5, conflicting × 2, invalid × 2; clamp 0-100. Score drops of 10+ points trigger a notification to all admins.
- Most checks are rule-based (free) — duplicate fuzzy matching, email format validation, phone digit count, future-date detection. AI is only used for the recommendations summary at the end (one light-tier call per report).
- The merge engine respects manual merge history — if a contact was previously rejected as a duplicate, the report won't flag it again until something changes.
- Fixes are gated to ADMIN+ permissions because they mutate live data. Read-only access to the report is open to everyone.

## Example
A sales manager opens Data Quality on a Monday morning: score dropped from 78 to 64 over the weekend (notification already pinged her phone). Top recommendation: "Merge 23 duplicate contacts created by the weekend lead-import — high impact, low effort". She clicks "Fix All" on Duplicates. 23 merges in 2 minutes. Score back to 81. Without this report she'd have noticed in 4 weeks at the next QBR.

## Troubleshooting
- **Score is permanently in the 60s and won't budge** — You're probably importing data faster than you can clean it — every weekly report finds new duplicates / incompletes from the latest imports. Fix: Tighten the import flow: enable de-duplication on import, require minimum fields, validate email format before save. The Guardian is a backstop, not the first line of defense.
- **"Fix" button is grayed out on an issue** — The issue has fixAction="none" — it's informational (e.g., "5 contacts have no source") because the fix needs human judgment, not a one-click action. Fix: Click "View Affected" to see the records and decide manually. Or update them in bulk via the contacts page.

## Plans
Included in every plan. Weekly run is mostly free (rule-based) + one light-tier call for the recommendations summary. Toggleable per-org under Settings > AI Usage > AI Features (key: data_quality) — disabling stops the weekly worker.