Methodology — Political Baseball Card Generator

Methodology version: 1.3.1 Schema version: 4 Status: This document is part of the product. It is linked from every card's "How this score was calculated" panel. It is not internal-only documentation.

Trust note for readers: Baseball statistics on these cards are a *simplified visualization layer*, not a complete measure of a person's record or character. Every number maps to a published formula, a source priority tier, a confidence score, and dated citations. Where data is partial, we say so.

1. Core Principles

1. Neutrality: Data is presented raw; analysis is transparent. Media source

bias is *labeled*, never hidden, and is kept visually separate from a candidate's own ideology.

1. Accuracy: Every computed stat has a formula, a source priority, a

confidence score, and a methodology version.

1. Provenance: Every metric links to one or more citation records with a

URL, source type, retrieval timestamp, and (for news) a media-bias rating.

1. Humility: Uncontested races, brand-new candidates, and missing vote

histories produce Low confidence and explicit caveats — never invented data.

2. Source Priority Tiers

Fallback rule: A score always prefers the highest available tier. When a Tier 1 source is unavailable, the metric drops to the best available tier, its confidence is reduced by at least one level, and a caveat records the substitution. Tier 3 sources never set a numeric score on their own; they supply narrative context and citations.

3. Confidence Scoring

Confidence is a High / Medium / Low band assigned per metric, weighing four factors:

• Source quality — higher-tier sources (Section 2) raise confidence.
• Freshness — recent data is more confident than aging or stale data.
• Agreement across sources — corroborating sources raise confidence;

conflicting or single-source data lowers it.

• Completeness — a full record is more confident than partial or proxy data.

A metric is only as strong as its weakest factor, and the card-level confidence (methodology.confidence) reflects the least confident of the metrics that drive the headline stats.

4. Baseball-Stat Mapping

Each stat below defines plain-English meaning, formula, normalization, source priority, and caveats.

4.1 Batting Average — Promise Fulfillment / Stated-Policy Follow-Through

• Meaning: Of the trackable promises or stated policy positions, how many

the official has measurably acted on, surfaced to voters as a percentage.

• Primary data: Campaign platform, official actions, bill sponsorship,

executive actions (Tier 1/2).

• Caveats: Must expose the list of promises counted and which were fulfilled.

New candidates with no record return N/A (not 0).

• Validation breakdown: The headline percentage is backed by a validation

breakdown that exposes the counted promises so the number can be audited rather than taken on faith: - Counts split into Fulfilled, In Progress, Stalled, and Broken. Only *Fulfilled* and *In Progress* count toward the percentage; *Stalled* and *Broken* do not. - A plain-English summary, a note describing how promises were selected, and a list of representative examples — each with a status and citations for footnotes. - For non-incumbents who nonetheless have a prior governing record (e.g. a former Speaker now running for a different office), the breakdown is scored from that prior service and the note says so. Candidates with no record at all carry a documented "not available" explanation instead of a breakdown and remain N/A. - Coverage standard (all profiles): Every card includes a promise-fulfillment section. Record-holders get a scored breakdown; first-time candidates and others without a scoreable governing record get an honest "not available" explanation instead. An internal coverage check enforces that both sections are present and properly cited before a card ships.

4.2 Home Runs — Major Achievements

• Meaning: Count of *documented* major legislative/policy outcomes (enacted

bills, signed laws, passed budgets, and other verified outcomes).

• Normalization: Compared within peer group (same office class) for the

comparison view; raw count shown on the card.

• Primary data: Enacted bills, passed budgets, signed laws (Tier 1).
• Caveats: Count only documented outcomes, not press claims alone.

4.3 Fielding Percentage — Reliability

• Meaning: How reliably the official shows up to vote / participate. This is

distinct from Promise Fulfillment (§4.1): Reliability measures *participation* (did they show up?), while Promise Fulfillment measures *follow-through* (did they act on what they promised?).

• Primary data: Roll-call participation, committee attendance (Tier 1).
• Caveats: For executives/candidates with no roll-call record, use a

role-appropriate reliability proxy and label it; if none exists, N/A. Labeled Reliability everywhere in the UI (the older "Attendance" label is retired).

