diff --git a/conductor/workflow.md b/conductor/workflow.md
index 340bbe3b..a18e8125 100644
--- a/conductor/workflow.md
+++ b/conductor/workflow.md
@@ -396,3 +396,30 @@ To emulate the 4-Tier MMA Architecture within the standard Conductor extension w
 - The **Phase Completion Verification and Checkpointing Protocol** is the project's primary defense against token bloat.
 - When a Phase is marked complete and a checkpoint commit is created, the AI Agent must actively interpret this as a **"Context Wipe"** signal. It should summarize the outcome in its git notes and move forward treating the checkpoint as absolute truth, deliberately dropping earlier conversational history.
 - **MMA Phase Memory Wipe:** After completing a major Phase, use the Tier 1/2 Orchestrator's perspective to consolidate state into Git Notes and then disregard previous trial-and-error histories.
+
+---
+
+## Known Pitfalls (2026-06-05)
+
+### Defer-Not-Catch Pattern for Native Crashes
+
+`imgui-bundle` (and similar native extension libraries) expose C-level functions that can crash the Python process with a Windows access violation (`0xc0000005`) or a SIGSEGV on Linux. **These crashes are not catchable from Python** — `try/except Exception` does not intercept native access violations, only Python exceptions.
+
+The fix is **defer-not-catch**: track a one-shot "ready" flag in instance state; return early on the first call, only invoking the C function on subsequent calls. See [../docs/guide_gui_2.md](../docs/guide_gui_2.md#workspace-profile-defer-not-catch) and [../docs/guide_testing.md](../docs/guide_testing.md#known-gotchas-2026-06-05) for the canonical examples and how to recognize these crashes.
+
+When designing any method that calls into `imgui.*` (or similar native libs), ask: "Can this be called before ImGui is fully initialized?" If yes, add a defer-not-catch guard.
+
+### Test Failure Bisect Anchors (Theme Track)
+
+When debugging test failures introduced by a theming/visual change, use the following bisect anchors:
+
+- **Pre-existing failures:** bisect to commit `7df65dff` (last commit before the multi_themes_20260604 track began). Failures that reproduce at this anchor are pre-existing and not caused by the theme changes.
+- **Theme-caused failures:** bisect to commit `7ea52cbb` (the theme refactor commit). Failures that only appear after this commit but not at `7df65dff` were introduced by the theme track.
+
+In particular, watch for:
+- Tests asserting theme color usage: the theme track changed `C_LBL` etc. from `ImVec4` values to callable functions. Tests that assert with `C_LBL` (the function) need to be updated to `C_LBL()` (the call), and they need to patch `src.theme_2.imgui` so the mock's `theme.get_color()` returns the mock's `ImVec4`.
+- Tests with production code that builds dicts of theme color callables (e.g. `DIR_COLORS = {"request": C_OUT}`): the dict must store the function, and the use site must call it (`d_col()` not `d_col`). Bug example: `src/gui_2.py:3705-3707` (commit `1469ecac`).
+
+### Live_gui Test Fragility
+
+`live_gui` is a session-scoped fixture. All tests in a session share the same `sloppy.py` subprocess. Test order matters: a test that triggers deep render paths early in the session "warms up" ImGui state for later tests. Always bisect live_gui test failures by running the test both in the full suite and in isolation to distinguish "needs warmup" from "real bug". See [../docs/guide_testing.md](../docs/guide_testing.md#live_gui-non-determinism) for the full pattern.