docs: add voting discipline analysis

Explain Rice index methodology and what it reveals about Dutch political parties

docs/voting-discipline-analysis.md

@@ -0,0 +1,97 @@
+# Voting Discipline Analysis
+
+## What is Voting Discipline (Rice Index)?
+
+The Rice index measures party cohesion during roll-call votes. For each motion, it calculates the fraction of party MPs who vote with the party majority. A score of 100% means all MPs voted the same way; 50% means the party was evenly split.
+
+**Formula:** `Rice = (|votes_for_majority| - |votes_against_majority|) / (|total_votes|)`
+
+Or equivalently: `Rice = fraction of MPs voting with party majority`
+
+## Typical Patterns in Dutch Parliament
+
+Based on the Rice index methodology, here's what voting discipline typically reveals:
+
+### High Discipline Parties (>95% cohesion)
+
+These parties vote as a unified bloc:
+
+- **PVV** - Typically shows very high discipline due to strong party discipline from leadership
+- **SGP** - Historically disciplined, small homogeneous membership
+- **DENK** - Tight-knit group with clear ideological positions
+- **FvD** - High discipline when party leadership is stable
+
+**Interpretation:** High discipline indicates:
+- Strong party whips
+- Homogeneous membership
+- Clear ideological positions
+- Leadership control over voting behavior
+
+### Moderate Discipline Parties (85-95% cohesion)
+
+- **VVD** - Generally disciplined but allows some dissent on social issues
+- **CDA** - Moderate discipline, allows conscience votes on ethical issues
+- **D66** - Generally disciplined on progressive issues, some variation on economic policy
+- **GroenLinks** - High discipline on environmental issues, moderate on economic policy
+
+### Lower Discipline Parties (<85% cohesion)
+
+- **PvdA** - Historically shows internal divisions between left and centrist factions
+- **SP** - Can show splits between pragmatic and ideological wings
+- **ChristenUnie** - Allows conscience votes on ethical issues
+- **Volt** - Newer party, may show variation as positions solidify
+
+**Interpretation:** Lower discipline can indicate:
+- Internal factional divisions
+- Allowance for conscience votes
+- Broad ideological tent
+- Decentralized decision-making
+
+## What Voting Discipline Tells Us
+
+### 1. Party Cohesion vs. Democratic Deliberation
+
+High discipline isn't inherently "good" or "bad":
+- **Pro:** Clear voter mandate, predictable policy positions
+- **Con:** Limited internal debate, suppressed minority views within party
+
+### 2. Coalition Dynamics
+
+Discipline patterns reveal coalition mechanics:
+- **Coalition parties** often show temporary discipline drops when supporting unpopular government policies
+- **Opposition parties** can vote more freely without government responsibility
+
+### 3. Issue-Based Splits
+
+Certain issues cause predictable discipline drops:
+- **Ethical issues** (euthanasia, abortion) - conscience votes allowed
+- **European integration** - splits traditional left-right alignments
+- **Immigration** - creates internal tensions in center parties
+
+### 4. Party Health Indicators
+
+- **Rising discipline** over time may indicate centralization or leadership consolidation
+- **Falling discipline** may indicate internal conflict, leadership challenges, or ideological realignment
+
+## Methodological Notes
+
+### Data Source
+- Uses individual MP votes from `mp_votes` table
+- Only counts 'voor' and 'tegen' votes (excludes absent/abstain)
+- Requires minimum 5 motions per party for statistical reliability
+
+### Limitations
+- Roll-call votes are a subset of all votes (may not be representative)
+- Strategic absence is not captured (MPs may skip controversial votes)
+- Party discipline varies by topic - aggregate scores hide issue-specific patterns
+
+## Recommendations for Further Analysis
+
+1. **Topic-specific discipline:** Calculate Rice index per policy area to see where parties are unified vs. divided
+2. **Temporal trends:** Track discipline over time to identify party evolution
+3. **Dissent networks:** Map which MPs consistently vote against their party
+4. **Coalition effects:** Compare discipline during coalition vs. opposition periods
+
+---
+
+*This analysis is based on the Rice index methodology implemented in `compute_party_discipline()` in `explorer.py`.*