koala73 / koala73/worldmonitor
feat(data): global election calendar with proximity-based instability risk scoring
- Dominant language
- TypeScript
- Stars
- 86.6k
- Forks
- 13.1k
- Avg merge
- 8h 4m
- Merged PRs (30d)
- 825
Description
## Summary
Elections are among the strongest predictable drivers of instability windows, and we have no election awareness anywhere: no calendar, no proximity signal in country risk, nothing for agents to query. (Raised once inside the closed community-synthesis issue #540; never scoped or built.)
## Proposed scope
1. **Dataset**: curated global election calendar (national executive + legislative, plus scheduled referendums), 2026–2030 horizon. Sources: IFES ElectionGuide / IPU / Wikipedia-derived curation; stored as a versioned curated dataset like our other static registries, refreshed on a slow cadence.
2. **Risk scoring**: proximity-based instability weighting — election within N days raises a country's watch level, modulated by our existing unrest/conflict baseline for that country (fold into the Composite Instability Index inputs rather than inventing a parallel score).
3. **Surfaces**:
- MCP tool `get_election_calendar` (filters: country, window, type) with freshness metadata
- `get_country_risk` gains an `upcomingElection` component
- dashboard: upcoming-elections list in the country panel / world brief context
4. **Brief integration**: world/country briefs mention imminent elections as context.
## Considerations
- Snap elections make any static calendar decay — the dataset needs an update path and a `lastReviewed` vintage field, and the scoring must tolerate missing/moved dates gracefully.
- Keep scoring transparent (component visible in CII breakdown, like unrest/conflict/security/news components today).
## Acceptance criteria
- [ ] Calendar dataset with vintage metadata + update runbook.
- [ ] CII/country-risk integration with visible component and tests.
- [ ] MCP tool + docs + parity entry shipped.
## Related
- #540 (community synthesis, closed)
Contributor guide
Research direction
Start by locating the existing static registries, Composite Instability Index inputs, country-risk surface, MCP tool registrations, dashboard country panel, and brief generation paths. Review their tests, freshness metadata, and parity documentation before defining the dataset and update path. Done means the calendar, transparent risk component, MCP surface, dashboard and brief integration, tests, docs, and runbook meet the listed acceptance criteria.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- backend-api-design, data, documentation, frontend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100