# Phase 20.5: Modal State Architectural Audit — Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-04-16
**Phase:** 20.5-modal-state-architectural-audit-inserted
**Areas discussed:** Audit scope definition, Documentation format, Callback depth, Fragile pattern handling
**Mode:** --auto (all decisions auto-selected)

---

## Audit Scope Definition

| Option | Description | Selected |
|--------|-------------|----------|
| All overlay components | Includes PopupWindow modals + inline overlays with open/close state (sidebar, sidecar) | [auto] |
| PopupWindow modals only | Strict scope: only lookup-modal, state-transition-modal, settings-modal, add-product-form | |

**User's choice:** [auto] All overlay components (recommended default)
**Notes:** Sidebar/sidecar have state machines that interact with modals (Esc priority, focus). Excluding them would miss half the fragility surface.

---

## Documentation Format

| Option | Description | Selected |
|--------|-------------|----------|
| Mermaid stateDiagram-v2 | Already in placeholder, GitHub/VS Code renderable, machine-parseable | [auto] |
| Structured markdown tables only | Simpler, no rendering dependency | |
| ASCII art diagrams | Universal but hard to maintain | |

**User's choice:** [auto] Mermaid stateDiagram-v2 (recommended default)
**Notes:** Continuity with existing placeholder template.

---

## Callback Documentation Depth

| Option | Description | Selected |
|--------|-------------|----------|
| Full chain traces | End-to-end: slint callback → dashboard forwarding → main.rs handler → side effects | [auto] |
| Names and directions only | Callback name + in/out direction per modal | |

**User's choice:** [auto] Full chain traces (recommended default)
**Notes:** Incomplete chain understanding is the root cause of modal fragility (F1 failure mode).

---

## Fragile Pattern Handling

| Option | Description | Selected |
|--------|-------------|----------|
| Inline per modal with cross-refs | Warning placed where editor will see it, linked to RETRO doc | [auto] |
| Separate "Known Issues" section | Centralized but disconnected from the modal being edited | |

**User's choice:** [auto] Inline per modal with cross-refs (recommended default)
**Notes:** Aligns with M-2 "find-all-sites" philosophy — put the warning at the point of action.

---

## Claude's Discretion

- Internal organization of MODAL-STATE.md sections
- Level of detail in Mermaid diagrams
- Whether to include a modal interaction map

## Deferred Ideas

- 6 todos reviewed but not folded (all feature/bug work, not audit scope)