KPI Performance Framework

Version: 2.0.0
Status: Core Implementation Complete
Last Updated: 2026-01-17

Executive Summary

The KPI Performance Framework is a revolutionary approach to staff performance management designed specifically for disability support organisations. Unlike traditional KPI systems that create anxiety and feel punitive, this framework emphasizes transparency, coaching, and effort recognition.

Why This Matters for RABS

RABS has historically lacked formal KPI tracking due to:

• Limited HR resources to manually track performance
• Fear of creating a punitive environment for support workers
• No integrated system to collect data from multiple sources
• Concern about damaging workplace culture

This framework solves these problems by:

1. Automating data collection from existing systems (Deputy, Discord, shift notes)
2. Recognizing effort alongside outcomes (effort score provides buffer before triggers)
3. Providing coaching instead of surveillance
4. Separating process transparency from data access (staff see scores and tips, not raw peer feedback)
5. Visual storytelling through the tree-to-phoenix health visualization

---

Philosophy & Core Principles

1. Transparency of PROCESS, Not Raw DATA

Staff can see:

• ✅ What KPIs they're measured on
• ✅ How each KPI is calculated (data sources listed)
• ✅ Their current scores and trends
• ✅ AI-generated coaching tips
• ✅ Areas for growth with actionable guidance

Staff cannot see:

• ❌ Raw peer feedback or who said what
• ❌ Individual incident reports naming them
• ❌ Management's private concerns
• ❌ Detailed data points (aggregated only)

2. Effort Matters

Every KPI has a separate effort score that acts as a buffer:

• Effort score decays over time (always trending toward 0%)
• Evidence-based entries add effort points
• 100% effort = up to 10% buffer on actual score
• Formula: effective_score = actual_score + (effort_score × 0.10)
• This means a staff member at 55% actual with 100% effort has 65% effective score

Why this matters:

• A support worker who genuinely tries but struggles gets a buffer before triggers
• Working with HR to document effort can prevent performance workflows
• Effort must be continuously demonstrated (it decays)

3. Living Journal, Not Static Scores

Every score change is logged with context:

• What triggered the change (telemetry, observation, catch-up)
• Who made the entry (system vs. manager)
• Why it matters (AI-generated summary)
• Staff can request context be added (approval queue)

4. Coaching Over Surveillance

The AI assistant:

• Generates personalized coaching tips based on patterns
• Celebrates improvements and streaks
• Suggests specific actions for growth
• Never names individual complainants or incidents

---

Scoring System

Points-Based Model

Core Rule: 10 points = 1% (universal, predictable)

All KPIs use a standardized points system:

• Journal entries add or deduct points
• Points convert to percentage at a fixed rate
• This allows automated systems to contribute without knowing percentages

Starting State

• All KPIs start at their target score (typically 80%)
• No journal entries = 80% (baseline "doing your job correctly")
• Above 80% = exceptional performance
• Below 80% = areas for improvement

Target vs Minimum (Criticality)

The target is standardized (80%) so all KPIs are comparable. The minimum defines how critical the KPI is:

KPI Type	Target	Minimum	Margin	Incidents to Minimum*
Critical	80%	70%	10%	10 entries of -10 pts
Standard	80%	60%	20%	20 entries of -10 pts
Low-stakes	80%	40%	40%	40 entries of -10 pts

*Assuming -10 points = -1%

Threshold Triggers:

• Dropping below minimum triggers performance workflow
• But the effective score (with effort buffer) is what's checked
• 51% actual + 100% effort (10% buffer) = 61% effective → no trigger if minimum is 60%

Standardized Point Scale

Journal entries use a dropdown with consistent options:

Points	Label	Description
+10	Exceptional	Dramatic positive change in practices
+5	Sustained	Previous improvements maintained
+3	Minor positive	Small improvement noted
0	Note only	Context/observation, no score change
-3	Minor concern	Small issue noted
-5	Not sustained	Changes not adopted or maintained
-10	Significant concern	Additional evidence of undesired behaviour

