AI Copilot

What. A side-drawer assistant that reads the current entity, chats about it, and proposes artifacts (CAPAs, controls, modules, approval chains) you approve before they land in the system. Where. Inline buttons throughout the app (Draft CAPA, Suggest Controls, Generate Checklist, etc.) and the Approval Center at /ai/approvals.

Two surfaces

1. The Copilot drawer

Opens contextually:

• On a Finding: Analyze Root Cause, Draft CAPA, Find Similar.
• On a Requirement: Suggest Controls, Suggest Evidence.
• On an Audit: Generate Checklist, Suggest Evidence, Draft Report.
• On a Standard module page: Build Module with AI.
• On a Process / Document: Summarize, Check Compliance, Suggest Improvements.

Inside the drawer:

• A scrolling chat with prior messages.
• An input box at the bottom for free-form questions.
• Inline action buttons rendered by the AI when it has a structured proposal ready.

2. The Approval Center (/ai/approvals)

Every AI proposal queues here. Filter by status: All / Pending / Approved / Rejected / Executed / Failed.

Each card shows: title, risk level, action count, created date. Click into the card → detail view with the proposed payload (you can edit fields), then Approve (writes to DB) or Reject (closes without writing).

Provenance. Every artifact created by an approved AI proposal stores source_proposal_id linking back to the original proposal row. So a CAPA created via Copilot links back to the Copilot session that proposed it.

Common flows

Draft a CAPA from a Finding

1. Open the finding detail.
2. AI Assistant strip → Draft CAPA.
3. Drawer opens with a chat showing the AI's analysis: title, description, root cause draft, corrective + preventive action.
4. The AI says: "I've prepared 1 action(s) for your approval: 1. Create CAPA: …"
5. Open /ai/approvals → click the new pending proposal.
6. Review the payload (title, priority, root cause, actions, due date). Edit any field.
7. Click Approve. CAPA materializes in /capa with source_proposal_id = <proposal.id>.

Suggest controls for a requirement

1. Open /library → drill to a requirement.
2. Suggest controls in the drawer.
3. The AI proposes 1-N control specs, each with title, description, frequency, evidence template.
4. Approve in /ai/approvals → controls land in /controls, linked to the requirement.

Build a module with AI

1. Open /library → Build module with AI.
2. Upload the standard PDF/DOCX. The drawer extracts text and asks for a module name.
3. The AI returns a structured outline of clauses + requirements.
4. Approve → a new entry in module_drafts. Click into it, review each clause, optionally edit, then Publish module to move into the live requirements_modules so it shows in the library.

Generate audit checklist

1. Open an audit detail.
2. Generate Checklist under AI Assistant.
3. The AI looks at the audit's standard + scope, proposes one checklist item per relevant requirement.
4. Approve → items inserted with result='pending'.

Risk levels

Every proposal has a risk level (low / medium / high) that determines:

• Card color in /ai/approvals (green / blue / red)
• Whether the proposal requires elevated role to approve

Risk is the AI's estimate of impact-if-applied; trust but verify.

Tool calls (internal)

Under the hood, the Copilot has a set of write-tools the agent can propose (it cannot directly execute):

• propose_capa
• propose_controls_for_requirement
• propose_evidence
• propose_approval_chain
• create_module

All proposals route to ai_action_proposals with actions_json describing the intended writes. The Apply step in the Approval Center deserializes actions_json and runs each write inside an RLS-protected SQL block.

Test it

• On a finding, click Draft CAPA. Drawer shows AI thinking → draft → "1 action(s) for your approval".
• Open /ai/approvals. Pending tab shows the proposal.
• Click into the proposal → review payload → click Approve.
• CAPA materializes in /capa with source_proposal_id set.
• Reject a different proposal. Status = Rejected. No artifact created.
• On a Requirement, Suggest controls → proposal queues → approve → controls appear in /controls.
• On a Standard, Build module with AI → upload sample PDF → preview shows extracted clauses → Apply → module draft created.