> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleverschool.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# Complaints Management

> Workflows & Investigation Deep Dive

## End-to-End Complaint Lifecycle

The module coordinates school complaints through a structured, multi-stage lifecycle that balances procedural fairness, rapid resolution, and statutory compliance.

```mermaid theme={null}
flowchart TD
    subgraph Stage1["Stage 1: Informal Stage"]
        S1["Concern raised and addressed informally;<br/>documented if escalated"]
    end

    subgraph Stage2["Stage 2: Formal Complaint Dossier"]
        S2_1["1. Manager adds complaint"] --> S2_2["2. Complainant submits formal details"]
        S2_2 --> S2_3["3. Staff add internal notes"]
        S2_3 --> S2_4["4. AI triage & policy review"]
        S2_4 --> S2_5{"5. Manager triage decision"}
        S2_5 -->|Investigate| S2_Inv["AI briefing ➔ Investigation ➔ Outcome"]
        S2_5 -->|Informal / Out of Scope / Unreasonable| S2_Draft["AI draft response dispatched"]
    end

    subgraph Stage3["Stage 3: Review Panel Appeal"]
        S3_1["1. Manager opens Stage 3"] --> S3_2["2. Complainant submits appeal grounds"]
        S3_2 --> S3_3["3. Staff add appeal notes"]
        S3_3 --> S3_4["4. AI Stage 3 triage"]
        S3_4 --> S3_5{"5. Manager decision"}
        S3_5 -->|Investigate - Review Panel| S3_Panel["Panel Review ➔ Outcome"]
        S3_5 -->|Out of Scope / Unreasonable| S3_Draft["AI draft response dispatched"]
    end

    Stage1 --> Stage2
    Stage2 -->|If escalated by Manager| Stage3
```

***

## Stage 2: Formal Investigation Workflow

### Step 1: Recording the Initial Complaint

When an informal concern cannot be resolved or a parent requests a formal investigation:

1. A `Complaints Manager` navigates to **Complaints** and clicks **Add Complaint**.
2. Enter the complainant's full name and email address, and optionally select a designated `Complaint Owner` (investigating officer).
3. The system assigns a unique reference number (e.g. `CMP-2026-001`) and sends an automated notification email to the complainant containing a secure magic login link and one-time password (OTP).

### Step 2: Complainant Portal Submission

The complainant logs in to the dedicated portal at `/complaint` and completes four mandatory submission fields:

* **Telephone & Address**: Verified contact details for formal correspondence.
* **Complaint Details**: Comprehensive narrative of the incident or grievance (up to 2,000 characters).
* **Stage 1 Action Taken**: Summary of informal discussions, meetings, or steps previously taken to resolve the issue.
* **Why Stage 1 Resolution Was Unsatisfactory**: Clear statement of why earlier informal measures failed to address the concern.
* **Stage 2 Action Requested**: Specific remedies or outcomes sought by the complainant.

> [!NOTE]
>
> Once submitted, the complainant's submission locks permanently to preserve evidentiary integrity and prevent retroactive changes.

### Step 3: School Context & Internal Investigation Notes

Before proceeding to triage, school staff review the submission and record internal background notes in four parallel fields:

* **Details Notes**: Contextual facts, internal records, witness accounts, or initial staff observations.
* **Stage 1 Action Notes**: School records of informal meetings, emails, or interventions previously attempted.
* **Stage 1 Unsatisfactory Notes**: Internal perspective on why the complainant rejected informal resolution.
* **Stage 2 Action Requested Notes**: Assessment of whether the requested remedies are viable, proportionate, or outside school authority.

> [!TIP]
>
> Internal notes are strictly confidential to staff with `Complaints Owner` or `Complaints Manager` permissions and are never exposed on the complainant's external portal.

### Step 4: AI-Assisted Policy Triage

Clicking **Submit for Triage** engages the `ComplaintTriager` AI agent:

1. The AI evaluates the complainant's submission alongside the school's internal notes.
2. It fetches and analyses your school's published complaints procedure via the configured policy URL.
3. It generates an objective, structured triage briefing covering:
   * **Summary of Complaint**: Synthesised overview of key allegations.
   * **Scope Assessment**: Analysis of whether the matter falls under the complaints procedure (or statutory exclusions such as admissions, exclusions, or staff grievances).
   * **Reasonableness & Proportionality**: Assessment of whether the complaint meets criteria for serial, vexatious, or unreasonable conduct.
   * **Informal Resolution Opportunities**: Identification of any remaining avenues for mediation or direct dialogue.

