4.4 KiB
Traceability view comprehension — issue 31
Branch-specific work above b8685416f56e53e30bd11ecf93a54cea10ac8458.
Issue31
owns live progress. This note records the chosen design and acceptance plan,
not completed validation or integration.
The user's observed problem is that OA↔SA traceability looks like All relationships and its purpose is unclear. Existing core behavior already projects both layers' placed elements, ordinary relationships and explicit traces with available endpoints. Switching projection neither creates semantic counterparts nor adds missing placements. Existing Add existing supports both layers, but its default suggested-type filter conceals opposite-layer choices. Show in this diagram also has inconsistent cross-layer eligibility and selects an opposite-layer element before placement, potentially changing the target view.
Decision and criteria
Make the existing workflow understandable and reachable before introducing a second counterpart browser. Criteria: a new user can explain the distinction, find both named ends, place existing counterparts in the chosen saved diagram, see/inspect correspondence, understand absent lines, and preserve semantic data. Keep the established mixed ordinary/trace contract, explicit semantic creation, saved view filters and single-operation placement history.
Use concise projection-local explanation, the actual count of projected trace edges, Add existing elements, Review layer traces, and existing View visibility. Default the Existing chooser to All compatible types only for Traceability; creation and ordinary-view defaults stay scoped to their existing contexts. Align Show in this diagram with actual supported placement and retain the captured diagram across cross-layer selection. Review layer traces opens a predictable layer-trace inventory without a stale artifact filter/search, through existing navigation/draft guards. It does not promise that subsequently choosing an opposite-layer endpoint preserves the originating diagram.
The count is exactly project_view(...).edges.filter(trace).count(), after saved
filters. It is neither a project-wide trace total nor a coverage denominator.
No overlapping missing/hidden reasons are added into invented totals. Port
correspondences use owner-card placements; relation-to-relation correspondences
remain reviewable semantic records and are not promised a diagram line.
An expandable view-local counterpart browser with named Place/Locate actions was independently proposed. It can reduce name memorization, but introduces another scope, owner-mapping, omission-reason and targeted-placement interface. The existing chooser already completes the bounded placement task once its default and shortcut are corrected. Revisit the richer browser if the actual native task remains confusing. Tooltip-only, traces-only replacement, automatic counterpart creation/placement and forced OA/SA layout were rejected: respectively weak task completion, broken mixed-context contract, surprising semantics/history, and unwanted authored-layout changes.
Verification plan
Exercise the real Existing chooser and actual Show menu path for opposite-layer elements, including stale/pending refusal and ordinary-view restrictions. Only the current diagram's intended placement may change; preserve semantic maps, other views, route/visibility choices, exact source Undo/Redo and save/reopen. Ports cannot become node placements. An already placed element must not acquire a duplicate placement. Predictable trace review must preserve drafts and obey the usual modal/navigation guards.
Use core projection/filter evidence for no trace, missing endpoints, both placed, ordinary OA/SA edges, multiple traces, explicit hides plus disabled Trace kind, port owners and relation correspondence. Do not infer visible lines from unfiltered edge_availability or confuse unrelated model traces with counterparts.
Native acceptance starts with an OA-owned mixed view, one already visible correspondence pair and another existing named SA counterpart not yet placed. Find/place it through the visible controls, see/select the additional trace, inspect an absent-line visibility reason, Undo/Redo and Save/reopen. Inspect toolbar/canvas space and chooser clarity at a realistic window size. Different help text or count tests alone do not resolve the user's comprehension complaint. Linux remains user-paused; Codex-956atf retains shared integration ownership.