Individual Rationale

1. What does this feature do? (High-Level Overview)

This feature captures the individualized clinical rationale of the BIP so clinicians can document the client-specific medical necessity narrative in one focused section, linking case formulation to why this specific intervention plan is appropriate for this client, and supporting consistency for care planning, payer-facing documentation, and multidisciplinary communication.

2. Who is this for? (Roles & Permissions)

• Superadmin/Admin/Owner/Manager (or any role granted manage_bips): Primary users of editable tabbed BIP flow; can write or refine individualized rationale content.
• RBT/Analyst without manage_bips: Usually redirected to full BIP read-only flow (/bip/show/patient/:id) instead of tabbed editing flow.
• Users without BIP access permissions (view_bips/manage_bips): Cannot access BIP actions from normal client workflows.

Required permissions used by this feature path:

• manage_bips: Required to remain in editable tabbed BIP route.
• view_bips: Used in non-tabbed BIP viewing entry points.

3. Business Rules & Enforcements

• Rule 1: This tab is defined as individual_rationale with title Individual Rationale.
• Rule 2: The tab is feature-flagged and only appears when insurance-statements-fields is enabled.
• Rule 3: If no BIP exists yet, tab interaction is blocked globally and users must first create a BIP.
• Rule 4: Any text change emits bipUpdated, which triggers parent debounced autosave.
• Rule 5: Tab completion state is true when individualized_rationale has non-empty trimmed text.
• Rule 6: The tab includes a Regenerate with AI action that requests backend field regeneration (regenerateField with key individualized-rationale).
• Rule 7: AI regeneration is blocked when BIP has no ID (unsaved/not ready) and user receives feedback message.
• Rule 8: While regeneration is running, the UI enters loading/disabled state to avoid conflicting edits.

4. UI Placement

• Medical > clients list > client actions > BIP View / Update.
• Inside BIP tabbed view: tab Individual Rationale (tab id individual_rationale) when feature flag is enabled.

5. How-To Guide (Step-by-Step)

Scenario A: Write individualized rationale manually

1. Go to Medical and open the clients list.
2. Open client actions and click BIP View / Update.
3. Open tab Individual Rationale.
4. Enter or refine the client-specific rationale text in the editor.
5. Wait for autosave confirmation/toast after edits.

Scenario B: Regenerate rationale with AI

1. Open Individual Rationale tab.
2. Click Regenerate with AI.
3. Wait for regeneration to complete (loading spinner shown).
4. Review generated text and make manual clinical edits if needed.
5. Save is triggered through standard tab update flow.

Scenario C: Regeneration when BIP is not ready

1. Open tab before BIP has persisted ID.
2. Click Regenerate with AI.
3. System blocks operation and displays guidance to create/load BIP first.

6. What happens if…? (Edge Cases / FAQ)

• Q: What if AI regeneration returns no content?

• A: The system shows a feedback message (No content returned by AI regeneration) and keeps existing content unchanged.

• Q: What if AI regeneration fails?

• A: The system displays backend error message (or fallback failure text) and exits loading state.

• Q: Why don’t I see this tab in some environments?

• A: The tab depends on insurance-statements-fields feature flag; if disabled, it is intentionally hidden.