### Step 5: Triage Decision & Execution

The `Complaints Manager` reviews the AI triage output and selects one of four formal decisions:

> [tab] Option A: Investigate
>
> **Formal Stage 2 Investigation**
>
> * Selecting **Investigate** (with an assigned `Complaint Owner`) dispatches the `ComplaintReviewer` AI agent.
> * The AI generates a detailed **Investigator Briefing Report**, highlighting key allegations, risks, relevant regulations, and recommended lines of enquiry.
> * The `Complaint Owner` investigates, interviews relevant parties, gathers evidence, and drafts an outcome recommendation.
> * The `Complaints Manager` reviews findings and records the formal outcome (*Upheld*, *Partially Upheld*, or *Not Upheld*) along with mandatory outcome reasoning.
> * An automated outcome notification is dispatched to the complainant.

> [tab] Option B: Informal Resolution
>
> **De-escalation & Direct Engagement**
>
> * The AI automatically generates a customised, constructive draft response letter proposing specific informal resolution steps.
> * The manager reviews, edits, and dispatches the response via email directly from the dossier with one click.

> [tab] Option C: Out of Scope
>
> **Statutory or Policy Redirection**
>
> * The AI drafts a formal response letter explaining why the complaint falls outside the school's complaints procedure (e.g. subject to separate appeals machinery) and signposts appropriate channels.
> * The manager reviews and sends the letter.

> [tab] Option D: Unreasonable / Vexatious
>
> **Policy Application & Closure**
>
> * The AI drafts a formal response citing the specific clauses of your published complaints policy governing unreasonable or persistent complaints.
> * The manager reviews, confirms, and dispatches the formal decision.

***

## Stage 3: Review Panel Workflow

If a complainant remains dissatisfied after receiving the Stage 2 outcome, they may request escalation to a Stage 3 Review Panel.

### Step 1: Initiating Stage 3

1. On the complaint row or dossier, a `Complaints Manager` selects **Start Stage 3 Review**.
2. The system updates the status to *Stage 3 Open* and notifies the complainant via email that Stage 3 has been initiated.

### Step 2: Complainant Stage 3 Submission

The complainant accesses `/complaint` and submits:

* **Reasons Stage 2 Outcome Was Unsatisfactory**: Specific grounds of appeal explaining where the Stage 2 investigation was procedurally flawed, incomplete, or unreasonable.
* **Stage 3 Action Requested**: Desired outcome from the panel.

### Step 3: Stage 3 School Notes & AI Triage

1. School leadership inputs **Stage 2 Unsatisfactory Notes** and **Stage 3 Action Requested Notes**.
2. The manager clicks **Submit for Triage**. The `ComplaintStage3Triager` AI evaluates the appeal grounds against published Stage 3 criteria.

### Step 4: Stage 3 Triage Decision

The `Complaints Manager` evaluates the AI triage recommendations and chooses the appropriate path:

> [tab] Proceed to Review (Investigate)
>
> **Review Panel Hearing**
>
> * Selecting **Investigate** confirms that the appeal warrants formal review.
> * The system activates the **Stage 3 Review Outcome** card and the **Stage 3 Outcome Reason** tab on the dossier, and dispatches an automated notification email to the complainant confirming that the appeal has been accepted for formal review.
> * School governors and panel members convene to review evidence, hear representations, and determine findings.

> [tab] Out of Scope / Unreasonable
>
> **Formal Appeal Rejection**
>
> * Selecting **Out of Scope** or **Unreasonable** dispatches the specialised AI agent to draft a formal response letter explaining why a review panel will not be convened.
> * The manager reviews and edits the draft in the **Stage 3 Response** tab and clicks **Send Response** to dispatch the decision directly to the complainant with an automated email.

### Step 5: Recording Stage 3 Review Outcome & Decision

Once the panel has concluded its hearing and reached a determination:

