feat: document residual new-pane flashing limitations in the README #118

New issue

Closed

opened 2026-04-28 01:58:05 +00:00 by barrettruth · 0 comments

barrettruth commented

2026-04-28 01:58:05 +00:00

Problem

Even after the follow-up work from #100, some creation-time flashing, role-shift, zoom snap, or global reshaping will likely remain in specific states. Users need a documented limitations section instead of having to infer this from issue history.

Blocked by: #101, #102, #105, #106, #107, #108, #109, #110, #111, #112, #113, #114, #115, #116, #117

Proposed solution

Add a README section that documents the residual creation-time flashing or reshaping circumstances precisely. It should cover the final tested matrix, not vague prose.

Context

This should come last among the follow-up issues. It should describe the final contract after the implementation and policy issues settle, not speculate up front.

Acceptance notes

The README should name exact classes and representative circumstances.
Keep it user-facing and precise.
Do not write it until the behavior is stable enough to document honestly.

Alternatives considered

Leave the limitation surface in issue comments only.
Document too early, then churn the README repeatedly as the behavior changes.

## Problem Even after the follow-up work from #100, some creation-time flashing, role-shift, zoom snap, or global reshaping will likely remain in specific states. Users need a documented limitations section instead of having to infer this from issue history. Blocked by: #101, #102, #105, #106, #107, #108, #109, #110, #111, #112, #113, #114, #115, #116, #117 ## Proposed solution Add a README section that documents the residual creation-time flashing or reshaping circumstances precisely. It should cover the final tested matrix, not vague prose. Suggested content: - which layouts now birth into the correct branch first - which states still require local equalization or local role shifts - which states remain true global-repartition cases - any explicit mirrored-policy decisions - monocle-specific zoom/focus caveats - min-size fallback behavior ## Context This should come last among the follow-up issues. It should describe the final contract after the implementation and policy issues settle, not speculate up front. ## Acceptance notes - The README should name exact classes and representative circumstances. - Keep it user-facing and precise. - Do not write it until the behavior is stable enough to document honestly. ## Alternatives considered - Leave the limitation surface in issue comments only. - Document too early, then churn the README repeatedly as the behavior changes.