# LeadPilot — Attention Center

**Document Version:** 1.0.0 (Phase 10)

---

## 1. Purpose

The Attention Center is the core operational intelligence of LeadPilot's No Lead Left Behind experience.

It collects leads that require immediate human action and presents them in priority order.

---

## 2. Categories

All category rules are **deterministic** — no AI, no machine learning, no probabilistic scoring.

### NEEDS_RESPONSE

**Rule:** `lead.first_contacted_at IS NULL AND status NOT IN ('won', 'lost', 'archived')`

A lead has arrived but no contact has been recorded. The business has not yet responded.

---

### FOLLOWUP_DUE

**Rule:** `follow_up.status = 'scheduled' AND due_at BETWEEN now()-24h AND end_of_day()`

A scheduled follow-up task has become due within the last 24 hours but is not yet overdue.

---

### OVERDUE

**Rule:** `follow_up.status = 'scheduled' AND due_at < now()-24h`

A scheduled follow-up has gone more than 24 hours past its due time.

---

### HOT

**Rule:** `lead.ai_score >= 75 AND status IN ('active', 'new') AND not already in another category`

A lead with a high AI qualification score requires prompt attention.

The hot score threshold (75) is a constant in `DashboardMetricsService::HOT_SCORE_THRESHOLD`. It does not change per-workspace in V1.

---

### AUTOMATION_FAILED

**Rule:** `follow_up.status = 'failed'`

An automated email follow-up failed after exhausting all retry attempts. Manual intervention is required.

---

### STALE

**Rule:** `lead.last_activity_at < now() - stale_lead_days AND status NOT IN ('won', 'lost', 'archived')`

A lead has had no qualifying activity for longer than the workspace-configured stale threshold.

The stale threshold is stored in `workspaces.stale_lead_days` (default: 7 days).

---

## 3. Priority Rules

Each attention item is assigned a deterministic priority level.

| Condition | Priority |
|-----------|----------|
| `AUTOMATION_FAILED` on hot lead (score ≥ 75) | `critical` |
| `OVERDUE` more than 48 hours | `critical` |
| `HOT`, `AUTOMATION_FAILED`, `OVERDUE` (general) | `high` |
| `NEEDS_RESPONSE` on hot lead | `high` |
| `NEEDS_RESPONSE`, `FOLLOWUP_DUE` | `medium` |
| `STALE` | `low` |

---

## 4. Sort Order

Attention items are sorted by:

1. Priority weight (critical=0, high=1, medium=2, low=3)
2. Due date ascending (most overdue first)
3. Lead score descending (highest value first)

---

## 5. Available Quick Actions

| Category | Actions |
|----------|---------|
| `NEEDS_RESPONSE` | Respond Now, Open Lead |
| `FOLLOWUP_DUE` | Send Follow-up, Open Lead |
| `OVERDUE` | Send Follow-up, Open Lead |
| `HOT` | Open Lead |
| `AUTOMATION_FAILED` | Open Lead |
| `STALE` | Open Lead |

---

## 6. Limits

- Maximum 50 items returned by default (configurable via API `?limit=N`)
- API maximum cap: 100 items
- Per-category sub-limits in the service prevent any single category flooding the list
- Items are deduplicated by a unique `id` composed of the source entity and category

---

## 7. Service Class

`App\Domains\Dashboard\Services\AttentionCenterService`

Key method: `getAttentionItems(int $limit = 50, int $staleDays = null): Collection`