4.4 Stolen Bases — Initiative / Speed (retired from the UI)

• Meaning: First-mover activity — new bills introduced, early policy actions.
• Status: The Stolen Bases stat is retained in the data model but **no

longer surfaced** in the card stats grid, the deep-dive metrics, or the comparison "Performance Metrics" section, because raw introduction counts are activity (not quality) and were easily misread as effectiveness.

4.5 Errors — Documented Ethics / Legal Controversies

• Meaning: Count of *officially documented* ethics or legal findings.
• Primary data: Official ethics findings, court records (Tier 1).
• Caveats: Never score rumors or uncited allegations. Absence of findings

is shown as 0, not as proof of conduct.

4.6 RBI — Funding Secured / Measurable Impact

• Meaning: Appropriations, grants, or budget impact delivered to the

district/state, reported in millions USD.

• Primary data: Appropriations, grants, budget records (Tier 1).
• Caveats: Disclose whether the figure is absolute or per-capita normalized

and the time window covered.

4.7 Campaign Funding & Influence

• Meaning: Who funds each campaign and how much of the support is

outside/less-accountable money — surfacing heavy funding, heavy outside influence, and large undisclosed sums as a comparison criterion.

• Primary data: the official FEC campaign-finance record (Tier 1) for

*federal* candidates — committee receipts and their individual/PAC/party/self breakdown, notable contributing organizations, and independent (outside) spending. For *state and municipal* candidates the figures are researched, dated values drawn from the relevant disclosure agency — the Maine Ethics Commission, New York State Board of Elections, Texas Ethics Commission, the Georgia Government Transparency and Campaign Finance Commission, and the New York City Campaign Finance Board — each tied to a named filing with a working citation link and a coverage/report date.

• Source scope (per candidate): Every profile records which disclosure regime

the finance source follows the committee the candidate's *active / most-recent* campaign actually files with. So an officeholder currently running a federal race (e.g. a governor running for U.S. Senate, or a state legislator running for the U.S. House) is sourced to the FEC, while gubernatorial and legislative filers are sourced to their state agency and a citywide candidate to the municipal board.

• Source breakdown: Each slice (small individuals, large individuals, PACs,

party committees, self-funding, and other) is a share of committee receipts; outside spending is reported alongside as a share of receipts + outside spending because it is not money the campaign raised.

• Opacity proxy: an undisclosed-share figure derived from outside spending

relative to total money in the race, with a transparency read as its inverse. Small-dollar unitemized donations are deliberately NOT treated as opaque — they are grassroots support, not dark money.

• Outside influence: Derived from PAC share and outside-spending share

It is surfaced as a descriptive Performance Metric (in the deep-dive metrics and the comparison "Performance Metrics" section) linked back to this Campaign Funding section, which remains the source of its derivation.

• Campaign Funding vs Funding Secured: These are different signals and must

not be conflated. Campaign Funding (this section) is money raised *for the campaign*; Funding Secured (§4.6 RBI) is appropriations *delivered to the district/state*. The UI states this explicitly and shows the source of the campaign-finance figures (FEC for federal candidates; the relevant state ethics agency otherwise).

• Callout flags: descriptive flags surface heavy fundraising, PAC-dominated

receipts, large outside spending, heavily self-funded campaigns, and a large outside/undisclosed share, each triggered at documented thresholds.

• State/municipal outside-spending gap: Unlike the FEC's Schedule E, most

