---
session: ses_2a6e
updated: 2026-04-04T15:34:15.344Z
---

# Session Summary

## Goal
Analyze and document how the most important motions are defined and ranked in the Stemwijzer codebase, focusing on importance criteria, selection mechanisms, metadata, key files, and user interaction patterns.

## Constraints & Preferences
- Provide detailed findings with file paths and line numbers
- Focus on code analysis without making changes
- Document the complete motion ranking and display system

## Progress
### Done
- [x] Analyzed motion importance criteria (controversy_score, SVD scores, entropy-based discrimination)
- [x] Documented motion selection mechanisms for SVD display, Political Compass, quiz, and similarity search
- [x] Mapped database schema for motions, mp_votes, svd_vectors, similarity_cache tables
- [x] Identified key files and their roles in motion handling
- [x] Documented user interaction flows for SVD components tab, MP quiz, and motion browser
- [x] Cataloged SVD_THEMES dictionary with all 10 component labels and explanations

### In Progress
- (none - analysis complete)

### Blocked
- (none)

## Key Decisions
- **Analysis-only session**: No code modifications were requested or made; this was purely investigative work to understand the existing motion ranking system.

## Next Steps
1. Awaiting further instructions from user on what to do with the analysis (e.g., implement changes, add features, optimize)

## Critical Context
### Motion Importance Metrics
1. **Controversy Score**: `1 - winning_margin` (0.5 = even split, higher = more controversial)
2. **SVD Component Scores**: Absolute projection on each SVD component axis
3. **Entropy Score**: Shannon entropy of vote distribution (for quiz discrimination)

### Motion Selection Strategies
- **SVD Display**: Top 10 per component (5 positive pole, 5 negative pole)
- **Political Compass**: Top 5 at each pole for axis labeling
- **Quiz Seed**: Top 8 controversial motions with individual MP votes
- **Quiz Discriminating**: Entropy-ranked motions that best split candidate MPs

### Database Schema
```sql
motions: id, title, description, date, policy_area, voting_results (JSON), 
         winning_margin, controversy_score, layman_explanation, body_text, url
mp_votes: motion_id, mp_name, party, vote, date
svd_vectors: window_id, entity_type, entity_id, vector (JSON 50-dim)
similarity_cache: source_motion_id, target_motion_id, score, vector_type, window_id
```

### Key Functions
| Function | Location | Purpose |
|----------|----------|---------|
| `get_motions_with_individual_votes()` | database.py:660-692 | Get controversial motions with MP votes |
| `choose_discriminating_motions()` | database.py:817-903 | Entropy-based motion selection |
| `_top_motion_ids()` | axis_classifier.py:274-295 | Top N motions per axis pole |
| `build_svd_components_tab()` | explorer.py:3081-3497 | UI for SVD motion display |
| `build_mp_quiz_tab()` | explorer.py:3499-3724 | MP quiz with adaptive motion selection |

### SVD Themes Location
`explorer.py:432-762` - Dictionary `SVD_THEMES` contains labels, explanations, and party poles for components 1-10.

## File Operations
### Read
- `/home/sgeboers/Projects/stemwijzer/analysis/axis_classifier.py`
- `/home/sgeboers/Projects/stemwijzer/database.py`
- `/home/sgeboers/Projects/stemwijzer/explorer.py` (partial reads at offsets 1860, 3050, 3400)
- `/home/sgeboers/Projects/stemwijzer/pages/1_Stemwijzer.py`
- `/home/sgeboers/Projects/stemwijzer/scripts/generate_svd_json.py`
- `/home/sgeboers/Projects/stemwijzer/similarity/lookup.py`
- `/home/sgeboers/Projects/stemwijzer/src/types/motion_types.py`
- `/home/sgeboers/Projects/stemwijzer/migrations/2026_03_21__create_mp_metadata.sql`
- `/home/sgeboers/Projects/stemwijzer/migrations/2026_03_21__create_mp_votes.sql`
- `/home/sgeboers/Projects/stemwijzer/migrations/2026_03_21__create_svd_vectors.sql`
- `/home/sgeboers/Projects/stemwijzer/migrations/2026-03-22-add-similarity-cache.sql`

### Modified
- (none)