From 13cf3fe201f2b531ee7b8863e8a84005942b821d Mon Sep 17 00:00:00 2001 From: tocmo0nlord Date: Sat, 30 May 2026 20:43:10 +0000 Subject: [PATCH] Add end-to-end workflow documentation (WORKFLOWS.md) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Practical guide walking the case from intake through closed: per-stage walkthroughs (Intake → Active → Discovery → Pre-Trial → Closed), cross-cutting flows (Documents → e-Sign → e-File, AI agents comparison, time & billing, deadlines, conflict gate, portal access), roles, troubleshooting, menu map. Co-Authored-By: Claude Sonnet 4.6 --- WORKFLOWS.md | 509 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 509 insertions(+) create mode 100644 WORKFLOWS.md diff --git a/WORKFLOWS.md b/WORKFLOWS.md new file mode 100644 index 0000000..301ea52 --- /dev/null +++ b/WORKFLOWS.md @@ -0,0 +1,509 @@ +# ActiveBlue Family Law — End-to-End Workflows + +How a case moves from intake through final order, what each role does at each +stage, and which buttons / menus to click. Targets the live build on +`192.168.2.9:8069`, database `db1`. Florida 11th Circuit (Miami-Dade). + +--- + +## Stage map at a glance + +``` + Intake ─► Active ─► Discovery ─► Pre-Trial ─► Closed + │ │ │ │ │ + │ │ │ │ └─ archive, bill, retention + │ │ │ └─ pretrial stmt, exhibits, witnesses, mediation + │ │ └─ interrogatories, production, depositions + │ └─ serve, mandatory disclosure (FL 12.932), initial hearings + └─ conflict check, questionnaire, fee-waiver assessment +``` + +Move stages via the Kanban (drag) or the status bar on the case form. Each +transition automatically runs the **Paralegal agent**, which (1) generates the +stage's task batch, (2) recalculates deadlines, (3) cross-references statutes +to the case's issue tags, and (4) posts a chatter summary. + +The case **cannot leave Intake until the conflict-of-interest check passes** +(or an administrator overrides it with a written justification). + +--- + +## One-time configuration (before your first case) + +Settings → Technical → System Parameters: + +| Key | Value | Used by | +|---|---|---| +| `fl_ai.claude_api_key` | `sk-ant-…` | AI engine, Paralegal agent, Attorney agent | +| `fl_timesheet.default_hourly_rate` | e.g. `350` | Time & Billing totals when employee has no rate set | +| `fl_efiling.portal_url` | `https://eportal.flcourts.org` (default) | Open e-Filing Portal button | +| `web.base.url` | your Odoo base URL | Signing-portal link in emails | + +Per-employee: open the employee record, set **Family Law Billing Rate ($/hr)**. + +Python dependencies in the container (already required by code paths): +`anthropic`, `pikepdf`, `PyMuPDF`. Install with +`docker exec -u root odoo-web-1 pip install anthropic pikepdf PyMuPDF`. + +--- + +## STAGE 1 — Intake + +**Goal:** capture parties, screen for conflicts, decide if pro se vs attorney +referral, assess fee-waiver eligibility, identify legal issues. + +### 1.1 Create the case + +Two paths: + +- **Family Law → Cases → New Case (Intake Wizard)** — guided form covering + case type, parties, children, basic facts. +- **Family Law → Cases → All Cases → New** — direct creation of `fl.case`. + +Required at create time: `case_type` and `petitioner_id`. `respondent_id` is +strongly recommended (drives conflict screening and downstream service). + +### 1.2 What the system does automatically on create + +1. **Conflict-of-interest check** runs first + - Compares petitioner / respondent / party names against parties on every + other open case (folded stages excluded). + - Exact partner-id match → instant conflict. Otherwise fuzzy match + (difflib ≥ 0.85). + - Conflict found → red banner on the case, Kanban "Conflict" badge, + `conflict_check_passed = False`, **case is locked at Intake**. + - Clear → `conflict_check_passed = True`, case can advance. + +2. **Project auto-created** with case-type task templates. + +3. **Paralegal agent** generates the Intake task batch: + - Run conflict-of-interest check (the audit record) + - Complete client intake questionnaire + - Assess fee-waiver eligibility (FL 57.082) + +4. **Fee waiver eligibility** computed quickly from petitioner income vs + 200% FPL; chatter note if eligible. + +5. **DV flag** (if set) posts a safety banner with mediation/representation + guidance and the Miami DV hotlines, forces `attorney_referral_flag`. + +### 1.3 Resolving a flagged conflict + +Open the conflict check record from the case's "Conflict of Interest" group +(Parties tab) or via **Cases → Conflict Checks**. + +- Review the match list and similarity scores. +- If proceeding is safe, an **administrator** writes a justification and + clicks **Override Conflict** → state becomes "override", + `conflict_check_passed = True`, audit entry posted to chatter. +- Never silently pass a conflict — the override leaves a permanent record. + +### 1.4 Fill in the questionnaire (Parties tab) + +For each party (One2many "Party Details"): + +- Employment type and gross monthly income. +- Statutory deductions (federal tax withholding, mandatory retirement, + health insurance self-only, other court-ordered support) → Odoo computes + net monthly income per FL 61.30(3). +- **Income imputation** (FL 61.30(2)(b)) if voluntarily un/under-employed — + set `income_imputed`, an imputed amount, and document the basis. +- **Lifestyle inconsistency** flag if income vs lifestyle is suspect + (Barner v. Barner) — Attorney agent will incorporate this. + +### 1.5 Run the AI passes + +- **Paralegal Review** (header button) — Claude procedural briefing + (best-effort; falls back to a rule-based summary if the API is unavailable). + Useful to see "what should we be doing now?" at any time. +- **AI tab → Generate Attorney Strategy Memo** (admin) — substantive memo. + Identifies the top 3–5 statutes and case law (from the seeded library only, + no hallucinated citations), drafts petitioner arguments, opposing + counterarguments, procedural risks, and a substantial-change assessment for + modifications. Stored as `fl.analysis` of type "attorney", linked from + `case.attorney_memo_id`. + +### 1.6 Advance to Active + +Drag the case to **Active** on the Kanban (or click the status bar). If +`conflict_check_passed` is still False you'll get a blocking error — go back +and resolve the conflict. + +--- + +## STAGE 2 — Active + +**Goal:** serve the respondent, exchange mandatory disclosure, schedule the +initial hearings, generate and file the petition. + +### 2.1 Automatic on stage entry + +Paralegal agent generates the Active task batch: + +- Effect service of process +- Serve mandatory disclosure (FL-12.932) within 45 days of service +- Schedule initial hearings (case management, temporary relief) + +### 2.2 Filing date and service date drive deadlines + +Set `filing_date` on the case → deadline engine generates filing-anchored +deadlines (30-day target service, 120-day FL 1.070 max service, parenting +class for petitioner if minor children). + +Set `service_date` → service-anchored deadlines are generated/recalculated: + +| Deadline | Offset | Statute | +|---|---|---| +| Respondent answer due | service + 20 days | FL 1.140 | +| Mandatory disclosure exchange | service + 45 days | FL 12.285 | +| Certificate of mandatory disclosure | service + 45 days | FL 12.932 | +| Discovery opens | service + 20 days | FL 12.280 | +| Respondent parenting class | service + 60 days | FL 61.21 | + +Each `fl.deadline` syncs to a `calendar.event` (visible in the case's +Deadlines tab and on the user's calendar). Daily cron sends 7/3/1-day and +overdue alerts to the case chatter. + +### 2.3 If respondent doesn't answer by day 20 + +A daily cron (FL 12.922 / FL 1.500) automatically: + +1. Creates a "File Motion for Default" deadline (5 days out). +2. Adds an urgent project task with filing instructions. +3. Posts a "DEFAULT JUDGMENT WINDOW OPEN" alert to the case chatter. + +### 2.4 Generate and file court documents + +Each case document maps to a QWeb PDF report: + +| Document | Form | Menu / Action | +|---|---|---| +| Financial Affidavit (Short) | FL-12.902(b) | Reports → on `fl.document` | +| Financial Affidavit (Long) | FL-12.902(c) | "" | +| Child Support Worksheet | FL-12.902(e) | "" | +| Motion to Modify | — | "" | +| Notice of SSN | FL-12.930(a) | "" | +| Mandatory Disclosure Certificate | FL-12.932 | "" | +| Notice of Deposition | — | "" | +| Motion to Compel | FL 1.380 | "" | +| Income Withholding | FL 61.1301 | "" | +| Parenting Plan | FL-12.995(a) | "" | +| Application for Civil Indigent Status | FL 57.082 | "" | +| Motion for Default | FL 12.922 | "" | + +To get a signed, filed PDF, use **Filings tab → Request Signature** then +**Prepare e-Filing** (full walkthrough in *Cross-cutting flows: Documents → +e-Sign → e-File* below). + +### 2.5 Fee waiver application + +If the case shows "Fee Waiver Potentially Eligible" (200% FPL test), open the +Fees & Expenses tab → **Create Fee Waiver Application**. Complete household +size and income; eligibility is computed against the FL 57.082 threshold and +the document flows through draft → submitted → approved/denied. Generate the +QWeb PDF and file with the clerk. + +### 2.6 Move to Discovery when ready + +Drag to **Discovery** when initial service + mandatory disclosure are in +hand and you need formal discovery. Typically also after the Attorney agent +has rated complexity as `medium` or higher. + +--- + +## STAGE 3 — Discovery + +**Goal:** Interrogatories, requests for production, depositions, motions to +compel as needed. + +### 3.1 Automatic on stage entry + +Paralegal agent generates the Discovery task batch: + +- Draft interrogatories +- Draft requests for production +- Schedule depositions where income or facts are disputed + +### 3.2 Discovery Suggest wizard + +From the case → **Run Discovery Suggest Wizard** (or Cases → Discovery → +specific tools). The wizard reads: + +- Case's issue tags (`issue_tag_ids`) +- Complexity (from the latest analysis or rule-based fallback) +- Active flags (DV, income imputation, respondent has counsel) + +…and proposes a tailored discovery package: interrogatory sets directed to +the opposing party, document requests, deposition notices, third-party +subpoenas (e.g., employer when income is disputed). + +Each selected line creates an `fl.discovery` item linked to the case. The +wizard posts a chatter summary of everything generated. + +### 3.3 Discovery items lifecycle (`fl.discovery`) + +- States: draft → served → responded → complete (or → motion-to-compel / + deemed-admissions when overdue). +- 30-day response clock from service; **daily cron** fires alerts for overdue + responses and flags admissions deemed under FL 1.370 when the deadline lapses. +- Track objections and motion-to-compel status per item. + +### 3.4 Depositions (`fl.deposition`) + +- States: draft → noticed → confirmed → completed (or cancelled / no-show / + continued). +- **Notice validity** is computed (FL 1.310(b): ≥10 days notice). Search + filters expose "Invalid Notice" — fix before serving. +- Duces tecum (document subpoena): tracked separately. +- Generate the Notice of Deposition PDF and route through e-Sign / e-File. + +### 3.5 Move to Pre-Trial + +When discovery is essentially closed (responses in, depositions taken or +waived), advance the stage. + +--- + +## STAGE 4 — Pre-Trial + +**Goal:** Pretrial statement, exhibits, witnesses, mediation, support +calculation, parenting plan, threshold test for modifications. + +### 4.1 Automatic on stage entry + +Paralegal agent generates the Pre-Trial task batch: + +- Prepare pretrial statement +- Compile exhibit list +- Compile witness list +- Schedule mediation (separate rooms if DV flagged — FL 44.102) + +### 4.2 Child support calculation (FL 61.30) + +Open **Case → Open Calculator** (or AI tab → Calculator stat button). + +- Pulls petitioner / respondent effective monthly income (uses imputed if set). +- Children, day-care, health insurance for children, tax exemption assumptions. +- **Substantial timesharing** kicks in when either parent has > 73 overnights + (FL 61.30(11)(b)) — automatically detected from `petitioner_overnights`. +- Result → `case.calculated_support`. + +For **modifications**, the Support tab also runs the threshold test +(FL 61.30(1)(b)): change must be both ≥ $50 AND ≥ 15%. The case shows a clear +"QUALIFIES" / "DOES NOT QUALIFY" panel with the math. + +### 4.3 Mediation scheduling + +Add `fl.hearing` of type "Mediation" (Hearings tab). If `domestic_violence_flag` +is set, you get a separate-rooms reminder. Court-ordered mediation is the +default in family law cases (FL 44.102). + +### 4.4 Pretrial statement, exhibit and witness lists + +Use the project tasks generated by the paralegal agent as the checklist. +Documents and exhibits go through the standard Documents → e-Sign → e-File +flow. + +### 4.5 Move to Closed when the final order is entered + +--- + +## STAGE 5 — Closed + +**Goal:** Capture the new order, generate income withholding, reconcile +billing, archive the case, send retention notice. + +### 5.1 Automatic on stage entry + +Paralegal agent generates the Closed task batch: + +- Complete archive checklist +- Reconcile billing +- Send file retention notice + +### 5.2 Post-order: income withholding (FL 61.1301) + +Set `new_order_amount` and `new_order_date` on the case → an +`fl.income.withholding` record is auto-created (mandatory under FL 61.1301 +unless good cause or written agreement). Generate the Income Withholding PDF +and serve. + +`retroactivity_date` is computed = `filing_date` (FL 61.30(17)). + +### 5.3 Reconcile billing + +Time & Billing tab shows: + +- `total_billable_hours` — sum of billable timesheet entries +- `total_billable_amount` — billable hours × rate +- `total_ai_audit_hours` — non-billable AI agent time (for audit trail) + +Add manual time entries inline (date, who, hours, description, billable). +The wrapped `account.analytic.line` records flow into standard Odoo +Accounting for invoicing. + +### 5.4 File retention notice + +Use the Document workflow to generate a closing letter to the client with +the retention/destruction policy. + +--- + +## Cross-cutting flows + +### A. Documents → e-Sign → e-File + +The "paperwork pipeline" — every court document follows the same path. + +1. **Generate** the document. From the case Documents area (Filings tab or + `fl.document` form), pick the document type (e.g., Financial Affidavit + Long). Use **Print → [Report]** to render the QWeb PDF, or the document + auto-renders when a signature request is created. + +2. **Request Signature** (Filings tab → "Request Signature" button). On the + `fl.signature.request` form: + - Pick the document and signer (`signer_partner_id`). + - Click **Render PDF** to generate the unsigned PDF (or skip — clicking + "Send to Signer" will render automatically). + - Click **Send to Signer**. An email goes out with a one-time link + `https:///familylaw/sign/` (token is 256-bit; expires + in 14 days; cron sweeps expired links hourly). + +3. **Signer signs** at the portal page (no login required): + - The unsigned PDF is shown in an iframe. + - The signer draws on the HTML5 canvas pad (mouse/trackpad/finger). + - "Submit Signature" posts the PNG to the server; PyMuPDF embeds it at + the per-report `_SIGNATURE_COORDS` rectangle. + - The signed PDF is attached to the `fl.document` (state → "signed"); the + request state → "signed"; case chatter logs the event with signer IP. + + The signer can also Decline with an optional reason; the request closes. + +4. **Re-validate PDF/A** on the signed PDF (signature form has a button) if + it's bound for e-filing. Uses the same `pikepdf` check as the e-Filing + model. + +5. **Prepare e-Filing** (Filings tab → "Prepare e-Filing"). The wizard: + - Picks the signed PDF (or any attachment). + - Generates the 11th Circuit-compliant filename: + `{LastName}_{CaseNumber}_{DocType}_{YYYYMMDD}.pdf`. + - Auto-validates PDF/A. + +6. **Submit on the FL e-Filing Portal**. From the `fl.efiling.submission` + form: + - Click **Open e-Filing Portal** — opens `eportal.flcourts.org` in a new + tab, deep-linked with the case number if available. + - Upload the signed PDF on the portal, complete the filing, copy the + portal confirmation #. + - Back in Odoo, paste the confirmation # and click **Mark Submitted**. + - When the clerk acts, click **Clerk Accepted** (which also marks the + `fl.document` as filed) or **Clerk Rejected** (note the reason). + +The Submit via API button is reserved for Phase 2 and currently refuses to +call any unconfirmed endpoint — assisted submission is the supported flow. + +### B. AI agents — when to use which + +| Agent | Trigger | What it produces | Cost | +|---|---|---|---| +| **Paralegal — auto** | Every stage transition (including case creation) | Stage task batch, deadline recalc, statute cross-ref, rule-based chatter summary | No AI call | +| **Paralegal — manual** ("Paralegal Review" button) | On demand | Same as above + Claude procedural briefing | 1 Claude call | +| **AI Engine** ("Run AI Analysis" header → wizard) | On demand | Rule-based issue tagging + caselaw matching + Claude case-summary analysis (`fl.analysis` type `engine`) | 1 Claude call | +| **Attorney — manual** (AI tab → "Generate Attorney Strategy Memo") | On demand, admin | Substantive strategy memo: top 3–5 statutes (linked to `fl.statute`), top 3–5 case law (linked to `fl.caselaw`), petitioner arguments + opposing counterarguments, risk narrative, substantial-change assessment, attorney-referral flag | 1 Claude call (longer prompt) | + +All agents log non-billable audit time to `fl.timesheet` (`ai_agent` field +identifies which agent) and fall back to rule-based output if Claude is +unavailable. AI failures never block the user workflow. + +### C. Time & Billing + +- **Manual entry**: Case → Time & Billing tab → add row. Date, employee, + hours, billable flag, description. +- **AI audit time**: posted automatically by each agent run (paralegal ~0.05h + AI / 0.01h rule-based; attorney ~0.1h AI / 0.02h fallback). Marked + non-billable; visible in the same tab and on the **Cases → Timesheets** + list (filter: AI Audit). +- Rate resolves to `hr.employee.fl_hourly_rate` (per person) or the firm + default param. +- Each timesheet entry wraps an `account.analytic.line`, so it shows up in + Odoo Accounting and flows into invoicing in the usual way. + +### D. Deadlines & calendar + +- Defined in `fl.deadline`; each one syncs to a `calendar.event` (default 1h + block at 08:00). +- Decoration in the Deadlines tab: red for overdue, yellow for ≤ 7 days. +- Daily cron posts 7-day, 3-day, 1-day, and overdue alerts to the case chatter. +- The case header shows "Next Deadline" and "Overdue Deadlines"; the Kanban + card shows the count. + +### E. Conflict-of-interest gate + +- Runs on case creation. Also accessible via header **Run Conflict Check**. +- Admin override only, with a written justification (audit-logged). +- Visible globally under **Cases → Conflict Checks** (default filter: open + conflicts). + +### F. Portal access (clients) + +Petitioner / respondent users (groups `group_portal_petitioner` / +`group_portal_respondent`) can sign in and see: + +- `/my/cases` — their case(s) +- `/my/cases/` — case detail with deadlines and timeline +- `/my/cases/calculator` — interactive FL 61.30 calculator +- `/my/cases/caselaw` — searchable FL case law library + +To grant portal access, on the party record (Parties tab → party row) link a +`partner.user_ids` to that party's partner. + +--- + +## Roles — who does what + +| Role | Group | Typical day | +|---|---|---| +| Admin / Attorney | `group_admin` | Open Attorney Strategy Memo; review/override conflicts; review filings before submission; review billing | +| Paralegal | `group_paralegal` | Drives the case stage-by-stage; runs Paralegal Review for procedural questions; manages discovery, depositions, deadlines; prepares court documents, signatures, filings; logs billable time | +| Portal Petitioner | `group_portal_petitioner` | Sees own case; signs court documents on the portal page when sent a link | +| Portal Respondent | `group_portal_respondent` | Sees own case (read-only beyond their party record) | + +--- + +## Quick troubleshooting + +| Symptom | Where to look | +|---|---| +| Can't move case past Intake | Conflict check failed — open the conflict record, admin override with justification | +| "anthropic not installed" / no AI summary | `pip install anthropic` in `odoo-web-1`; set `fl_ai.claude_api_key` system parameter | +| Signature page errors | `pip install PyMuPDF`; check `web.base.url` is set so the email link is correct | +| PDF/A check always warns | Source PDFs are not PDF/A-compliant — wkhtmltopdf output is plain PDF. Run them through a PDF/A converter (e.g., Ghostscript `pdfa.ps`) before signing/filing if the clerk rejects them. The pikepdf check is pragmatic (markers + OutputIntents), not full veraPDF conformance. | +| e-Filing API button errors | By design — confirm portal endpoint, set `fl_efiling.api_endpoint`, then Phase 2 work is needed to wire real submission. Until then, use Open Portal + Mark Submitted. | +| Paralegal agent fires twice on Intake | Once from `create()`, once from the first stage-write. Tasks are idempotent (same-name guard) so no duplicates are actually created. | +| Deadline alerts not firing | Check **Settings → Technical → Scheduled Actions** for "FL Family Law: Daily Deadline Alerts" — `active = True`, last run within 24h | + +--- + +## Reference: menus + +``` +Family Law +├── Cases +│ ├── All Cases +│ ├── New Case (Intake Wizard) +│ ├── Deadlines +│ ├── Hearings +│ ├── Depositions +│ ├── Discovery +│ ├── Conflict Checks +│ ├── Timesheets +│ ├── e-Filings +│ └── Signature Requests +├── Support Calculator +│ ├── Calculations +│ └── FL DCF Schedule (admin) +├── Case Law Library +└── Configuration (admin) + ├── FL Statute Index + └── Issue Tags +```