Effort Score (Per KPI)

Separate from the main score, provides a safety buffer using a per-entry decay model:

1. Per-entry lifecycle - Each effort entry has its own decay based on when it was added
2. Contribution formula - effort_points × 10 × (1 - days_old / 42)
3. Entries expire - After 42 days (6 weeks) an entry contributes 0
4. Contributions stack - Multiple entries sum up with no cap (bragging rights!)
5. Buffer calculation - effective_score = actual_score + MIN(10%, effort_score × 0.10)
6. Maximum buffer - Capped at 10% even if effort exceeds 100%

Why per-entry decay?

• Each effort demonstration has its own lifespan
• Multiple entries can stack (e.g., 20 entries over 20 days = 200%+)
• Old entries naturally expire without complex tracking
• Sustained effort (regular entries) maintains the buffer
• Effort > 100% is a badge of honor but buffer still caps at 10%

Caching Strategy:

• Scores cached in cached_effort_score column
• Updated by trigger on journal entry changes
• Refreshed by midnight cron job for decay accuracy
• Fast widget/dashboard loading from cached values

Example:

• Day 0: Staff adds +10 effort → 10 × 10 × (1 - 0/42) = 100%
• Day 21: Add +5 effort → first entry at 50%, second at 100%
  • Total: (10 × 10 × 0.5) + (5 × 10 × 1.0) = 50% + 50% = 100%
• Day 42: First entry expired, second at 50%
  • Total: 0% + (5 × 10 × 0.5) = 25%
• Effective buffer at 25% effort: MIN(10%, 25% × 0.10) = 2.5% protection

---

Complete Scoring Breakdown

Score Calculation Formula

Main Score = Target Score + (Total Points / 10)
           = 80% + (sum of all score_impact values / 10)
           = Clamped to 0-100%

Effort Score = SUM of each entry's contribution
             = SUM(effort_points × 10 × (1 - days_old / 42))
             = Can exceed 100% (no cap)

Effort Buffer = MIN(10%, Effort Score × 0.10)
              = Caps at 10% even if effort > 100%

Effective Score = Main Score + Effort Buffer
                = What's actually compared against minimum threshold

Worked Examples

Example 1: New Staff Member

• Target: 80%, Minimum: 60%
• No journal entries yet
• Main Score: 80% (default)
• Effort Score: 0%
• Effective Score: 80% ✓ Above minimum

Example 2: Staff with Negative Feedback

• Target: 80%, Minimum: 60%
• Journal entries: -10 points, -5 points, -3 points = -18 total
• Main Score: 80% + (-18/10) = 80% - 1.8% = 78.2%
• Effort Score: 0%
• Effective Score: 78.2% ✓ Above minimum

Example 3: Staff Struggling but Showing Effort

• Target: 80%, Minimum: 60%
• Score entries: -50 points total over past month
• Main Score: 80% - 5% = 75%
• Effort entries: +10 (5 days ago), +10 (15 days ago), +5 (30 days ago)
  • Entry 1: 10 × 10 × (1 - 5/42) = 88.1%
  • Entry 2: 10 × 10 × (1 - 15/42) = 64.3%
  • Entry 3: 5 × 10 × (1 - 30/42) = 14.3%
  • Total Effort: 166.7%
• Effort Buffer: MIN(10%, 166.7% × 0.10) = 10% (capped)
• Effective Score: 75% + 10% = 85% ✓ Above minimum

Example 4: Staff Below Minimum (Triggers Performance Workflow)

• Target: 80%, Minimum: 60%
• Score entries: -250 points total
• Main Score: 80% - 25% = 55%
• Effort: All entries > 42 days old = 0%
• Effective Score: 55% ❌ Below 60% minimum → TRIGGER

Database Tables Involved

hr.staff_kpis
├── current_score        -- Main score (cached, recalculated by trigger)
├── total_points         -- Sum of all score_impact from entries
├── cached_effort_score  -- Effort score (cached, refreshed by cron)
└── scores_calculated_at -- When last recalculated