1. **Enter Outcome Rationale**: The manager navigates to the **Stage 3 Outcome Reason** tab in the dossier and enters the comprehensive panel findings, conclusions, and recommended actions using the rich text editor.
2. **Select Outcome**: In the **Stage 3 Review Outcome** card, the manager selects the formal decision:
   * **Upheld**: The appeal was substantiated in full, with panel recommendations recorded.
   * **Partially Upheld**: Key elements of the appeal were validated while others were not substantiated.
   * **Not Upheld**: The Stage 2 investigation and outcome were found to be robust, fair, and in accordance with school policy.
3. **Confirm & Finalise**:
   * The manager clicks **Save**. A confirmation modal prompts the manager to verify that the outcome text is accurate and complete before finalising.
   * Confirming locks the outcome reason and decision from further edits and records the completion timestamp.
   * An automated outcome notification email is dispatched to the complainant with the complete, updated PDF complaint report attached (including both Stage 2 and Stage 3 outcomes and reasons), copied to the school complaints inbox and bcc'd to the investigating owner.

***

## Status & Progression Glossary

> [accordion] Opened
>
> Initial record created by school staff. The complainant has been notified and granted access to the external portal, but has not yet submitted formal Stage 2 details.

> [accordion] Submitted
>
> The complainant has completed and submitted their formal Stage 2 statement. The complaint is awaiting internal staff notes and AI triage.

> [accordion] Stage 2 Triaged
>
> AI triage has evaluated the submission against the published complaints policy and internal notes. The manager is ready to decide whether to investigate or dispatch an initial response.

> [accordion] Upheld
>
> Formal investigation or Stage 3 review concluded. The complaint or appeal was substantiated in full, with corrective actions or remedies recorded.

> [accordion] Partially Upheld
>
> Formal investigation or Stage 3 review concluded. Specific elements of the complaint or appeal were validated while others were unsubstantiated.

> [accordion] Not Upheld
>
> Formal investigation or Stage 3 review concluded. The investigation or panel review found no evidence of wrongdoing or failure to follow school procedures.

> [accordion] Stage 3 Open
>
> A Stage 3 review has been authorised by the Complaints Manager. The complainant has been invited to submit their grounds of appeal.

> [accordion] Stage 3 Requested
>
> The complainant has submitted their formal Stage 3 appeal statement. The appeal is awaiting school notes and Stage 3 triage.

> [accordion] Stage 3 Triaged
>
> Stage 3 triage has been completed, evaluating whether the appeal meets criteria for a review panel hearing.

***

## Evidentiary Dossiers & PDF Generation

At any point during Stage 2 or Stage 3, staff can click **Export to PDF** (or **Print Complaint**):

* **Complete Evidential Dossier**: Generates a clean, paginated PDF document including:
  * Complainant details and submission timestamps.
  * Formal statements and requested remedies across Stage 2 and Stage 3.
  * Internal staff investigation notes and appeal notes.
  * AI triage summaries, policy analysis, and investigator briefings.
  * Formal Stage 2 and Stage 3 outcome determinations, dates, and recorded outcome reasons.
* **Panel Packs**: Perfect for distributing confidential hearing packs to panel members and trust officers.

***

## Automated Notification & Digest Schedule

| Event / Trigger | Recipient | Content |
| :- | :- | :- |
| **Complaint Created** | Complainant | Reference number, portal login link, and OTP access instructions. |
| **Owner Assigned** | Complaints Owner | Notification that they have been assigned to investigate a complaint. |
| **Complaint Submitted** | Complainant & Managers | Confirmation of receipt and alert to managers to begin triage. |
| **Response Dispatched** | Complainant | Formal letter regarding informal resolution, scope, or reasonableness (Stage 2 or Stage 3). |
| **Investigation / Review Concluded** | Complainant | Formal Stage 2 or Stage 3 outcome (*Upheld*, *Partially Upheld*, *Not Upheld*) and written justification with attached PDF report. |
| **Stage 3 Opened** | Complainant | Notice that Stage 3 review is open and invitation to submit appeal grounds. |
| **Stage 3 Submitted** | Complaints Manager | Alert that Stage 3 appeal statement has been submitted. |
| **Stage 3 Review Initiated** | Complainant | Confirmation that the appeal is proceeding to formal panel review. |
| **Weekly Digest (Monday 08:00)** | Managers & Owners | Summary of active, pending, and overdue complaint actions. |
| **Missing Manager Alert** | Administrators | Alert sent when module is enabled but no `Complaints Manager` is assigned. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.