# System Requirements Specification — Breakdown Reporting Module (PIR / RCA / CAPA)

**GPS Renewables · Operations & Maintenance Technology**

| Field | Detail |
|---|---|
| Document type | System Requirements Specification (functional spec) |
| Version | **Draft v0.1** |
| Derived from | Interactive design build `Breakdown Reporting.dc.html` |
| Date | 23 August 2026 |
| Status | For review |
| Classification | Confidential · Internal |
| Related documents | SRS — Maintenance Management Platform (Draft v0.3): the Breakdown module is a **producer of activities** into that platform (its `FR-EXT-01/02`, origin = Breakdown) |

---

## 1. Introduction

### 1.1 Purpose
Define the requirements for the **Breakdown Reporting module**: the workflow used to report a plant breakdown, record the immediate response, run a Root Cause Analysis (RCA) where warranted, and track the corrective actions through to closure. It formalises what the Maintenance Management Platform's SRS calls the "Breakdown module" — an upstream source of maintenance activities with its own investigation and approval workflow.

### 1.2 Scope
Covers: raising a **Preliminary Inspection Report (PIR)** for a breakdown, the seven-stage investigation lifecycle, recording the immediate corrective measure, the 5-Why RCA with central-team approval, creating and tracking **corrective actions** (which become activities on the Maintenance Platform) and non-gating **general tasks**, a dashboard of leading/lagging KPIs, and role-based access across the plant and central organisation.

### 1.3 Out of scope
The Maintenance Platform's own activity/equipment/PM machinery (specified in its own SRS) — this document specifies only the **handoff**: a corrective action created here becomes an Activity there, origin = Breakdown. Also out of scope: SSO/identity (shared with the Maintenance Platform), email delivery, file storage backend, and any production incident/HSE reporting system this module might one day sit alongside.

### 1.4 Status & priority legend
**Priority (MoSCoW):** `Must` · `Should` · `Could` · `Won't (now)`.

**Build status:** `Built` (implemented and matches intent) · `Partial` (partly implemented) · `Open` (specified, not yet built).

---

## 2. Product overview

### 2.1 Design principles

| Principle | What it means |
|---|---|
| **Report first, investigate second** | Raising a PIR is a low-friction, single form. The investigative rigor (immediate action, RCA, approval) is layered on afterward by the assigned engineer, not demanded up front. |
| **RCA is a gate, not a formality** | If an RCA is required, no corrective action can be created against the PIR until the central team approves it — corrective actions cannot outrun root-cause understanding. |
| **General tasks never block closure** | Follow-ups that aren't equipment fixes (process updates, training, procurement) are tracked but explicitly excluded from the PIR's closure condition. |
| **Closure is automatic, not clicked** | A PIR closes itself the moment every corrective action against it is done and (if required) the RCA is approved — no separate "close" button exists. |
| **One record, one story** | Every PIR carries its own activity log — reported, immediate action, RCA milestones, reassignment, cancellation — in one place. |
| **The Maintenance Platform owns execution** | Corrective actions are created here but worked and closed on the Maintenance Platform as ordinary activities; this module only tracks their status back. |

### 2.2 Users & roles
Same six roles as the Maintenance Platform (shared identity in production).

| Role | In this module |
|---|---|
| **Shift In Charge** | Raises PIRs at the point of breakdown; can reassign the investigating engineer. |
| **Maintenance Engineer** | Owns the investigation once assigned: reviews, records immediate action, runs the RCA, creates corrective actions. |
| **Plant Manager** | Can cancel a PIR; owns general tasks alongside the central team. |
| **Central Team** | Approves or rejects RCAs; owns general tasks; can reassign and cancel. |
| **Portfolio Manager** | Implicit read-only oversight (no write permissions granted anywhere in the permission model). |
| **Admin** | All capabilities. |

### 2.3 The PIR lifecycle
A Preliminary Inspection Report moves through seven ordered stages, plus a terminal **Cancelled** state reachable from any open stage:

