Functional Impairment

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

This feature documents behavior concerns that produce meaningful functional impairment, so the clinical team can connect symptom burden to treatment need in a clear medical-necessity narrative. It centralizes one focused statement that can be edited manually or regenerated with AI support.

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 edit and regenerate functional impairment 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 functional_impairment with title Functional Impairment.
• 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: Regenerate with AI requires a persisted BIP ID; otherwise operation is blocked with feedback.
• Rule 6: During regeneration, editing is disabled and loading state is shown.
• Rule 7: If regeneration returns empty content, existing text is preserved and user gets informational feedback.

4. UI Placement

• Medical > clients list > client actions > BIP View / Update.
• Inside BIP tabbed view: Functional Impairment tab (id functional_impairment) when feature flag is enabled.
• Route family used for tabbed BIP: /bip/tabbed/:patient_id and /:id route variant under BIP module.

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

Scenario A: Write functional impairment statement manually

1. Go to Medical and open the clients list.
2. Open client actions and click BIP View / Update.
3. Open Functional Impairment tab.
4. Enter or revise Description text.
5. Wait for autosave confirmation/toast after edits.

Scenario B: Regenerate functional impairment with AI

1. Open Functional Impairment tab.
2. Click Regenerate with AI.
3. Wait for loading to finish.
4. Review generated text and make clinical edits if needed.

Scenario C: Regeneration when BIP is not ready

1. Open tab before BIP has persisted ID.
2. Click Regenerate with AI.
3. System blocks action and asks user to create/load BIP first.

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

• Q: Why is this tab not visible in some environments?

• A: It depends on insurance-statements-fields feature flag.

• Q: What if AI regeneration fails?

• A: The UI shows backend or fallback error message and exits loading state.

• Q: Does this tab currently have dedicated completion criteria?

• A: In parent tab-completion logic there is no explicit functional_impairment completion case.