ims/docs/superpowers/specs/2026-07-11-phase-3-ai-dashboard-design.md

Phase 3 — AI Features & Dashboard Upgrade

Date: 2026-07-11 Status: Approved

---

Scope

Phase 3 adds AI-assisted capabilities via the Claude API and upgrades all role dashboards from placeholders to functional views. Similar-incident retrieval (pgvector) is deferred to Phase 4.

Deliverables:

1. Upgraded dashboards for all 5 roles
2. Report quality check (AI)
3. Severity/category suggestion at triage (AI)
4. RCA/CAPA drafting assistant (AI)

---

1. Dashboard Upgrades

Approach

Replace placeholder home pages for each role with data-driven dashboards scoped to what that role needs to act on. All dashboards are server-rendered (Next.js App Router, force-dynamic). Site/zone heatmap is a plain HTML table with Tailwind bg-opacity intensity — no canvas library.

Role Dashboards

HSE Officer — /hse/dashboard (upgrade existing)

• Leading vs lagging split: near_miss + hazard = leading indicators; injury + lti = lagging
• Site/zone heatmap: incident count per site × zone, color-coded by intensity
• CAPA on-time completion rate: (verified CAPAs where completed_at <= due_date) / total verified * 100
• Top 3 incident categories by count (current month)
• Top 3 root causes from investigations.root_cause_summary (simple text frequency, no NLP)
• DOSH-reportable filing status: counts of dosh_reports rows by status (not_required / pending / submitted)
• CSV export endpoint: GET /api/dashboard/export?role=hse — all incidents with key fields

Management — /management (upgrade placeholder)

• This month vs last month incident count (delta + arrow)
• LTI count (incidents where medical_status = 'lti')
• Severity distribution bar (count per severity 1-5)
• Leading/lagging split (same calc as HSE)
• CAPA overdue count (status = 'overdue')
• Site comparison table: incident count per site, sorted descending
• CSV export: GET /api/dashboard/export?role=management

Supervisor — /supervisor (upgrade placeholder)

• Scoped to user.site_id — only their site's data
• Open incidents count + list (status != closed), linked to incident detail
• CAPA status summary for their site: open / in_progress / overdue counts
• Overdue CAPAs: list with owner name + due date

CAPA Owner — /capa-owner (upgrade placeholder)

• Scoped to capa_actions.owner_user_id = current_user
• My open CAPAs: list with incident ref, description, due date, status
• Overdue count highlighted in red
• No export needed

Reporter — /reporter (upgrade placeholder)

• Scoped to incidents.reported_by = current_user
• My submissions: list with reference_no, date, type, current status
• Status shown as colored badge (reported / triaged / investigating / capa_pending / verification / closed)
• No export needed

---

2. AI Features

Architecture

• All Claude API calls: server-side only, /app/api/... routes
• Model: claude-sonnet-4-6
• API key: ANTHROPIC_API_KEY env var (never client-side)
• Every AI suggestion logged to audit_log with: table=ai_suggestion, action=suggested, old_value=null, new_value=JSON of suggestion, changed_by=current user

2a. Report Quality Check

Trigger: Incident report form submit — before DB write, client POSTs to quality-check route first.

API route: POST /api/incidents/quality-check

Request payload:

{
  "description": "string",
  "incident_type": "injury | near_miss | ...",
  "injury_involved": true,
  "evidence_count": 0
}

Claude prompt strategy: Send incident fields; ask Claude to return a JSON array of short warning strings covering: vague description (< 20 words), injury with no photo, no location detail, missing witness info for serious incidents.

Response:

{ "warnings": ["Description too vague — add what happened and where", "Injury reported but no photo attached"] }

UI: If warnings exist, show yellow warning panel above the submit button listing each warning. "Submit anyway" button still present — user is never blocked, only informed.

Audit log: Not logged (no human decision to record — warnings are informational only).

2b. Severity/Category Suggestion (Triage)

Trigger: "Get AI suggestion" button in existing triage panel at /hse/incidents/[id]/triage.

API route: POST /api/incidents/[id]/ai-triage

Claude prompt strategy: Send description, incident_type, injury_involved, lost_days. Ask Claude to return suggested severity 1-5 with confidence (high/medium/low) and one-sentence reasoning. Return as JSON.

Response:

{
  "suggested_severity": 3,
  "confidence": "medium",
  "reasoning": "Injury involved with medical treatment but no LTI reported — consistent with severity 3."
}

UI: Suggestion card appears below the severity input in the triage form. "Accept" pre-fills the severity field. HSE can ignore and type their own value. Card shows confidence label and reasoning text.

Audit log: On triage form save, log: suggested_severity, confidence, human's final severity value. record_id = incident id.

2c. RCA/CAPA Drafting Assistant

Trigger: "Generate suggestions" button in investigation workspace at /hse/incidents/[id]/investigation.

API route: POST /api/incidents/[id]/ai-rca

Claude prompt strategy: Send incident description, investigation findings_text, root_cause_summary. Ask Claude to return: 2-3 root cause categories (from standard EHS taxonomy: Human Factors, Equipment Failure, Procedure, Environment, Management System) + 2-3 draft CAPA action descriptions as JSON array.

Response:

{
  "root_causes": [
    { "category": "Procedure", "explanation": "No documented SOP for forklift loading at Dock A" }
  ],
  "capa_drafts": [
    "Develop and implement SOP for forklift loading operations at all dock areas within 14 days",
    "Conduct refresher training for all forklift operators on LOTO procedure by end of month"
  ]
}

UI: Collapsible "AI Suggestions" panel below the RCA form fields. Each root cause has a "Use this" button that appends text to root_cause_summary. Each CAPA draft has a "Create CAPA" button that opens the CAPA creation form pre-filled with that description.

Audit log: Log on button click: which suggestion index was used, full suggestions array as old_value context. record_id = incident id.

---

3. Data & Schema

No new DB tables required. Existing audit_log table handles AI suggestion logging via action = 'ai_suggested'.

CSV export routes query existing tables — no new schema.

---

4. Implementation Order

1. Dashboard — HSE (upgrade existing, most complex)
2. Dashboard — Management
3. Dashboard — Supervisor
4. Dashboard — CAPA Owner
5. Dashboard — Reporter
6. CSV export endpoint (shared, covers HSE + management)
7. Report quality check (AI)
8. Severity suggestion at triage (AI)
9. RCA/CAPA drafting assistant (AI)

---

5. Out of Scope (Phase 3)

• Similar-incident retrieval via pgvector — Phase 4
• WhatsApp notifications — Phase 4
• Multi-language UI — Phase 4
• CAPA effectiveness re-check automation — Phase 4
• Risk heatmap / predictive analytics — Phase 4