1. **Reported** — raised, awaiting review.
2. **Under Review** — the assigned engineer has started looking at it.
3. **Immediate Action** — the immediate corrective measure is being recorded; this is also where "is an RCA required?" is decided.
4. **RCA In Progress** — a 5-Why analysis is being built and submitted for approval (skipped entirely if RCA is not required).
5. **RCA Approved** — the central team has signed off the root cause and proposed actions (skipped if RCA is not required).
6. **CAPA** — corrective actions are open and being worked.
7. **Closed** — every corrective action is done and (if applicable) the RCA is approved. Reached automatically.

The stage rail visually strikes through RCA-related stages when RCA has been marked not required, rather than hiding them, so the record shows the decision was made rather than skipped by omission.

### 2.4 Screen inventory

| # | Screen | Purpose | Priority | Status |
|---|---|---|---|---|
| S1 | Dashboard | Leading/lagging KPIs, breakdowns by equipment/type, severity mix, overdue corrective actions. | Must | `Built` |
| S2 | Breakdowns (PIR list) | Sortable, filterable list of all PIRs. | Must | `Built` |
| S3 | PIR detail | The investigation record: report, immediate action, RCA, linked corrective actions, general tasks, activity log. | Must | `Built` |
| S4 | RCA Approvals | Queue of RCAs awaiting central-team decision. | Must | `Built` |
| S5 | General Tasks | Cross-PIR list of non-gating follow-ups, filterable by assignee. | Should | `Built` |

Supporting modals: Raise PIR (S6), Record immediate action (S7), Create corrective action / general task (S8), Cancel PIR (S9), Approve/reject RCA (S10).

---

## 3. Functional requirements

### 3.1 Raising and listing — `FR-PIR`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-PIR-01 | Shift In Charge / Maintenance Engineer / Admin shall raise a PIR via a guided form: equipment, date & time of incident, title (required), description, type (Mechanical/Electrical/Instrumentation/Process/Civil/Utility/Safety/Environmental), severity (None…Catastrophic), CBG-impact flag, assigned engineer (required), and an optional note on immediate action already taken. | Must | `Built` |
| FR-PIR-02 | A PIR shall be assigned to exactly one Maintenance Engineer at creation and land on its detail screen immediately after raising. | Must | `Built` |
| FR-PIR-03 | The Breakdowns list shall be filterable by stage, severity, and type, toggleable to "assigned to me", searchable by title/equipment/PIR ID/engineer, and sortable on every primary column. | Must | `Built` |
| FR-PIR-04 | Each list row shall show a CAPA-completion indicator (corrective actions done / total) at a glance. | Should | `Built` |
| FR-PIR-05 | Shift In Charge, Central Team, or Admin shall be able to **reassign** the investigating engineer at any time before closure. | Should | `Built` |
| FR-PIR-06 | Plant Manager, Central Team, or Admin shall be able to **cancel** an open PIR with a mandatory reason; the record is retained for audit but leaves the active workflow and can no longer take new corrective actions or general tasks. | Must | `Built` |

### 3.2 Lifecycle & stage control — `FR-WF`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-WF-01 | A PIR shall carry a **stage** from the ordered set in §2.3, shown as a breadcrumb rail on detail and a column in the list. | Must | `Built` |
| FR-WF-02 | Roles with `setStage` permission (Plant Manager, Shift In Charge, Maintenance Engineer, Central Team, Admin) shall be able to **manually override** the stage from a dropdown on the header, independent of the guided action buttons. | Should | `Built` |
| FR-WF-03 | The header shall present **one contextual primary action** per stage for the assigned engineer (Start review → Record immediate action → Start RCA / Create corrective action), so the expected next step is always obvious. | Should | `Built` |
| FR-WF-04 | A PIR shall **auto-close** the instant its RCA (if required) is approved and every corrective action against it is marked Done — no manual close action exists. | Must | `Built` |
| FR-WF-05 | Cancellation shall be reachable from any stage prior to Closed/Cancelled and shall require a free-text reason, visible on the record thereafter. | Must | `Built` |

### 3.3 Immediate action — `FR-IMM`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-IMM-01 | The assigned engineer shall record the **immediate corrective measure** taken to make the plant/equipment safe, as free text, with author and timestamp captured automatically. | Must | `Built` |
| FR-IMM-02 | Recording immediate action shall require a decision — **"Is an RCA required?"** (Yes/No) — which determines whether the RCA stages are exercised or skipped for this PIR. | Must | `Built` |
| FR-IMM-03 | Immediate action shall be editable after first entry (re-opens the same form pre-filled). | Should | `Built` |