hr.kpi_journal_entries
├── score_impact    -- Points added/deducted (-10 to +10)
├── effort_points   -- Effort demonstration (0 to +10)
└── created_at      -- Used for effort decay calculation

Recalculation Triggers

1. Journal Entry Change (trigger)

   • INSERT, UPDATE, DELETE on hr.kpi_journal_entries
   • Only recalcs if score_impact, effort_points, created_at, or staff_kpi_id changed
   • Immediate update to cached values

2. Midnight Cron Job (scheduled)

   • Runs at 00:00 daily
   • Refreshes all active KPI scores
   • Required for effort decay to update without journal activity
   • Enable with KPI_CRON=true in .env

3. Manual Recalculation (on-demand)

   • "Recalc Scores" button on KPI Modules page
   • Calls POST /api/v1/hr/kpis/recalculate-all
   • Useful if cron hasn't run or for debugging

Effort Decay Visualization

Day 0   ████████████████████ 100%  (10 pts × 10)
Day 7   █████████████████░░░  83%
Day 14  ██████████████░░░░░░  67%
Day 21  ███████████░░░░░░░░░  50%
Day 28  ████████░░░░░░░░░░░░  33%
Day 35  █████░░░░░░░░░░░░░░░  17%
Day 42  ░░░░░░░░░░░░░░░░░░░░   0%  (expired)

---

System Integration

Automated processes can write journal entries with points:

Example: Sick leave without sufficient balance The warnings system might create:

• KPI "Attendance": note + -10 points
• KPI "Leave Management": note + -5 points
• KPI "Communication": note + 0 points (context only)

This allows any system to participate in KPI scoring with predictable, auditable entries.

Total File Health

The overall "File Health" score (displayed on the tree-to-phoenix visualization):

• Average of all active KPI percentages
• KPIs with no entries default to target (80%)
• Drives the visual progression from dead tree (low) to phoenix (high)

---

KPI Performance Interface

Visual Design: Tree to Phoenix

The KPI interface uses 8 background images showing progression:

• 1B-2B: Dead tree in storm (0-49%)
• 3B-4B: Bare tree, clouds clearing (50-64%)
• 5B-6B: Growing tree with leaves (65-79%)
• 7B: Healthy tree with light (80-89%)
• 8B: Phoenix rising from tree (90-100%)

This creates emotional context - staff see their "file health" as a living thing that grows with good performance.

Interface Layout

• Full-screen modal with immersive background
• Vertical nav (top-left): Direct KPIs, Catch Up, APR, Reports
• Content area (left ~45%): Cards and forms
• Plinth (right): Shows overall health score on the background's pedestal
• Background cycler (debug): Arrows to preview all backgrounds

Four Views

1. Direct KPIs - List of assigned KPIs with scores, click to expand for Journal/Add Note
2. Catch Up - Structured 1:1 meeting form (responses route to KPI journals)
3. APR - Annual Performance Review form
4. Reports - AI-generated summaries (Performance, Strengths, Development, Compliance)

Journal View

When viewing a KPI's journal:

• Header with KPI name and "Back" button
• "Add Note" button
• Chronological list of entries showing:
  • Entry type badge (Note, Added, Activated, Catch Up, etc.)
  • Date and time
  • Title and content
  • Author name
  • Delete button

---

System Architecture

Database Schema (hr.* namespace)

hr.kpi_modules          58 KPIs across 14 role groups
hr.template_kpis        Links KPIs to contract templates
hr.staff_kpis           Individual assignments with cached scores
hr.kpi_journal_entries  Living journal (13 entry types)
hr.kpi_adjustments      Audit trail with flagging
hr.staff_catchups       Structured 1:1 conversations
hr.catchup_kpi_discussions  KPI-specific discussions
hr.kpi_evaluations      Periodic summaries (staff/admin split)
hr.kpi_achievements     Gamification (badges, streaks)

Data Flow

