Methodology & trust · working spec v1
How we work, and how we show it.
Trust is the whole game. If we can't point to where a claim came from, we don't make the claim. Here is how the data gets collected, summarized, scored, and checked, and the rules that keep it honest.
Where the data comes from
We start with the government's own records. Everything on Civic Herald is built from primary, public-domain federal sources, not from a pundit, a party, or a press release. When a number is on the page, you can follow it back to the office that published it.
As coverage expands, state and local sources follow the same discipline: official first, with a citation attached.
How the pipeline works
Automated labor, prioritized by what people need. A bill becomes law about one time in twenty, so we don't summarize all ten thousand of them with equal effort. The pipeline ranks work by activity and attention. Then it drafts a plain-language briefing of what a bill does and who it touches, and tags each provision against a fixed issue taxonomy.
The model does the toil: it reads dense legislative text and proposes structured outputs. It does not get the last word. Until a person has reviewed a claim, it is shown as provisional, with that label on it, and never presented as settled fact.
Derived vs. fetched
A model's estimate is never dressed up as a fact. We keep a hard line between two kinds of information: data we fetched from an official source, and analysis a model derived from it. Both can appear side by side, and each wears its own label.
We never let a model's estimate sit on the page looking like an official number.
Fetched data carries its source and the time it was retrieved. Derived data carries the run that produced it and its review status. A cost figure from the Congressional Budget Office is labeled as such; a modeled estimate is labeled as a modeled estimate.
Party unity is one of ours. The party-unity figure on a member's page is a count we compute. No agency publishes it, which is why it is labeled derived wherever it appears. Its denominator is the roll calls where that member voted yea or nay; votes they missed, or answered "present" on, are left out. For each of those roll calls we take the side most of their party voted, using each member's party as of that vote. The figure is the share of that member's votes that landed on the same side. A member with no party on file, or with no yea-or-nay votes yet, gets no figure at all rather than a zero.
How alignment is scored
We measure against your values. There is no house line. Onboarding asks where you stand on the issues you care about. A bill's alignment score is computed at read time from your stated values and the bill's per-issue effects. It is never stored on the bill, because the same bill matches different people differently.
The method is symmetric: the same scoring runs for every user and every member, with no special handling for either side. We keep relevance ("is this on your radar?") separate from alignment ("does it match your values?"). They are two different questions, and they get two different answers.
How cluster scores are built
Six clusters, one disclosed rule, the same math for every member. A member's says-vs-does page groups our full issue taxonomy into six fixed clusters. Each is drawn as a named axis between two poles (for example, PUBLIC SPENDING ↔ FISCAL RESTRAINT). The grouping is a versioned, published map. Every issue belongs to exactly one cluster, and each issue carries a disclosed orientation that says which pole its own scale points toward. The map never changes per member, and the version that produced a page is stamped on it.
A cluster's stated position averages only human-reviewed platform positions. Its record position is built from reviewed votes, weighted by how many roll calls back each issue. An issue only counts once it clears the same vote-count confidence gate used everywhere else in our scoring. A cluster's record shape is drawn only when at least two of its issues clear it. The signed says-does gap is computed only across issues where both sides qualify. Subtracting averages taken over different sets of issues can manufacture a "gap" out of nothing but composition, so we never do that. Any "differs" count includes only divergences that passed human review, and the headline numeral counts reviewed stated positions with a voting record on file.
Human review & balance
The pipeline does the toil; people guard the integrity. Trained reviewers audit the data itself. They confirm or correct plain-language summaries, issue tags, effect directions, and divergence flags. Accusatory features stay gated behind that review: a machine's provisional judgment about a named person is not enough to publish.
Reviewers are recruited in equal number from the left, the center, and the right. Each rates their own political lean before they serve, and we publish it. They review blind to a claim's source or sponsor, and scores are averaged across the groups so that no single side sets a number.
Provenance on everything
Every claim carries its source, version, and freshness. Provenance is built into the page, and the page depends on it.
For example, a bill's header might read "Bill text: GovInfo XML (38pp) · summarized by model v.2026.05 · last refresh 6h ago." Summaries point back into the bill's own sections. A review stamp, "Reviewed by a balanced panel · 3 days ago," appears only when it is true.
If a part of a claim is missing, with no source or no review, the page says so rather than papering over it.
Neutrality governance
Neutrality is built into the process. A scorecard is only useful if people who disagree with each other can both trust the math. So we build the neutrality into the process rather than asserting it in a mission statement.
A scorecard is only trustworthy if a conservative and a progressive both believe the numbers weren't cooked for the other side.
We blind extraction to party and hold to a strict non-advocacy charter. Our safeguards (balanced panels, public donor disclosure, an editorial firewall) are copied from the institutions that set the standard for nonpartisan civic data.
Privacy & your data
Your values, your activity, and your profile are yours. Your stated positions power your scores and nothing else. You can download your data or delete it. Personalized scores are computed fresh each time you read a page; they are never sold and never used to advocate.
We'd rather show less and be unimpeachable than show more and be doubted. This spec is a living document. It changes as our methods are reviewed and externally audited. Found an error, or want to check the math? That's the point. See who funds us or become a reviewer.
Living document
Check the math.
This spec evolves as our methods are reviewed and externally audited. Found an error, or want to check our work? That's the point.