ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

docs(workflow): add Known Pitfalls section (defer-not-catch, theme bisect anchors, live_gui fragility)

Browse Source
This commit is contained in:
Edward R. Gonzalez
2026-06-05 18:31:14 -04:00
parent 2312965476
commit 71b0082bbf
1 changed files with 27 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
conductor/workflow.md
+27
View File
@@ -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.