congress-analyzer/NOTES.md

NOTES — Deferred Concerns

This file captures known concerns considered but deliberately deferred from the MVP scope of the 119th Congress voting-dashboard rewrite. Each item names the source of the concern (compliance, PM, programmer) and the reason it was deferred.

1. Editorial label wording (compliance Finding 1, High). The compliance review flagged that current labels such as "Helped Republicans" and "Blocked Dem-Backed" attribute intent and agency that the underlying math does not actually measure. Neutral alternatives were proposed — for example, "Aligned with R majority" and "Voted Nay on failed D-backed measures" — which describe the observed voting behavior without imputing motive. The decision is to keep the current wording per explicit user preference for the MVP, and to revisit this language before any third-party publication or wider distribution.

2. compare.html chart scope (PM + programmer, Medium). Both the PM and programmer agents observed that the voted-against-own-party overlay and the vote-distribution comparison chart are largely derivative of data already shown in the single-member view, raising a question of whether all five comparison charts add distinct value. The decision is to ship all five charts in MVP per user preference, and to trim the set later only if user-research feedback shows that specific charts are redundant or confusing.

3. Visible caveats panel (compliance Finding 2). Section 10 of DOCUMENTATION.md enumerates material limitations of the analysis: procedural and substantive votes are treated equally, blocking is computed per-share rather than at the margin, the lone-wolf threshold of ≤5 is a heuristic, and voice votes are invisible to the pipeline. Compliance recommended surfacing these caveats to end users via a collapsible "How to read this" panel on each dashboard page. This work is deferred to v1.1 rather than blocking MVP launch.

4. localStorage as MVP feature (PM, Could-Have). Client-side persistence of user preferences via localStorage was scoped as a Could-Have rather than a Must-Have for the MVP. The PM agent flagged it as the first candidate to cut if Phase 3 implementation runs long, so it is being tracked here as an explicit deferral rather than a forgotten feature.

5. 120th Congress dry-run (programmer). The rewrite generalizes the pipeline so that it can ingest any Congress by number, but no live 120th Congress data exists yet to actually exercise that generalization end-to-end. Until real 120th data is available, the programmer's confidence in the parameterized pipeline rests on code review and unit tests alone; a true dry-run validation is deferred until the data lands.

6. Comparison "Voted against own party" proxy (Phase 5). analyze.py emits monthly alignment buckets keyed by [Helped R / Helped D / Helped Both / Helped Neither], but does NOT emit a per-month "voted against own party" series. The compare.html chart uses monthly['Helped Neither'] as a proxy, since a vote that helped neither party is the strongest signal of own-party defection available from current aggregates. Caveat: "Helped Neither" can also include votes where both parties were Split or where the member voted Yea on a tied vote — it is not a pure measure of own-party defection. Surfaced in the chart's figcaption. A future enhancement to analyze.py could emit a true monthly own-party-defection series.