Contract Template → Staff Contract → Staff KPIs
       ↓                                  ↓
  Default KPIs                    Individual Additions
       ↓                                  ↓
                  staff_kpis table
                        ↓
              Journal Entries (from data sources)
                        ↓
              Weekly AI Evaluation
                        ↓
         Staff Dashboard + Coaching Tips

Integration Points

Source	Data Type	Automation Status
Deputy Timesheets	Attendance, punctuality, shift completion	🟢 Live
Deputy Leave	Leave patterns, availability	🟢 Live
Shift Notes	Care quality, participant engagement	🟡 Partial
Discord Activity	Communication, team engagement	🟡 Partial
Incident Reports	Safety, compliance	🔴 Planned
Phone Logs	Response times, communication	🔴 Planned
Supervision Records	Professional development	🔴 Planned
Hazard Reports	Safety awareness	🔴 Planned
Training Records	Compliance, skill development	🔴 Planned

---

KPI Module Library

Role Groups (15 Total)

1. Universal - All staff (communication, culture, safety, documentation)
2. Support Worker - Direct care (participant engagement, plan adherence, vehicle reporting)
3. Senior Support - Leadership (mentoring, incident trends, shift coverage)
4. Admin (General) - Office tasks (efficiency, record keeping, responsiveness)
5. Program Coordinator - Bridey's role (program delivery, roster management, staff coordination)
6. Support Coordinator - Case management (plan utilisation, NDIS compliance, stakeholder comms)
7. Customer Service - Client-facing (response time, resolution quality, triage)
8. Bookkeeper - Financial (transaction accuracy, reconciliation, invoice processing)
9. WHS & Facilities - Safety & assets (hazard mitigation, fleet management, audits)
10. Senior Manager (Finance) - Ami's role (billing accuracy, revenue protection, governance)
11. Senior Manager (Operations) - Richelle's role (program effectiveness, workforce utilisation, risk)
12. HR Staff - People ops (retention, recruitment, compliance, onboarding)
13. COO (Operations) - Executive level (cross-dept efficiency, strategic delivery, technology)
14. CEO - Organizational (sustainability, stakeholder confidence, culture)
15. Board - Governance (effectiveness, stewardship, strategic direction)

KPI Categories

Category	Focus	Example KPIs
Culture	Team environment	Team Collaboration, Peer Support
Productivity	Reliability	Attendance, Punctuality, Task Completion
Communication	Responsiveness	Message Response Time, Documentation Quality
Safety	Compliance	Incident Reporting, PPE Compliance
Care Quality	Participant outcomes	Engagement, Goal Progress, Satisfaction
Financial	Money management	Budget Adherence, Invoice Accuracy
Leadership	Team development	Mentoring, Decision Making
Compliance	Regulatory	Training Currency, Audit Readiness
Operational	Efficiency	Resource Utilization, Process Improvement

---

Ready-to-Use KPIs (🟢 Live/Partial Automation)

Universal KPIs (All Staff)

KPI	Automation	Data Sources
Attendance Rate	🟢 Live	Deputy Timesheets
Punctuality	🟢 Live	Deputy Timesheets
Leave Management	🟢 Live	Deputy Leave Records
Communication Responsiveness	🟡 Partial	Discord, Email Metrics
Team Collaboration	🟡 Partial	Discord, Catch-up Notes
Professional Development	🔴 Planned	Training Records

Support Worker KPIs

KPI	Automation	Data Sources
Shift Completion Rate	🟢 Live	Deputy Timesheets
Documentation Timeliness	🟡 Partial	Shift Notes
Participant Engagement	🟡 Partial	Shift Notes, Feedback
Care Plan Adherence	🔴 Planned	Shift Notes, Goals
Incident Response	🔴 Planned	Incident Reports
Handover Quality	🔴 Planned	Shift Notes

Senior Support KPIs

KPI	Automation	Data Sources
Mentoring Hours	🔴 Planned	Supervision Records
Shift Coordination	🟡 Partial	Deputy, Discord
Quality Oversight	🔴 Planned	Shift Notes Review
Emergency Response	🔴 Planned	Incident Reports

