Reggie Staff SMS Service

Status: Superseded - See V3
Version: 1.0 (Original Design)
Last Updated: 2026-01-06

Note: This was the original V1 design document. The system has evolved through V2 and is now on V3. This doc remains for historical reference.

---

1. Overview

The Reggie Staff SMS Service allows employees to text Reggie's number to ask questions about their employment. Reggie will answer questions using data from Deputy (shifts/leave), Xero (pay), Monday (tasks), and the Employee Handbook.

Design Philosophy

Rather than a single LLM agent with tool-calling capabilities, we use a two-stage architecture for reliability and auditability:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Stage 1        │    │  Data Fetch     │    │  Stage 2        │
│  CLASSIFIER     │───▶│  SERVICE        │───▶│  RESPONDER      │
│  (Categorize)   │    │  (Get context)  │    │  (Generate)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
       │                                              │
       │ "Is this about shifts?"                     │ "Your next shift is..."
       │                                              │
   Small/Fast LLM                               Main LLM + Context

---

2. Two-Stage Architecture

Stage 1: Classifier

Purpose: Determine if the incoming message is about an answerable topic.

Input:

{
  "message": "when do i get paid next?",
  "from_phone": "+61412345678",
  "staff_name": "Sarah Johnson"
}

Classifier Prompt:

You are a message classifier for a disability services company.
Given a staff member's SMS, determine if it relates to one of these topics:

ANSWERABLE TOPICS:
- shifts: Questions about upcoming shifts, roster, schedule
- leave: Leave balance, leave requests, time off
- pay: Pay dates, payslips, pay rates, superannuation
- training: Required training, certifications, compliance
- handbook: Company policies, procedures, dress code, conduct
- tasks: Assigned tasks, deadlines, Monday board items

Respond with JSON:
{
  "topic": "pay|shifts|leave|training|handbook|tasks|unknown",
  "confidence": 0.0-1.0,
  "is_answerable": true|false
}

Output:

{
  "topic": "pay",
  "confidence": 0.95,
  "is_answerable": true
}

Data Fetch Service

Based on the classified topic, fetch relevant data:

Topic	Data Sources
shifts	Deputy: Next 7 days of rostered shifts
leave	Deputy: Leave balance, pending requests
pay	Xero: Next pay date, last payslip summary
training	Monday: Training board items for this staff
handbook	Vector search: Relevant handbook sections
tasks	Monday: Assigned tasks with deadlines

Stage 2: Responder

Purpose: Generate a helpful, accurate response using the fetched context.

Input:

{
  "topic": "pay",
  "staff_name": "Sarah Johnson",
  "original_message": "when do i get paid next?",
  "context": {
    "next_pay_date": "2026-01-09",
    "pay_frequency": "fortnightly",
    "last_pay_amount": "$1,847.32"
  }
}

Responder Prompt:

You are Reggie, a helpful AI assistant for RABS disability services staff.

Staff member: Sarah Johnson
Their question: "when do i get paid next?"
Topic: Pay information

Context data:
- Next pay date: Thursday 9th January 2026
- Pay frequency: Fortnightly
- Last pay: $1,847.32

Generate a friendly, concise SMS response (max 160 chars if possible).
Be accurate - only state facts from the context provided.
Sign off as "Reggie".

Output:

Hi Sarah! Your next pay is Thursday 9th Jan. Pay runs fortnightly. 
Let me know if you need anything else! - Reggie

---

3. Answerable Topics Configuration

Stored in database for easy modification:

CREATE TABLE comms.reggie_staff_topics (
  id UUID PRIMARY KEY,
  topic_key TEXT UNIQUE NOT NULL,      -- 'shifts', 'pay', etc.
  topic_name TEXT NOT NULL,
  description TEXT,
  data_sources JSONB NOT NULL,         -- ['deputy_shifts', 'xero_payroll']
  is_enabled BOOLEAN DEFAULT TRUE,
  classifier_hints TEXT[],             -- Keywords to help classifier
  response_template TEXT,              -- Optional template
  created_at TIMESTAMPTZ DEFAULT NOW()
);

Default Topics

Topic	Data Sources	Example Questions
shifts	Deputy roster	"What shifts do I have this week?"
leave	Deputy leave	"How much annual leave do I have?"
pay	Xero payroll	"When is the next pay day?"
training	Monday training board	"What training do I need to complete?"
handbook	Handbook vector store	"What's the dress code policy?"
tasks	Monday tasks	"What tasks are assigned to me?"

---

4. Staff Identification

When an SMS arrives at Reggie's number:

1. YP3000 Lookup: Resolve phone number to identity
2. Staff Verification: Check if identity has primary_role = 'staff' and staff_id link
3. Access Control: Only respond to verified staff

Non-Staff Response:

Hi! This number is for RABS staff enquiries only. 
If you need to contact us, please call the office on (02) XXXX XXXX.
- Reggie

---

5. Conversation Flow

Staff SMS: "hey reggie when's my next shift"
                    │
                    ▼
        ┌─────────────────────┐
        │ YP3000 Resolution   │
        │ Phone → Identity    │
        │ → Staff: Sarah J    │
        └─────────────────────┘
                    │
                    ▼
        ┌─────────────────────┐
        │ Stage 1: Classify   │
        │ Topic: shifts       │
        │ Confidence: 0.92    │
        └─────────────────────┘
                    │
                    ▼
        ┌─────────────────────┐
        │ Data Fetch          │
        │ Deputy API →        │
        │ Next 7 days shifts  │
        └─────────────────────┘
                    │
                    ▼
        ┌─────────────────────┐
        │ Stage 2: Respond    │
        │ Generate SMS        │
        └─────────────────────┘
                    │
                    ▼
Reply SMS: "Hi Sarah! Your next shift is tomorrow (Tue 7th) 
           8am-4pm at Penrith Day Program. - Reggie"

---

6. Error Handling

Scenario	Response
Unknown topic	"I'm not sure I can help with that. Try asking about shifts, leave, pay, or policies. - Reggie"
Data fetch failed	"Sorry, I couldn't get that info right now. Please try again or contact the office. - Reggie"
Low confidence	"I want to make sure I understand - are you asking about [topic]? - Reggie"
Non-staff sender	Polite redirect to office number

---

7. Logging & Audit

All interactions logged for compliance:

CREATE TABLE comms.reggie_staff_conversations (
  id UUID PRIMARY KEY,
  identity_id UUID REFERENCES core_source.yp3000_identities(id),
  staff_id UUID REFERENCES core_source.staff(id),
  incoming_message TEXT NOT NULL,
  classified_topic TEXT,
  classifier_confidence FLOAT,
  data_context JSONB,                  -- What data was fetched
  outgoing_message TEXT,
  response_latency_ms INTEGER,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

---

8. Implementation Phases

Phase 1: Foundation

• Two-stage LLM pipeline
• Staff identification via YP3000
• Basic topics: shifts, pay

Phase 2: Data Integrations

• Deputy shift data fetch
• Xero pay data fetch
• Leave balance queries

Phase 3: Extended Topics

• Monday tasks integration
• Handbook vector search
• Training compliance queries

Phase 4: Polish

• Conversation context (follow-up questions)
• Admin dashboard for topic config
• Analytics on common questions