### 3.4 Root Cause Analysis — `FR-RCA`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-RCA-01 | When RCA is required, the record shall present a **5-Why** grid (five Why/Because rows), a root-cause category (single-select from a fixed list), free-tag **contributing factors**, and proposed **medium-term** and **long-term** actions as text. | Must | `Built` |
| FR-RCA-02 | An RCA document (e.g. PDF) shall be attachable to the record. | Should | `Built` (attach is simulated) |
| FR-RCA-03 | The RCA shall carry a status: **Draft → Awaiting approval → Approved**, or **Sent back** (rejected, returns to Draft-equivalent editable state). Only Draft/Sent-back is editable by the engineer. | Must | `Built` |
| FR-RCA-04 | Submitting an RCA shall require choosing an **approver** (a Central Team member) and shall notify that approver's queue (RCA Approvals). | Must | `Built` |
| FR-RCA-05 | Central Team / Admin shall **approve** (optional comment) or **reject** (mandatory reason) a pending RCA from the approvals queue or from the PIR itself. | Must | `Built` |
| FR-RCA-06 | Approving an RCA shall unlock corrective-action creation on that PIR; rejecting shall return it to the engineer with the reason visible on the record. | Must | `Built` |
| FR-RCA-07 | Time from report to RCA submission shall be tracked in days and measured against a configurable target (default 7 days) for the dashboard KPI. | Should | `Built` |

### 3.5 Corrective actions & general tasks — `FR-CAPA`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-CAPA-01 | A **corrective action** shall only be creatable once the PIR either does not require an RCA, or its RCA is approved. | Must | `Built` |
| FR-CAPA-02 | Creating a corrective action shall capture title, owner, and due date, and shall create the corresponding **Activity on the Maintenance Platform** (origin = Breakdown), referenced back from the PIR. | Must | `Built` (simulated locally; real handoff is `Open`, see §7) |
| FR-CAPA-03 | The PIR shall show a **CAPA completion bar** (done / total corrective actions) and a table of linked actions with owner, due date (flagged if overdue), and status. | Must | `Built` |
| FR-CAPA-04 | The assigned engineer shall be able to **mark a corrective action done** directly from the PIR; this is the trigger that (combined with `FR-WF-04`) auto-closes the PIR. | Must | `Built` |
| FR-CAPA-05 | A **general task** — a non-corrective follow-up (process, training, procurement, cross-site) — shall be raiseable against any open PIR by Plant Manager, Central Team, or Admin, independent of RCA/CAPA gating. | Should | `Built` |
| FR-CAPA-06 | General tasks shall be visible both on their parent PIR and in a cross-PIR **General Tasks** list filterable by assignee; they shall **never** gate PIR closure. | Should | `Built` |
| FR-CAPA-07 | Corrective actions and general tasks assigned to a person other than the current owner (or Admin) shall show a **read-only status chip** rather than a "Mark done" control. | Must | `Built` |

### 3.6 Activity log — `FR-LOG`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-LOG-01 | Every state-changing action (raised, reassigned, immediate action recorded, RCA submitted/approved/rejected, corrective action created/completed, general task created, cancelled, stage overridden) shall post an **automatic system entry** with actor and timestamp. | Must | `Built` |
| FR-LOG-02 | Users with stage-control permission shall be able to post a free-text **internal note**, visually distinguished from system entries. | Should | `Built` |
| FR-LOG-03 | The log shall group entries by day and remain in reverse-chronological order; entries are not editable or deletable. | Must | `Built` |

