Developer Handover Pack

Developer Handover Pack

Workplace Incident Reporting

This agent fires the moment a new Google Form response lands. It parses every field from the form payload, applies the severity classification logic (minor, moderate, or serious) against agreed rule criteria covering injury type, number of people affected, and regulatory threshold flags, assigns a padded sequential reference number (e.g. INC-0042), and writes a fully structured row to the Google Sheets incident register. It is the entry point for the entire workflow and all downstream agents depend on the data it writes. Estimated build time: 6 hours. Complexity: Moderate.

// Input
form_response: {
  submitted_at: ISO8601 timestamp,
  reporter_name: string,
  reporter_email: string,
  incident_date: date (YYYY-MM-DD),
  incident_time: string,
  incident_location: string,
  incident_type: enum [near-miss, injury, property-damage, hazard-report],
  injury_involved: boolean,
  injured_employee_id: string | null,
  description: string (free text),
  witnesses: string | null
}

// Output
sheets_row: {
  reference_number: string (e.g. INC-0042),
  submitted_at: ISO8601,
  reporter_name: string,
  reporter_email: string,
  incident_date: date,
  incident_type: string,
  injury_involved: boolean,
  injured_employee_id: string | null,
  severity: enum [minor, moderate, serious],
  description: string,
  status: 'open',
  notification_sent: false,
  investigation_due_date: date (incident_date + 5 business days for minor/moderate; + 2 for serious),
  corrective_actions_closed: false,
  bamboohr_updated: false
}

This agent watches the Google Sheets incident register for new confirmed rows written by the Intake Agent. On each new row it reads the department field and severity to determine the correct Slack recipient: the line manager for that department receives a channel notification for all incidents; the operations director receives an additional direct message for any incident classified as serious. The agent also writes a notification log entry (recipient, channel or DM ID, timestamp, incident reference) back to a dedicated Notifications tab in the same Google Sheet. Estimated build time: 5 hours. Complexity: Moderate.

// Input
sheets_row: {
  reference_number: string,
  severity: enum [minor, moderate, serious],
  incident_type: string,
  incident_date: date,
  incident_location: string,
  description: string (truncated to 300 chars for Slack preview),
  reporter_name: string,
  department: string  // used for manager routing lookup
}

// Output
slack_message_manager: {
  channel: '#incidents-[department]' or manager Slack user ID,
  text: 'New incident [reference_number] logged: [severity] | [incident_type] | [incident_date]. Please review and investigate within [investigation_due_date].',
  blocks: [incident summary card with reference, severity badge, due date, Notion link placeholder]
}
slack_message_director: {  // serious incidents only
  channel: '@ops-director-user-id',
  text: 'SERIOUS incident [reference_number] requires your immediate awareness. HR has been notified.'
}
sheets_notification_log_row: {
  reference_number: string,
  notified_at: ISO8601,
  manager_slack_id: string,
  director_notified: boolean,
  notification_sent: true
}

This is the most complex agent in the workflow. It triggers on a confirmed incident row in Google Sheets and performs four distinct functions: creates a structured Notion investigation page with all incident fields pre-populated and a deadline set; monitors that page on a scheduled poll and sends Gmail deadline reminder emails to the assigned manager if the page status has not progressed to 'findings submitted' before the due date; once corrective actions are logged in Notion, monitors each action for completion and sends escalating Gmail reminders; and for rows where injury_involved is true, calls the BambooHR API to write the incident date, type, and reference number to the employee's record. HR retains responsibility for marking the incident formally closed in Notion, which triggers the final closure confirmation email to the reporter. Estimated build time: 11 hours. Complexity: Complex.

// Input
sheets_row: {
  reference_number: string,
  severity: string,
  incident_type: string,
  incident_date: date,
  description: string,
  reporter_name: string,
  reporter_email: string,
  injury_involved: boolean,
  injured_employee_id: string | null,
  investigation_due_date: date,
  department: string
}

// Output: Notion page
notion_page: {
  database_id: [INCIDENTS_DB_ID],
  properties: {
    'Reference': reference_number,
    'Severity': severity,
    'Incident Type': incident_type,
    'Incident Date': incident_date,
    'Description': description,
    'Reporter': reporter_name,
    'Department': department,
    'Investigation Due': investigation_due_date,
    'Status': 'Under Investigation',
    'Findings': '' (blank, manager fills),
    'Corrective Actions': [] (relation, manager populates)
  }
}

// Output: Gmail reminder (deadline approaching, T-1 day)
gmail_reminder_1: {
  to: manager_email,
  subject: '[INC-XXXX] Investigation due tomorrow',
  body: 'The investigation deadline for incident [reference_number] is tomorrow. Please update the Notion page: [notion_page_url]'
}

// Output: Gmail reminder (deadline passed, T+0 and T+3 escalation)
gmail_reminder_2: {
  to: manager_email,
  cc: hr_coordinator_email,
  subject: '[INC-XXXX] Investigation overdue',
  body: 'The investigation for [reference_number] is now overdue. Please submit findings immediately.'
}

// Output: BambooHR update (injury incidents only)
bamboohr_custom_field_patch: {
  endpoint: 'PUT /v1/employees/{employee_id}/tables/customTabIncidents',
  body: {
    incident_reference: reference_number,
    incident_date: incident_date,
    incident_type: incident_type,
    outcome_notes: severity
  }
}