state and municipal agencies do not publish a comparable independent- expenditure total. When outside spending is not separately disclosed, the outside-spending and opacity/transparency figures are shown as "Not disclosed (state)" rather than fabricated as $0; where a state *does* report it (e.g. Maine's gubernatorial independent-expenditure filings), the disclosed figure is shown. Likewise, where a portal only offers PDFs or a search UI and a sub-breakdown (itemized vs. unitemized) is not separable, the approximate split is noted rather than presented as exact.

• Known limitations (shown in the UI): The FEC covers federal campaigns

only; state and municipal figures come from the agencies named above and are point-in-time snapshots dated to their latest available filing. The FEC does not cover Senate LDA lobbying spending or the donor identities behind 501(c)(4) "dark money" groups; those require a future lobbying/OpenSecrets adapter and are flagged as a coverage gap rather than fabricated.

4.8 Personal Net Worth

• Meaning: Estimated *personal* net worth over time — distinct from campaign

funding (§4.7). Surfaces year-over-year change since first taking office and a cross-official wealth ranking as voter context, never as a performance score.

• This is NOT the same as campaign funding. §4.7 is money raised *for a

campaign*; this section is an official's *personal* assets minus liabilities.

• Estimate, not an audited value. Financial-disclosure filings report assets

and liabilities in broad ranges, so each yearly figure is the midpoint of a disclosed range. Different analysts reach different totals from the same filings; the number is an approximation.

• Primary data: Original Personal Financial Disclosures (PFDs) filed

under the Ethics in Government Act of 1978 (U.S. House/Senate forms, OGE Form 278e); state officials file analogous disclosures with their state ethics agencies.

• Preferred compilers to cite (Tier 2, nonpartisan): OpenSecrets

"Personal Finances / Net Worth" (sums disclosed asset ranges minus liabilities) and Roll Call "Wealth of Congress". Quiver Quantitative may be cited only as a *live* estimate, clearly labeled as STOCK-Act-derived (tradable holdings only; excludes primary residence and liabilities). Aggregator lists (e.g. Wikipedia) are not cited directly — the underlying compiler is.

• Source scope (per official): federal disclosure, state disclosure, or

estimate, plus a report/coverage date. Drives the UI source badge.

• Ranking: Officials are ranked wealthiest → least by their current midpoint

estimate. Officials without a disclosed estimate are listed as unranked, not assigned a $0. Ranking is approximate and mixes disclosure regimes (federal vs. state), so cross-regime comparisons are labeled as inexact.

• Change since first elected: Percent change from the first-office-year

baseline (or earliest tracked year) to the latest disclosure. Shown on the summary card, comparison table, and detail panel; requires ≥ 2 tracked years.

• Documented limitations (shown in the UI disclaimer):

- Values are ranges, not exact figures ($1,001–$15,000 … up to "over $50,000,000"); the top bracket is open-ended, so the wealthiest are understated (such years are flagged as capped). - Primary residence and government salary are excluded. - Spouse and family assets are included but capped (a spouse's top bracket is "over $1M"), so an official who married into wealth is understated — a documented example is Chellie Pingree, whose spouse's assets far exceed the disclosed cap. - Net worth reflects neither how wealth was acquired (inherited, marital, business, or earned) nor any wrongdoing — it is transparency context only.

• Partial history: Where filings before some years cannot be obtained, the

history is marked incomplete and a note explains the gap rather than interpolating fabricated years. The year-over-year trend chart appears only on the one-page per-candidate detail view.

4.9 Legislative Record — Notable Bills

• Meaning: The candidate's most notable legislation, classified by

involvement to show whether they *lead* (write and drive legislation) or *follow* (mostly vote on others' bills), plus what major legislation they opposed. This is qualitative and curated — it is not scored and never produces a "winner."

• Involvement taxonomy:

- Authored — the candidate is the lead/primary sponsor. - Co-Authored — a named cosponsor who helped drive the bill. - Supported — a recorded Yea (or documented public support) on another member's bill. - Opposed — a recorded Nay or a documented effort to defeat/postpone a bill.

• Bill selection ("notable"): Bills are chosen for **public and legislative

significance** — landmark enacted laws, high-profile floor fights, and measures that defined the candidate's record in the press — not to flatter or attack them. Selection is documented per candidate in an accompanying methodology note.

• Required details per bill: a press-friendly popular name (e.g. "Kid-Safe

Products Act"), the official document ID (LD/paper number, legislature, and public-law chapter), a canonical source URL (Maine Legislature bill-status or record pages), the legislative session, a neutral one-sentence summary, the involvement (plus an optional detail citing the vote or sponsorship), and an unbiased pros/cons analysis.

• Pros/cons standard: Each pro/con summarizes the **strongest good-faith

argument on that side from a cited source (official bill text and fiscal notes, veto messages, roll-call records, and balanced press coverage), with citations for footnotes. Pros/cons describe the bill**, not the candidate, so a candidate who *opposed* a bill still shows its genuine merits.

• Comparison voting matrix (N/A rules): In the comparison view, each notable

bill (matched across the compared candidates by a stable key) gets one row and one cell per candidate: - In their record → the involvement chip (+ detail). - Bill's session not among the sessions the candidate served → "N/A — not in office." - Session served but no recorded position → "No recorded position." - Candidate has no legislative record at all (executive-only career) → "N/A — no legislative record."

• No-record candidates: Candidates whose careers were in non-legislative

roles carry a documented "no record" explanation instead of a bill list, and render as N/A on every matrix row rather than a fabricated record.

• Not recomputed by ingestion: This is curated content preserved from the

base snapshot on every refresh (like §4.1's promise breakdown); live APIs do not overwrite it.

• Coverage standard (all profiles, current and future): Every profile in the

dataset carries a legislative-record section. The choice between a curated bill list and the "no record" state is determined strictly by legislative service, not by current office: - Curated record — anyone who has held a seat in a state or federal House or Senate with roll-call votes (including former members now in executive roles, e.g. a governor who previously served in Congress). The record covers the sessions they actually served. - "No record" state — pure executives and appointees with no legislative service (governors/AGs/mayors/county executives who never held a House or Senate seat) and first-time candidates who have never held office. - Municipal record — city council members and comptrollers with documented local-law portfolios (e.g. NYC Council) receive a curated record using the same pros/cons standard, with official city-legislation URLs. An internal coverage check enforces that every card has a legislative-record section, that curated records carry cited bills with the required details, and that "no record" cards carry a documented explanation — so new profiles cannot ship without this section.

5. Media Bias Labeling (separate from candidate ideology)

• Source bias ratings come from a maintained media-bias reference and are

attached to each citation, recording which rater assigned the label.

• The media-bias meter visualizes the distribution of sources used, never the

candidate's ideology. Candidate ideology uses the Section 3 palette; media bias uses a distinct spectrum and is always labeled "Source/Media Bias".

• Aggregate weighting gives each source a 0–1 weight, summing to ~1 across the

sources used for a card.

• Rater attribution: The bands are informed by independent media-bias raters

(AllSides and Ad Fontes Media). Those raters' names and ratings belong to them and are referenced for identification only; the UI links out to each rater and to the [credits](/credits) page so readers can consult the primary rating rather than treating our label as authoritative.

5A. Issue Position Classification

For the six polarizing issues many voters care about most — Environment / Climate, Healthcare for All, Gun Legislation, Immigration, Abortion, and the War in Iran — each card carries a descriptive stance. Issue stances are never scored, ranked, or shown with "winner" styling. They describe a position, not a quality judgment.

Stance taxonomy:

Source priority (same tiers as Section 2): official first — campaign sites, voting records, .gov, signed legislation — then bias-labeled reputable news and structured civic datasets (Ballotpedia, AP/Reuters). For contested or politically charged issues we prefer at least one Center-rated source and, where practical, cross-spectrum corroboration. Every issue position links to its citations and renders footnote superscripts.

Deciding partial vs. unclear: If a candidate explicitly qualifies a position (e.g. supports background checks but opposes an assault-weapons ban) we record Mixed / Partial with a neutral summary. If the record is silent or genuinely ambiguous we record Unclear / No Public Position at Low confidence — we never infer a stance from party label alone or invent one.

Confidence follows the Section 3 model (source quality, freshness, agreement, completeness). Newer candidates and lightly documented figures legitimately end up Low confidence rather than overstated.

5B. Party Independence (Career / Cross-Aisle)

Party loyalty is reported as a unity/defection split derived from recorded votes. Where a politician has a prior political history (more than one office in their service record, or prior service before the current race), the party-loyalty read is enriched with a career view so readers can answer the plain question: "Do they work across the aisle?"

• The independence read draws on the full service history rather than only the

current term when a career view is available.

• A neutral, sanitized narrative describes cross-party behavior across the career

(including the honest case where a politician *rarely* worked across the aisle — e.g. a record-setting number of vetoes).

• Bipartisan highlights are specific, cited examples, each linked to its

sources for footnotes.

• For non-incumbent candidates whose current race has no measurable voting

record, the unity/defection numbers stay non-measurable (0/0, shown without a fabricated percentage) while the career narrative can still be drawn from their prior offices.

This section never invents cross-party behavior and never scores it as "good" or "bad" — high or low independence is presented descriptively with sources.

5C. Opposition Viewpoints (Contested Claims)

Each card may carry an Opposition Viewpoints section: up to five criticisms that the *opposing party* raises about the politician or candidate. This section is deliberately constrained because it is the most sensitive on the card.

Framing and guardrails:

• These are **contested viewpoints raised by opponents seeking competitive

advantage in an election — not verified findings** or this project's conclusions. A prominent disclaimer states this above the list.

• Each viewpoint is a neutral, sanitized restatement of the claim plus a framing

note explaining why opponents raise it. We never assert the claim as fact.

• Every viewpoint carries citation footnotes and a spectrum position (Far Left …

Far Right) describing where the cited source sits on the political spectrum — the "sentiment analysis on the political spectrum." The sentiment toward the subject is negative by definition, since these are criticisms.

• Placement: the section renders only in the detailed one-page summary

(the modal), never on the dashboard cards, is collapsed by default, and is positioned below all primary cited metrics so it cannot overshadow them.

• Candidates with no meaningful public record carry no opposition section rather

than speculative claims.

6. The 30-Day Freshness Rule

1. A public read looks up the most recent published snapshot for the requested

card under the current data version.

1. If that snapshot is within the freshness window (default 30 days) and was

produced by the current methodology → it is returned immediately with a "Last updated" date and confidence badges.

1. Otherwise → the last known good snapshot is returned immediately and marked

stale, and a refresh is scheduled. Refresh work happens in the background and never blocks the request.

6A. Election results & region freshness

Elections carry the same freshness discipline as officials. Each election records when it was last updated, a result status (scheduled → unofficial → certified), and a source link. The dashboards show a "Data for {region} last updated …" bar computed from the *oldest* update across that state's officials and elections.

Because election-result and issue data are expensive to collect, refresh is cost-conscious and region-scoped: the user's home region refreshes automatically on load, while every other region is manual ("Refresh this region"). Refresh work is always scheduled in the background; nothing is fetched inline on the request path.

6B. New-state download gate

The dataset covers a fixed set of officials and races and expands deliberately. When a user selects a state that has no loaded officials or elections, the app does not silently fetch or display data for it. Instead it shows an explicit confirmation ("Download data for {state}?") before any request is made. The prompt is honest about coverage: federal officials for that state can be populated from public sources (FEC, Congress.gov, GovTrack), while state- and local-level officials appear only after a verified data review and are never auto-generated. Auto-refresh is likewise suppressed for a not-yet-loaded home region until the download is confirmed.

6C. Data verification and unverifiable content

Editorial and record-based fields on seed cards (issue positions, documented controversies, funding context, net-worth ranges, scout narratives) are researched against primary and reputable secondary sources and carry article/record-level citations where possible. Election outcomes are verified against state election authorities and major reporting before a race is marked certified. Any figure or claim that research cannot substantiate is removed or marked Low confidence with an explicit caveat — never left as an authored guess. Interpretive constructs (ideology placement, the promise-fulfillment rate, party-unity estimates, media-bias bands) are labeled as editorial judgments rather than facts.

When live ingestion is enabled, federal refreshes update only what the live sources actually measure — roll-call participation (fielding), sponsored legislative output (achievements/initiative), and, via the FEC adapter, campaign finance. They deliberately preserve the researched promise, controversy, and funding-context values rather than overwriting them with proxies or a fabricated zero, and structured-civic feeds (e.g. GovTrack) never populate the media-source bias meter.

7. Version History

When to increment:

• Patch (1.0.x): wording/caveat clarifications, no score change.
• Minor (1.x.0): formula tweak, normalization change, or source-weight change.
• Major (x.0.0): redefinition of a stat or confidence model.

Any change to formulas, source weighting, or confidence rules must increment this version and append a row above. Snapshots store the methodology version used so historical cards remain auditable.