> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ret.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 & upload evidence"]
        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["Returned for Informal Resolution / Rejected as Out of Scope / Rejected as Unreasonable<br/>AI draft response prepared and dispatched"]
    end

    subgraph Stage3["Stage 3: Review Panel Appeal"]
        S3_1["1. Manager opens Stage 3 & evidence is re-indexed"] --> 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 the required submission fields:

* **Telephone & Address**: Verified contact details for formal correspondence.
* **Complaint Details**: A short, clear account of the incident or grievance with enough detail for the school to understand and consider it (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.

Before submitting, the complainant must confirm that they have read the complaints procedure, the complaint does not come under another procedure, all submitted details are true and accurate, and they have attempted to resolve the matter at the informal stage. All four confirmations are required before the complaint can be submitted.

At this stage, the complainant should keep their account short and succinct while providing enough information for the school to consider the complaint. If it is investigated, they will have an opportunity to provide more information if needed.

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

The complainant receives a confirmation email with the PDF report. All Complaints Managers also receive one shared notification email with the complaint PDF attached, and the configured complaints inbox is copied. If no Complaints Manager has been assigned, one manager should take responsibility for managing the complaint. Managers should review the complainant's points and arrange for notes to be added to the relevant sections of the complaint dossier.

### Step 2a: Uploading Complaint Evidence

After formal submission, staff can select **Complaint Evidence** from the complaint dossier to attach supporting documents:

* The assigned `Complaint Owner` and `Complaints Managers` can upload or delete PDF, DOC, or DOCX files up to 2 MB.
* Staff with read-only `Complaints Viewer` access can view and download evidence.
* The evidence list records who uploaded each file and can download all files for the complaint as a ZIP archive.
* Evidence stays attached to the complaint if its owner changes. Archived complaints remain viewable and downloadable, but evidence cannot be added or deleted.
* Each upload is also indexed in the complaint's AI evidence store. AI triage and review agents search relevant evidence alongside the complaint and published procedure, so staff should upload files before starting an assessment; previously generated results are not refreshed when evidence changes.

Files are stored privately and are only available through the permission-checked complaint evidence page.

Deleting evidence removes the original complaint file and its AI copy. Removing the last evidence file also deletes the AI store. Download a file first if it may be needed for later records or a hearing pack.

### 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. A Complaints Manager must be assigned in the complaint's edit modal before starting Stage 2 triage or dispatching the initial review; only users with the actual `complaints_manager` role are available for assignment.

On an active complaint, a manager can click **Edit** on the complaint page or use the edit action in the complaints list to assign the manager and Stage 2 owner. A newly assigned owner is notified. Name and email are read-only after Stage 2 submission; archived complaints must be restored before editing.

* **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:
While the Stage 2 assessment is running, a non-dismissible processing modal explains that the complaint and staff notes are being checked against the complaints procedure. It closes when the triage result is available.

1. The AI evaluates the complainant's submission alongside the school's internal notes.
2. It searches relevant complaint evidence when the AI evidence store is configured.
3. It fetches and analyses your school's published complaints procedure via the configured policy URL.
4. 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:

For the three non-investigation decisions, the complaint status changes as soon as the manager confirms the decision. While the response is being prepared, the status date falls back to the formal submission date (or complaint creation date if there is no submission date); once the response is sent, the status date reflects that response.

> [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.
3. The AI evidence store is rebuilt from the evidence files still attached to the complaint, so Stage 3 triage and review agents can search them.

### 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 and relevant complaint evidence 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.

After the final Stage 2 investigation or Stage 3 panel outcome notification is sent, the AI evidence copies and store are removed. The original evidence files remain attached to the complaint for future reference. This cleanup applies to formal investigation and panel outcomes, not the separate draft responses sent after a triage decision.

***

## 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**: Export the complaint PDF for panel members and trust officers, then download the evidence files separately from **Complaint Evidence**; uploaded documents are not embedded in the PDF dossier.

***

## 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; all Complaints Managers in one email, with the complaints inbox copied | Confirmation to the complainant; managers receive a complaint PDF, a link to the dossier, and instructions to take responsibility and arrange notes. |
| **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.