famlaw/WORKFLOWS.md

# 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://<your-host>/familylaw/sign/<token>` (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/<id>` — 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
```