docs(event-storming): reconcile PM/DL coordinate refs in simulation docs - #219
Merged
Merged
Conversation
… table `simulation-evaluation.md`'s PM rubric and `agentic-simulation.md`'s PM Round 2 carried compact literal y-values (y=200 for corrected policies, y=+250 for alternatives) that drifted from the Process Modeling Y-Coordinate Table in `miro-integration.md` (Pass 2 corrections=300, Exception flows=600, Secondary alternatives=900). Per issue #1490's pre-baked resolution, the table is the single source of truth for PM phase coordinates (mirroring #1473's Big Picture reconciliation) -- replace the drifting literals with references to the canonical table rows instead of restating values. Verified via the same x-aware deterministic overlap check used for #1473: the PM table is geometrically clean (0 overlaps across a 3-segment representative flow), so it's a safe alignment target. Design-Level Y-Coordinate Table has a separate pre-existing internal overlap (Actors/Commands/Aggregates within 100px) plus an orphaned duplicate coordinate scheme in miro-integration.md itself -- out of this issue's scope, noted in the PR for follow-up. Refs melodic-software/medley#1490
kyle-sexton
changed the title
This was referenced Jul 20, 2026
kyle-sexton
added a commit
that referenced
this pull request
Jul 30, 2026
…he duplicate scheme (#1789) ## Summary Implements the owner-approved decision on melodic-software/medley#1555: widen Design-Level row spacing past the overlap threshold, keeping the single-flow model, then collapse the orphaned duplicate scheme into a reference to the corrected table. Both findings live in one file, `plugins/event-storming/skills/simulation/reference/miro-integration.md`. **Finding 1 — the Design-Level table overlapped itself.** Actors (`-200`), Commands (`-100`) and Aggregates (`0`) sat in 100px gaps, under the ~199px threshold these layouts use. Rows above the Aggregates baseline now sit **250px** apart. The decision permits any gap ≥200px; I used 250 for two reasons rather than taking the minimum. This file's own Spacing summary already states `Vertical (rows) | 250px`, so 250 makes the table agree with the guidance printed below it. And the threshold is written as *"~199px"* — a 200px gap clears an approximate bound by one pixel, which is not margin. Aggregates stays the `y=0` baseline. Rows below it were untouched as first pushed; review has since added a `Policies` row, which shifts the two bottom rows down by 250px — see *Finding 3*. **Finding 2 — the orphaned block was a third scheme, not a stale copy of either table.** It restated Actors `-250`, Read Models `-450`, Hot Spots `-250`, alternatives `+250`, matching neither canonical table, and it opened with *"Main flow (y=0 baseline): Commands, Events, Policies all sit on y=0"* — true of the single-flow model it was written for, but not of Design-Level, where **Aggregates** holds `y=0`. So it was not merely duplicated, it was actively wrong for the phase it sat under. Its y literals are gone. What it uniquely carried is kept: the flow reads left to right at 400px per item, and one flow step is a column sharing an x. The worked example now names table rows instead of restating their values, so the tables stay the only place y is written down — the same treatment #1473 / #219 gave the drifting literals. **Finding 3 — the Design-Level table had no `Policies` row (found in review).** Raised as a P2 by `chatgpt-codex-connector` against the worked example. `agentic-simulation.md` puts policies on this board twice — `:875` carries them over from Process Modeling, and `:881` adds more in Step 3 — but the Design-Level table never gave them a row, so the example borrowed `Domain Events`, whose Purpose column reads *"Orange — outcomes"* while a policy is violet. Finding 2's new wording is what makes the omission load-bearing rather than cosmetic: once the text says the tables are the only place y is written down, an element with no row leaves an agent nothing correct to pick. Pre-existing state was wrong differently — on `main` the example read `Policy: x=800, y=0`, and `y=0` in this phase is the **Aggregates** baseline. So the gap predates this PR, but it lands on lines this PR rewrote under a rule this PR tightened, which makes it a fix rather than a deferral. `Policies` now sits at **1650**, directly below the two event rows — a policy reacts to an event, and the Process Modeling table already groups the two on its `Event-Command-Policy` spine. That keeps `Domain Events` and `Alternative outcomes` adjacent and keeps internal reactive logic above the `BC Contracts (outbound)` boundary row. It shifts `What-if challenges` 1700 → **1950** and `BC Contracts (outbound)` 2000 → **2250**. Nothing downstream restates these values — `simulation-evaluation.md`, `iteration-workflow.md` and `SKILL.md` all reference phase rows by *name*, never by coordinate — so the shift is contained to this one table. Review also noted the worked example had dropped the Read Model that used to head its `x=0` column. Restored, so the example again walks every row it touches. ## Test plan The issue asks for an x-aware geometric overlap check (two elements overlap only when their x-ranges intersect **and** `|Δy| < ~199px`). Every row in one phase's table shares the same x band — a flow step is a column — so x always intersects and the test reduces to adjacent `|Δy|` across the sorted rows. Run against `origin/main` and against this branch: **Before — reproduces exactly the two overlaps the issue reported:** ```text ok: Read Models <-> Actors |dy|=200px OVERLAP: Actors <-> Commands |dy|=100px OVERLAP: Commands <-> Aggregates |dy|=100px ok: Aggregates <-> Business Rules |dy|=300px RESULT: 2 overlap(s) exit=1 ``` **After:** ```text ok: BC Contracts (inbound) <-> Read Models |dy|=250px ok: Read Models <-> Actors |dy|=250px ok: Actors <-> Commands |dy|=250px ok: Commands <-> Aggregates |dy|=250px ok: Aggregates <-> Business Rules |dy|=300px RESULT: no overlaps exit=0 ``` That the *before* run independently reproduces the issue's reported figures is what makes the *after* run meaningful — the check is measuring the right thing, not passing vacuously. The other two phase tables were run through the same check to confirm this change did not disturb them: **Big Picture** — no overlaps; **Process Modeling** — no overlaps. **After Finding 3's row insert**, the same adjacent-`|dy|` walk was re-run over the widened Design-Level table, since the shift has to keep clearing the minimum. This run also flags gaps that clear the ~199px overlap bound but fall under the file's own stated 250px minimum, which the earlier pass did not distinguish: ```text === Design-Level Y-Coordinate Table (11 rows) === ok BC Contracts (inbound) <-> Read Models |dy|=250px ok Read Models <-> Actors |dy|=250px ok Actors <-> Commands |dy|=250px ok Commands <-> Aggregates |dy|=250px ok Aggregates <-> Business Rules |dy|=300px ok Business Rules <-> Domain Events |dy|=800px ok Domain Events <-> Alternative outcomes |dy|=300px ok Alternative outcomes <-> Policies |dy|=250px ok Policies <-> What-if challenges |dy|=300px ok What-if challenges <-> BC Contracts (outbound) |dy|=300px ``` The walk reads each row's declared y, so the Business Rules row shows an 800px delta to Domain Events; that row stacks at 300/550/800, so the real clearance from the bottom of the stack is 300px. Every other pair is its literal gap. Big Picture stays clean on that stricter check. **Process Modeling does not** — its three rows above the baseline are 200px apart, clear of the ~199px overlap bound but 50px short of the stated minimum. That is pre-existing, reproduces on `main`, and is out of scope here; filed as melodic-software/medley#1689 with the mechanical output. `markdownlint-cli2` on the edited file: 0 errors. ## Not covered No Miro render was performed — the verification is geometric, as the issue specifies. A to-scale visual confirmation is still worth doing by whoever next opens one of these boards, since only a render exercises sticky dimensions rather than centre coordinates. ## Related Refs melodic-software/medley#1555 🤖 Generated with [Claude Code](https://claude.com/claude-code) <https://claude.ai/code/session_01RhS3T7ShwJgKTrvk2Mvd3C> Fixes melodic-software/medley#1555 --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Reconciles the two Process Modeling coordinate conflicts flagged across the
event-stormingsimulationskill's three reference docs onto the existing per-phase canonical scheme (mirroring#1473's Big Picture reconciliation), for the PM/DL phases left unchanged by that prior work.
Why
simulation-evaluation.mdandagentic-simulation.mdcarried compact literal PM y-values thatdrifted from the Process Modeling Y-Coordinate Table in
miro-integration.md:y=200300y=+250/y=250600, Secondary alternatives =900Resolution — per-phase canonical (per the issue, mirroring #1473)
The Process Modeling and Design-Level Y-Coordinate Tables in
miro-integration.mdare the singlesource of truth for their phases. Replaced the drifting literals in
agentic-simulation.md(PM Round 2: Alternative Paths) and
simulation-evaluation.md(PM Rubric: Three passes completed,Alternative paths modeled) with references to the canonical table rows instead of restating
values — same treatment PR #159 gave the Big Picture phase.
Swept every
y=/x=/frame/tool coordinate reference in both files: no other PM/DL drift found.Design-Level sections in
agentic-simulation.mdcontain no numeric coordinate literals to beginwith (mechanical step descriptions only), so nothing there needed changing.
Verification (geometric, x-aware — no live Miro board)
Per the issue: PM/DL layouts are x-localized per flow-segment (not full-width bands like Big
Picture), so the overlap check must be x-aware — two elements overlap only when their x-ranges
intersect AND
|Δy| < ~199px.aligns to): built a representative 3-segment flow (x = 0, 400, 800 — the documented 400px
horizontal spacing) with every table row placed at each segment. 0 overlaps across 30
elements — confirms the table is a geometrically safe alignment target.
row gap is ≥200px (header stack) or 300px (below Main Flow), all clear of the 199px overlap
threshold.
Out of scope (follow-up — same bug class as #1473's "spotted but not fixed here")
The same verification pass surfaced two issues in
miro-integration.mditself, outside thisissue's scope (which only covers the two flagged PM literals in the other two files):
-200), Commands(
-100), Aggregates (0) are packed into 100px gaps — under the|Δy| < 199pxthreshold.Deterministic check confirms:
OVERLAP: Actors <-> Commands |dy|=100px,OVERLAP: Commands <-> Aggregates |dy|=100px.miro-integration.mdright after theDesign-Level table (
**Main flow (y=0 baseline)**/**Above the flow**/**Below the flow**/**Example: one complete flow segment**blocks) restating its own values (Actors-250, Read Models-450, Hot Spots-250, Alternative outcomes+250) that match neitherthe PM nor the DL table. Per
git blame, this block and both per-format tables were introducedin the same original authoring commit — it's the literal source the compact values removed by
this PR trace back to, never cleaned up when the two tables were added. Same shape as the
leaked-compact-scheme bug session-flow/running-retro analyzer: stenographer bias — accurate on self-declared findings, 0/2 on independent inference; structural claims asserted not computed #1473/PR fix(event-storming): reconcile Big Picture simulation layout to one canonical scheme #159 fixed for Big Picture.
Fixing #1 requires choosing new DL spacing (multiple valid options, no single correct answer
dictated by existing evidence) — a decision, not a mechanical literal-swap like this PR, so it
wasn't forced here. Filing a follow-up issue for a human decision was attempted but blocked by
this session's own write-permission guard (unrequested tracker write); flagging here instead so
it isn't lost.
Closes melodic-software/medley#1490