motief/thoughts/shared/plans/2026-03-30-compass-trajectory-consistency-plan.md

date	topic	status
2026-03-30	compass-trajectory-consistency	draft

Implementation Plan — Compass ↔ Trajectory Consistency

This plan implements the validated design (thoughts/shared/designs/2026-03-30-compass-trajectory-consistency-design.md) with the following firm constraints from the user:

• Use per-window MP-centroid party coordinates as the canonical source for components 1 & 2
• When a party has no MPs in a window, use the first chronological party vector as fallback
• Update all callers to the new explicit API; do NOT keep backward compatibility shims

Goal

Make the political compass numeric values identical to trajectory centroids for SVD components 1 and 2 by passing explicit per-party (x,y) coordinates (computed from positions_by_window) to the compass renderer and updating all callers to use that API.

Micro-tasks (ordered, small, actionable)

All tasks assume a development branch and running tests locally. Each task should be one commit.

1. Add explorer_helpers.py (pure helper)

• Create compute_party_coords(positions_by_window, party_map, window_id, fallback_party_scores=None)
• Returns (party_coords: Dict[str,(x,y)], fallback_used: Set[str])
• Unit tests: tests/test_explorer_helpers.py
• Estimate: 2.0h

2. Update explorer.py to the new strict API

• Replace _build_party_axis_figure to accept only explicit party_coords for comp_sel 1 & 2.
• Remove old polymorphic/legacy path; callers must pass party_coords or raise a clear error.
• Update rendering glue to call _build_party_axis_figure with explicit party_coords.
• Ensure hover text shows fallback notes for parties where fallback_used contains the party.
• Update/clean Streamlit caption behavior when no coords available.
• Tests: modify tests/test_explorer_chart.py to supply party_coords shape and assert behavior.
• Estimate: 4.5h

3. Update all callers across repo to pass explicit party_coords

• Grep for places that previously passed party vectors into _build_party_axis_figure or used load_party_axis_scores for compass rendering.
• Update each call site to compute party_coords via compute_party_coords, passing the fallback_party_scores (first-chronological vector) when needed.
• Caller list (non-exhaustive — verify with repo search):
  • explorer.build_svd_components_tab
  • explorer._render_party_axis_chart (if present)
  • any scripts or tests that directly call _build_party_axis_figure
• Update tests referencing legacy vector shape.
• Estimate: 3.0h

4. Add integration consistency test

• tests/test_compass_trajectory_consistency.py — synthetic positions_by_window and party_map to assert compute_party_coords equals centroid computations used by trajectories.
• Estimate: 1.0h

5. Run full test suite and fix regressions

• Run pytest; address failures introduced by strict API change.
• If other modules relied on old shape in ways not covered by tests, update them to use compute_party_coords.
• Estimate: 1.5h

6. Manual QA

• Run streamlit run explorer.py and visually verify compass tooltips and trajectories hover values match (comps 1 & 2) for several parties and windows.
• Verify fallback tooltip and logger WARN when a party uses fallback vector.
• Estimate: 1.0h

7. Commit and push (or open PR) with description: "feat(explorer): use explicit per-party (x,y) coords from positions_by_window for compass (components 1 & 2); update callers and add tests"

• Estimate: 0.5h

Verification commands

• Unit tests:
  • python -m pytest tests/test_explorer_helpers.py
  • python -m pytest tests/test_explorer_chart.py
  • python -m pytest tests/test_compass_trajectory_consistency.py
• Full test suite:
  • python -m pytest
• Manual UI:
  • streamlit run explorer.py

Rollback and mitigation

• If the strict API uncovers many call sites, revert to a temporary feature branch, document call sites, and migrate them in smaller patches.
• Keep commits small and self-contained to ease review.

Notes

• This plan follows the user's instruction to update all callers and to use the first chronological party vector as fallback.
• The helper is pure Python to keep tests simple; callers may cache if needed.