// On HR closes incident in Notion (status set to 'Closed')
gmail_closure: {
  to: reporter_email,
  subject: 'Incident [reference_number] closed',
  body: 'Your incident report has been investigated and all corrective actions confirmed. Reference: [reference_number].'
}
sheets_status_update: {
  row: matched by reference_number,
  status: 'closed',
  closed_at: ISO8601
}

// ── TRIGGER ──────────────────────────────────────────────────────────────
// Employee submits Google Form
TRIGGER: google_forms.on_new_response(form_id: INCIDENT_FORM_ID)
  -> form_response {
       submitted_at, reporter_name, reporter_email,
       incident_date, incident_time, incident_location,
       incident_type, injury_involved, injured_employee_id,
       description, witnesses
     }

// ── AGENT 1: INCIDENT INTAKE AGENT ───────────────────────────────────────
// Input: raw form_response
// Action: apply severity classification rules
severity = classify(incident_type, injury_involved, description)
  // rule: injury_involved = true AND incident_type = 'injury' -> 'serious'
  // rule: incident_type = 'near-miss' AND injury_involved = false -> 'minor'|'moderate'
  // rule: incident_type = 'hazard-report' -> 'minor' by default

// Action: assign reference number (read last INC-XXXX from config cell, increment)
reference_number = 'INC-' + zero_pad(last_ref + 1, 4)

// Action: compute investigation_due_date
investigation_due_date = add_business_days(
  incident_date,
  severity == 'serious' ? 2 : 5
)

// Action: write to Google Sheets register
google_sheets.append_row(sheet_id: REGISTER_SHEET_ID, tab: 'Incidents', row: {
  reference_number, submitted_at, reporter_name, reporter_email,
  incident_date, incident_type, injury_involved, injured_employee_id,
  severity, description, status: 'open',
  notification_sent: false, investigation_due_date,
  corrective_actions_closed: false, bamboohr_updated: false
})

// Output: confirmed row in Google Sheets with reference_number, severity, due_date

// ── AGENT 2: NOTIFICATION AND ESCALATION AGENT ───────────────────────────
// Input: new Google Sheets row where notification_sent = false
// Trigger: polled on new row append OR event-driven via webhook from Sheets

manager_slack_id = routing_table.lookup(department)
  // routing_table: [department -> slack_channel_id | slack_user_id]
  // must be pre-configured as a static lookup in the automation platform

// Action: send manager Slack notification (all severities)
slack.post_message(channel: manager_slack_id, blocks: [
  severity_badge(severity),  // green|amber|red
  text: '[reference_number] | [incident_type] | Due: [investigation_due_date]',
  text: description[0:300]
])

// Action: send director DM (serious only)
IF severity == 'serious':
  slack.post_message(channel: OPS_DIRECTOR_SLACK_ID,
    text: 'SERIOUS: [reference_number] requires immediate awareness.'
  )

// Action: log notification and update sheet
google_sheets.update_row(reference_number, {
  notification_sent: true,
  notified_at: now()
})
google_sheets.append_row(tab: 'NotificationLog', row: {
  reference_number, notified_at, manager_slack_id,
  director_notified: severity == 'serious'
})

// Output: Slack messages delivered; notification_sent = true in register

// ── AGENT 3: INVESTIGATION AND CORRECTIVE ACTION AGENT ───────────────────
// Input: confirmed Sheets row, notification_sent = true

// Action: create Notion investigation page
notion_page_id = notion.create_page(database_id: INCIDENTS_DB_ID, properties: {
  'Reference': reference_number,
  'Severity': severity,
  'Incident Type': incident_type,
  'Incident Date': incident_date,
  'Description': description,
  'Reporter': reporter_name,
  'Department': department,
  'Investigation Due': investigation_due_date,
  'Status': 'Under Investigation'
})

// Store notion_page_id back to Sheets row for reference
google_sheets.update_row(reference_number, { notion_page_url: notion_page_id })

// ── SCHEDULED POLL: daily at 08:00 local time ────────────────────────────
// Action: check each open Notion page against today's date
FOR each open_incident IN google_sheets.get_rows(status: 'open'):
  notion_status = notion.get_page(notion_page_id).properties['Status']

  IF today == investigation_due_date - 1 AND notion_status == 'Under Investigation':
    gmail.send(to: manager_email,
      subject: '[reference_number] Investigation due tomorrow',
      body: 'Please update: [notion_page_url]'
    )

  IF today >= investigation_due_date AND notion_status == 'Under Investigation':
    gmail.send(to: manager_email, cc: hr_email,
      subject: '[reference_number] Investigation OVERDUE',
      body: 'Immediate action required.'
    )

// ── BambooHR UPDATE (injury incidents only) ───────────────────────────────
IF injury_involved == true AND bamboohr_updated == false:
  bamboohr.put('/v1/employees/{injured_employee_id}/tables/customTabIncidents', {
    incident_reference: reference_number,
    incident_date: incident_date,
    incident_type: incident_type,
    outcome_notes: severity
  })
  google_sheets.update_row(reference_number, { bamboohr_updated: true })

// ── CLOSURE TRIGGER (HR sets Notion page Status to 'Closed') ─────────────
// Trigger: Notion webhook on page property change OR daily poll detects 'Closed'
IF notion_status == 'Closed' AND corrective_actions_all_complete:
  gmail.send(to: reporter_email,
    subject: 'Incident [reference_number] closed',
    body: 'Your report has been investigated and corrective actions confirmed.'
  )
  google_sheets.update_row(reference_number, {
    status: 'closed',
    closed_at: now()
  })

// ── END OF FLOW ──────────────────────────────────────────────────────────