# LeadPilot — UX Architecture Decision Records (UX-ADR Master Index)

**Document Version:** 1.0.0 (Phase 3 UX Architecture Lock)  
**Status:** Approved & Formally Enforced  

---

## UX-ADR-001: Attention-First Command Dashboard

* **Status:** Accepted
* **Context:** Traditional CRM dashboards are vanity pages filled with complex forecast charts that provide zero immediate guidance on what to do today.
* **Decision:** Anchor the top of the LeadPilot Dashboard with the **"Attention Required" Action Strip (P0)**, prioritizing overdue responses and follow-ups above all analytics.
* **Consequences:** Reps immediately know what needs attention upon login; eliminates forgotten deals.

---

## UX-ADR-002: High-Density Lead Inbox with Slide-Over Triage Drawer

* **Status:** Accepted
* **Context:** Users hate opening 10 separate browser tabs to inspect inbound leads.
* **Decision:** Build a high-density tabular inbox with an instant Alpine.js slide-over drawer that displays lead summary and quick actions on row click.
* **Consequences:** 3x faster lead triage; preserves table scroll position and active filter state.

---

## UX-ADR-003: "No Lead Left Behind" Dedicated Hub

* **Status:** Accepted
* **Context:** Neglected leads need a focused clearing queue separate from general lead browsing.
* **Decision:** Introduce `/leads/needs-attention` as a dedicated signature screen featuring 1-click action triggers and an "Inbox Zero" milestone.
* **Consequences:** Creates a daily operational habit for sales reps and business owners.

---

## UX-ADR-004: AI as Explainable Decision-Support Card

* **Status:** Accepted
* **Context:** Black-box AI scores alienate users if the rationale is opaque or if AI attempts to take autonomous closing actions.
* **Decision:** Display AI scoring inside a clear **Intelligence Card** that explains *why* the lead is scored HOT (budget, urgency signals) and provides a recommended human action.
* **Consequences:** Builds trust in AI recommendations; keeps human reps in total control.

---

## UX-ADR-005: Follow-Up as a First-Class Top-Level Workflow

* **Status:** Accepted
* **Context:** In traditional CRMs, follow-ups are buried as secondary sub-tasks inside contact records.
* **Decision:** Elevate Follow-ups to the top-level navigation (`/follow-ups`) with dedicated tabs for `Today`, `Overdue`, `Upcoming`, and `Completed`.
* **Consequences:** Eliminates dropped follow-up balls; ensures high follow-up completion rates ($> 90\%$).

---

## UX-ADR-006: Simplified Linear 5-Stage Pipeline with Mandatory Loss Protocol

* **Status:** Accepted
* **Context:** Over-customized 15-stage pipelines get clogged with zombie deals that reps refuse to mark lost.
* **Decision:** Enforce a strict 5-stage progression (`New` $\to$ `Contacted` $\to$ `Qualified` $\to$ `Proposal` $\to$ `Won`) with a mandatory Lost Reason Modal when exiting.
* **Consequences:** Clean pipeline data; actionable insights into lost revenue causes.

---

## UX-ADR-007: 3-Step Onboarding with Interactive Demo Lead

* **Status:** Accepted
* **Context:** New users frequently abandon software if onboarding requires 20 minutes of complex configuration before seeing value.
* **Decision:** Implement a 3-step setup wizard ($< 3\text{ minutes}$) with a 1-click **"Load Interactive Demo Lead"** button to deliver the activation moment immediately.
* **Consequences:** Guarantees Time to First Value (TTFV) $< 5\text{ minutes}$.