### 3.7 Dashboard & KPIs — `FR-RPT`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-RPT-01 | The dashboard shall show four headline KPIs: **RCA-within-target %**, **CAPA closure %**, **overdue CAPA count**, and **immediate-action-within-6h %**, each with its underlying count and a progress bar. | Must | `Built` |
| FR-RPT-02 | The RCA-within-target window shall be a **configurable tweak** (default 7 days). | Could | `Built` |
| FR-RPT-03 | The dashboard shall break down breakdown counts **by equipment** (top 6) and **by type**, and show a **severity mix** bar. | Should | `Built` |
| FR-RPT-04 | The dashboard shall surface a direct list of **overdue corrective actions** across all PIRs, deep-linking to each record. | Must | `Built` |
| FR-RPT-05 | Reports shall be scoped/filterable by portfolio or site once multi-site data exists (currently single-site). | Should | `Open` |
| FR-RPT-06 | KPI data shall be exportable to spreadsheet. | Could | `Open` |

### 3.8 Access & scoping — `FR-ACC`

| ID | Requirement | Pri | Status |
|---|---|---|---|
| FR-ACC-01 | Actions not permitted to the signed-in role shall **not be rendered** (no create/edit/assign/cancel/approve controls shown), matching the Maintenance Platform's access model. | Must | `Built` |
| FR-ACC-02 | Selecting **Central Team** as the active role shall default the landing screen to **RCA Approvals**, reflecting that role's primary job in this module. | Could | `Built` |
| FR-ACC-03 | Data shall be scoped to the user's site in production; the current build is single-site (Indore Biogas Plant). | Must | `Open` |

---

## 4. Access-control matrix

`—` = not available (control not rendered).

| Capability | Shift In Charge | Maintenance Engineer | Plant Mgr | Central Team | Portfolio Mgr | Admin |
|---|---|---|---|---|---|---|
| Raise PIR | Yes | Yes | — | — | — | Yes |
| Review / record immediate action / run RCA (as assignee) | — | Yes | — | — | — | Yes |
| Reassign engineer | Yes | — | — | Yes | — | Yes |
| Cancel PIR | — | — | Yes | Yes | — | Yes |
| Override stage manually | Yes | Yes | Yes | Yes | — | Yes |
| Approve / reject RCA | — | — | — | Yes | — | Yes |
| Create corrective action (as assignee, when unlocked) | — | Yes | — | — | — | Yes |
| Create / own general task | — | — | Yes | Yes | — | Yes |
| Post internal note | Yes | Yes | Yes | Yes | — | Yes |

---

## 5. Data model / entities

| Entity | Key attributes | Relationships |
|---|---|---|
| **PIR** | id `PIR-####`, title, description, equipment, type, severity, CBG-impact flag, stage (incl. Cancelled), reported/raised date-time, immediate action text + author + time, immediate-response hours, RCA-required flag, cancel reason | → Equipment (Maintenance Platform); 1 → 1 RCA; 1 → * Corrective Action; 1 → * General Task; 1 → * LogEntry; → User (reporter, assigned engineer) |
| **RCA** | 5-Why pairs (×5), root-cause category, contributing factors[], medium-term actions, long-term actions, attached file, status (draft/pending/approved/rejected), approver, days-to-submit, decision note, decided-by | → PIR (1:1) |
| **Corrective Action** | id, title, kind = Corrective, owner, due date, status (Open/In Progress/Done) | → PIR; mirrors an **Activity** on the Maintenance Platform (origin = Breakdown) |
| **General Task** | id `GT-##`, title, linked PIR, owner, due date, status | → PIR |
| **LogEntry** | kind (system/note), icon, text, author (notes only), timestamp | → PIR |

**Cardinality:** PIR 1—1 RCA · PIR 1—∞ Corrective Action · PIR 1—∞ General Task · PIR 1—∞ LogEntry.

---

## 6. Use cases