---

Development Roadmap

Phase 1: Foundation ✅ Complete

• Database schema (58 KPIs, 9 tables)
• Template wizard KPI selection (Step 4)
• KPI Gallery page (page_hr_kpis.html)
• Backend API with role filtering
• Staff preview cards

Phase 2: KPI Performance Interface ✅ Complete (Jan 2026)

• Full-screen immersive modal with tree-to-phoenix backgrounds
• Vertical nav with 4 views (Direct KPIs, Catch Up, APR, Reports)
• Direct KPI cards with scores defaulting to target (80%)
• Journal view with entry listing
• Add Note functionality (modal → POST to journal)
• Delete journal entry functionality
• Health score calculation (average of all KPIs)
• Background image selection based on health score
• Plinth positioning for score display

Phase 3: Points-Based Scoring ✅ Complete (Jan 2026)

• Add score_impact and effort_points fields to journal entries
• Points dropdown in Add Note modal (-10 to +10)
• Score recalculation trigger on journal entry changes
• Per-entry effort decay model (42-day lifecycle)
• Effective score calculation (actual + effort buffer, capped at 10%)
• Cached effort scores for fast retrieval
• Midnight cron job for daily effort decay refresh
• Manual "Recalc Scores" button on KPI Modules page

Phase 4: Data Source Integration (Q1-Q2 2026)

• Deputy attendance automation
• Deputy punctuality calculation
• Shift notes keyword analysis
• Discord engagement metrics
• Leave pattern analysis

Phase 5: Catch Up & APR Forms (Q1 2026)

• Structured Catch Up meeting form
• Form responses route to KPI journals
• APR (Annual Performance Review) form
• Contract renewal integration

Phase 6: AI Evaluation Engine (Q2 2026)

• Weekly evaluation cron job
• AI summary generation (staff view)
• AI concern flagging (admin view)
• Coaching tip personalization
• Trend analysis

Phase 7: Contract Integration (Q2 2026)

• Auto-create staff_kpis on contract creation (done)
• Additional KPIs for individuals
• Probation KPI milestones
• Contract renewal KPI review

Phase 8: Gamification & Recognition (Q3 2026)

• Achievement badges
• Streak tracking
• Team leaderboards (opt-in)
• Monthly recognition automation
• Staff portal visibility

Phase 9: Advanced Analytics (Q3-Q4 2026)

• Team performance dashboards
• Department comparisons
• Trend forecasting
• Retention risk indicators
• Training gap analysis

---

Technical Reference

API Endpoints

# KPI Modules
GET  /api/v1/hr/kpi-modules              List all KPIs (with filters)
GET  /api/v1/hr/kpi-modules/:id          Single KPI details

# Template KPIs
GET  /api/v1/hr/templates/:id/kpis       Template's assigned KPIs
PUT  /api/v1/hr/templates/:id/kpis       Update template KPIs

# Staff KPIs
GET  /api/v1/hr/staff/:id/kpis           Staff member's KPIs
POST /api/v1/hr/staff/:id/kpis           Add KPI to staff member
PATCH /api/v1/hr/staff/:id/kpis/:kpiId   Update staff KPI status

# KPI Journal
GET  /api/v1/hr/staff/:staffId/kpis/:staffKpiId/journal           Get journal entries
POST /api/v1/hr/staff/:staffId/kpis/:staffKpiId/journal           Add journal entry
DELETE /api/v1/hr/staff/:staffId/kpis/:staffKpiId/journal/:id     Delete journal entry

Query Parameters

Endpoint	Parameter	Description
kpi-modules	role_group	Filter by role (e.g., support_worker)
kpi-modules	include_universal	Include universal KPIs (default: true)
kpi-modules	category	Filter by category (e.g., safety)
kpi-modules	active_only	Only active KPIs (default: true)

PostgreSQL ENUMs