| ID | Actor | Scenario | Requirements |
|---|---|---|---|
| UC-01 | Shift In Charge | **Report a breakdown** — raise a PIR at 3am, assign it to the on-call engineer, note what the shift team already did to make the plant safe. | FR-PIR-01/02 |
| UC-02 | Maintenance Engineer | **Investigate** — start review, record the immediate action, decide RCA is required, complete the 5-Why, submit to the central team. | FR-IMM-01/02, FR-RCA-01/04 |
| UC-03 | Central Team | **Approve or reject an RCA** — open the approvals queue, review the 5-Why and proposed actions, approve (unlocking CAPA) or send it back with a reason. | FR-RCA-05/06 |
| UC-04 | Maintenance Engineer | **Close out via CAPA** — create corrective actions once the RCA is approved, mark each done as work completes on the Maintenance Platform; PIR closes itself on the last one. | FR-CAPA-01..04, FR-WF-04 |
| UC-05 | Plant Manager | **Raise a non-corrective follow-up** — add a general task (e.g. "review compressor overhaul intervals") against a closed-adjacent PIR without blocking it. | FR-CAPA-05/06 |
| UC-06 | Plant Manager | **Cancel a duplicate PIR** — cancel with a reason; record stays for audit. | FR-PIR-06 |
| UC-07 | Anyone with dashboard access | **Check breakdown performance** — review RCA-on-time %, CAPA closure %, overdue actions, and severity mix for the last 90 days. | FR-RPT-01/03/04 |

---

## 7. External interfaces

| Interface | Type | Requirement | Notes |
|---|---|---|---|
| **Maintenance Platform** | Outbound (create/update activity) | FR-CAPA-02 | Creating a corrective action here shall create an Activity there with origin = Breakdown and a back-reference to the PIR — this satisfies the Maintenance Platform SRS's `FR-EXT-01/02/04`. **Currently simulated in local state; the real API call is `Open`.** |
| **Keycloak SSO** | Authentication | Shared with Maintenance Platform | Identity, role, and site should come from the same token; this build uses a "View as" prototype switch only. |
| **Email** | Outbound notification | — | RCA submitted-for-approval and rejected-back-to-engineer are the two events most in need of email parity; not yet specified. |

---

## 8. Non-functional requirements

| ID | Requirement | Pri | Status |
|---|---|---|---|
| NFR-SEC-01 | Authentication via Keycloak SSO, shared with the Maintenance Platform. | Must | `Open` |
| NFR-SEC-02 | Role scoping and stage gates (RCA-before-CAPA) shall be enforced **server-side**. | Must | `Open` |
| NFR-DAT-01 | RCA and log entries shall be **immutable and auditable**; cancellation retains the full record. | Must | `Built` (UI) |
| NFR-USE-01 | Copy and structure follow the same plain-language, capitalize-headings voice as the Maintenance Platform. | Must | `Built` |
| NFR-PER-01 | List and dashboard views shall remain responsive with typical single-site PIR volumes (tens per month). | Should | `Open` |

---

## 9. Requirement traceability

| Requirements | Screen(s) | Status |
|---|---|---|
| FR-RPT-01..04 | S1 Dashboard | `Built`/`Open` |
| FR-PIR-01..06 | S2 List, S6 Raise modal | `Built` |
| FR-WF-01..05, FR-IMM-01..03, FR-RCA-01..07, FR-CAPA-01..07, FR-LOG-01..03 | S3 PIR detail + S7/S8/S9/S10 modals | `Built` |
| FR-RCA-05/06 | S4 Approvals | `Built` |
| FR-CAPA-05/06 | S5 General Tasks | `Built` |
| FR-ACC-01..03 | All screens | `Built`/`Open` |

---

## 10. Assumptions & open items

| # | Item |
|---|---|
| A1 | Corrective actions and the Maintenance Platform's Activities are **the same underlying record**, viewed from two applications; this SRS assumes a real API call replaces the current simulated local update. |
| A2 | Single site (Indore Biogas Plant) in the current build; multi-site scoping mirrors the Maintenance Platform's site model. |
| O1 | **Reassignment scope** — confirm whether reassigning the engineer mid-RCA should reset or preserve in-progress RCA edits. |
| O2 | **RCA rejection loop limit** — no cap on reject/resubmit cycles is specified; confirm whether one is needed. |
| O3 | **General task ownership** — currently any of Plant Manager/Central Team/Admin; confirm whether Portfolio Manager needs read access to this list. |
| O4 | **Notification routing** — align with the Maintenance Platform's open notification-routing decision (its SRS §12 O2). |
| O5 | **RCA approver list** — currently restricted to Central Team members; confirm this holds once portfolio-level roles are involved. |

---

*End of SRS Draft v0.1 — GPS Renewables Breakdown Reporting Module. Regenerated from `Breakdown Reporting.dc.html`. For review.*