hr.kpi_category: culture, productivity, communication, safety, 
                 care_quality, financial, leadership, compliance, operational

hr.kpi_role_group: universal, support_worker, senior_support, admin_general,
                   support_coordinator, customer_service, bookkeeper, 
                   whs_facilities, senior_manager_finance, senior_manager_operations,
                   hr_staff, executive, ceo, board

hr.kpi_score_type: percentage, rating, count, boolean, currency

hr.kpi_frequency: daily, weekly, fortnightly, monthly, quarterly, annually

hr.kpi_journal_entry_type: telemetry, manual_observation, manager_note,
                           catch_up, staff_context, adjustment, evaluation,
                           achievement, goal_set, goal_progress, flag_raised,
                           flag_resolved, system

hr.kpi_adjustment_reason: data_correction, extenuating_circumstances,
                          manager_discretion, staff_appeal, system_error, other

Key Files

File	Purpose
admin/src/html/page_hr_kpis.html	KPI gallery page
admin/src/js/pages/page_hr_kpis.js	Gallery JavaScript
admin/src/html/page_hr_contracting.html	Template wizard (Step 4)
admin/src/js/pages/page_hr_contracting.js	Template wizard JS
admin/src/html/page_staff_detail.html	Staff detail with KPI interface
admin/src/js/pages/page_staff_detail.js	KPI interface JavaScript
backend/routes_v1p/hr-contracts.js	KPI API routes (including journal)
admin/tasks/sql/sql-current/20260113_kpi_comprehensive_system.sql	Database schema
admin/tasks/sql/sql-current/20260117_kpi_points_and_effort.sql	Points & effort scoring
backend/services/kpi-cron.js	Midnight cron for score refresh
storage/assets/img/kpis/*.webp	Tree-to-phoenix background images (1B-8B)
admin/tasks/helpers/09_task_helper_template_ui.md	UI styling guide

---

Appendix: All 58 KPI Modules

Universal (6)

1. Attendance Rate
2. Punctuality
3. Leave Management
4. Communication Responsiveness
5. Team Collaboration
6. Professional Development Engagement

Support Worker (8)

7. Shift Completion Rate
8. Documentation Timeliness
9. Documentation Quality
10. Participant Engagement
11. Care Plan Adherence
12. Incident Response Quality
13. Handover Quality
14. Flexibility & Availability

Senior Support (6)

15. Mentoring & Coaching Hours
16. Shift Coordination Effectiveness
17. Quality Oversight
18. Emergency Response Leadership
19. Team Development
20. Rostering Support

Admin General (5)

21. Task Accuracy
22. Processing Timeliness
23. System Proficiency
24. Stakeholder Responsiveness
25. Record Keeping

Support Coordinator (6)

26. Plan Review Timeliness
27. Goal Achievement Rate
28. Participant Advocacy
29. Stakeholder Communication
30. Crisis Management
31. Documentation Compliance

Customer Service (5)

32. Response Time
33. Resolution Rate
34. Customer Satisfaction
35. Escalation Handling
36. Knowledge Accuracy

Bookkeeper (5)

37. Invoice Accuracy
38. Processing Timeliness
39. Reconciliation Accuracy
40. Reporting Timeliness
41. Compliance Adherence

WHS & Facilities (5)

42. Hazard Response Time
43. Inspection Completion
44. Compliance Rate
45. Incident Investigation Quality
46. Training Delivery

Senior Manager Finance (4)

47. Budget Accuracy
48. Forecasting Accuracy
49. Cost Optimization
50. Financial Reporting

Senior Manager Operations (4)

51. Service Delivery Quality
52. Resource Utilization
53. Process Improvement
54. Team Performance

HR Staff (4)

55. Recruitment Efficiency
56. Onboarding Quality
57. Employee Relations
58. Compliance Management

(Executive, CEO, and Board KPIs to be added in Phase 2)

---

Intelligent Meeting System

The Three Realities Problem

When conducting catch-up meetings, there are always three potentially different perspectives:

1. What the DATA shows - Objective scores, trend arrows, automated metrics
2. What MANAGEMENT perceives - Tacit knowledge, observations not yet in data
3. What the STAFF believes - Their self-assessment, context we don't have

Example: Bus Return Time KPI

• Data shows: 72% (below 80% target, trending down)
• Staff thinks: "I'm back by 4:15 most days, sometimes 4:20 if traffic is bad - I'm killing it!"
• Manager observes: "They're consistently 15-20 minutes late and it's affecting the next shift"

These misalignments are exactly why catch-ups exist - to get everyone on the same page.

Pre-Meeting Sentiment Check

Before generating a meeting agenda, the manager marks each KPI with their current perception:

Symbol	Meaning	Question Tone Generated
🟢	Exceeding expectations	Celebratory, learning-focused ("What can we learn from you?")
⚪	On track / Neutral	Maintenance-focused ("How's this going? Any friction?")
🔴	Needs attention	Supportive-corrective ("What obstacles can we help remove?")

Why this matters:

• Captures tacit knowledge before it's in the data
• Creates audit trail for gap analysis
• Drives appropriate question tone
• Acknowledges manager expertise beyond metrics

Gap Analysis Intelligence

Over time, comparing sentiment vs scores reveals patterns:

Scenario	Meaning	Action
Manager marks 🔴, score is 85%	Manager sees something data doesn't	Investigate data sources, trust manager
Manager marks 🟢, score is 55%	Manager too generous OR metrics wrong	Review both perception and measurement
Sentiment predicts score drop	Manager intuition is valuable	Weight sentiment in early warnings
Sentiment consistently wrong	Training opportunity	Calibrate manager expectations

Procedural Meeting Generation

Each meeting is procedurally generated based on:

• Staff member's specific KPI assignments
• Current scores and trends
• Manager sentiment selections
• Meeting type (Regular, Probation, Unscheduled, APR)

Meeting Structure Template:

1. Opening & Wellbeing (2 questions)
2. [For each KPI with 🔴 sentiment - 3-4 questions each]
3. [For each KPI with ⚪ sentiment - 2 questions each]
4. [For each KPI with 🟢 sentiment - 1-2 questions each]
5. Growth & Development (1-2 questions)
6. Staff Concerns & Feedback (open)
7. Closing & Next Steps (1 question)

Question Bank Structure

Each KPI has a question bank with three tone variants:

Example: Communication Responsiveness KPI

ID	Tone	Question
COMM-01-G	🟢 Green	"Your response times have been excellent. What's your system for staying on top of messages? Is there anything we could share with the team?"
COMM-01-N	⚪ Neutral	"How's the communication flow working for you? Any channels that feel overwhelming or any friction points?"
COMM-01-R	🔴 Red	"I've noticed some messages taking a while to get responses. What's getting in the way? Is there something about the current setup that makes it hard to stay on top of comms?"
COMM-02-G	🟢 Green	"Team members have mentioned you're great at keeping everyone in the loop. How do you decide what to escalate vs handle yourself?"
COMM-02-N	⚪ Neutral	"When something comes up on shift, how do you decide whether to message someone or wait until handover?"
COMM-02-R	🔴 Red	"There have been a couple of situations where information didn't get passed on in time. Can you walk me through how you handle urgent updates?"

LLM-Enhanced Generation

For more sophisticated meetings, the LLM can:

1. Select questions - Pick the most relevant from the bank based on KPI summaries
2. Generate custom questions - When the bank doesn't cover a specific situation
3. Provide scoring guidance - How to interpret and score responses

LLM Generation Request Format:

CONTEXT:
- Staff: [Name] ([Role], [Tenure])
- Meeting Type: [Regular/Probation/Unscheduled/APR]
- Manager Sentiment: [KPI: sentiment pairs]

KPI SUMMARIES FROM REPORTS:
[AI-generated summaries for each KPI]

MEETING STRUCTURE REQUIRED:
1. Opening (2 questions from wellbeing list)
2. [KPI Name] (N questions, tone: [green/neutral/red])
...

QUESTION BANK: [Provided per KPI]

OUTPUT FORMAT (for each question):
{
  "question_text": "...",
  "source": "bank" | "generated",
  "bank_question_id": "COMM-01-R" (if from bank),
  "intent": "What we're trying to learn",
  "expected_responses": {
    "positive": "Response indicating good understanding/practice",
    "neutral": "Response indicating awareness but room for growth",
    "concerning": "Response indicating misalignment or issue"
  },
  "scoring_guidance": {
    "effort_points": 0-10,
    "score_impact": -10 to +10,
    "conditions": "When to apply each score"
  },
  "fallback_question_id": "COMM-02-R" (if generated, closest bank alternative)
}

Safety Net: If LLM generates a custom question, it must also select the closest bank question as a fallback. Managers can always swap to the pre-approved alternative.

Meeting Types

1. Regular Catch Up (90-day cycle)

• Trigger: Automatic based on contract start date
• Purpose: Alignment, feedback, course correction
• Duration: 30-45 minutes
• Coverage: All active KPIs get at least one journal entry
• Tone: Collaborative, supportive

2. Probation Catch Up (1-3 or 2-5 meetings)

• Trigger: During probation period (3-month = 3 meetings, 6-month = 5 meetings)
• Purpose: Onboarding support, early issue detection, two-way feedback
• Duration: 20-30 minutes
• Focus: "How are you finding things? What do you struggle with? What could we do better for new staff?"
• Tone: Welcoming, curious, supportive

Probation Schedule:

Probation Length	Meeting 1	Meeting 2	Meeting 3	Meeting 4	Meeting 5
3 months	Week 2	Week 6	Week 11	-	-
6 months	Week 2	Week 6	Week 12	Week 18	Week 23

3. Unscheduled Catch Up (Performance Concern)

• Trigger: KPI drops below minimum threshold
• Purpose: Collaborative problem-solving, determine if educational/mentoring/disciplinary
• Duration: 30-45 minutes
• Tone: Serious but supportive, solution-focused
• Outcome: Action plan with clear expectations and timeline

Unscheduled Meeting Flow:

1. Acknowledge the concern clearly
2. Seek staff perspective (they may have context we don't)
3. Determine root cause together
4. Categorize response:
   • Educational - They didn't know, need training
   • Mentoring - They know but struggle, need support
   • Disciplinary - They know, can do it, choosing not to
5. Agree on action plan
6. Set follow-up date

4. Annual Performance Review (APR)

• Trigger: Contract anniversary or renewal period
• Purpose: Formal review, goal setting, career development
• Duration: 45-60 minutes
• Coverage: Full KPI analysis, year in review, forward planning
• Components:
  • AI-generated performance summary
  • Strengths analysis
  • Development areas
  • Achievement recognition
  • Goal setting for next period
  • Career conversation

Response Capture & Journal Integration

Every meaningful response during a meeting creates a journal entry:

Meeting: Regular Catch Up - 2026-01-18
KPI: Communication Responsiveness
Question: "What's getting in the way of responding to messages promptly?"

Response Summary: Staff explained they struggle with notifications on their 
personal phone and often miss Discord messages during shifts. Willing to 
try checking at set times (start, lunch, end of shift).

→ Journal Entry Created:
  - Type: catch_up
  - Title: "Communication barriers discussed"
  - Content: [Summary above]
  - Score Impact: 0 (informational)
  - Effort Points: +5 (showed willingness to improve)

Meeting Reports & Documentation

After each meeting, the system generates:

1. Meeting Summary - Key points discussed, decisions made
2. Action Items - With owners and due dates
3. Journal Entries - Auto-created for each KPI discussed
4. Follow-up Reminders - Scheduled based on action items

---

Contact & Support

• System Owner: HR Department
• Technical Lead: IT/Development Team
• Documentation: This file + inline code comments

For questions or feature requests, contact the HR team or raise a task in the HR Tasks board.