{ "_meta": { "name": "Texas Votes AI Methodology Export", "version": "1.0", "exportedAt": "2026-04-04T12:10:08.506Z", "purpose": "Complete transparency export of all AI prompts, data pipelines, and safeguards used by Texas Votes (txvotes.app) to generate personalized voting guides. This document is designed to be reviewed by independent AI systems for bias assessment.", "website": "https://txvotes.app", "auditPage": "https://txvotes.app/audit", "howItWorks": "https://txvotes.app/how-it-works", "nonpartisan": "https://txvotes.app/nonpartisan", "dataQuality": "https://txvotes.app/data-quality", "openSource": "https://txvotes.app/open-source", "balanceCheck": "https://txvotes.app/api/balance-check", "securityNote": "Verbatim system prompts and exact model versions have been redacted from this public export to prevent prompt injection attacks. The full methodology, safeguards, and audit framework remain visible for transparency. Security researchers can contact howdy@txvotes.app for responsible disclosure." }, "guideGeneration": { "description": "When a voter completes the interview, their profile is sent with the full ballot data to generate personalized recommendations. Both Republican and Democratic ballots use identical prompts and formatting.", "model": "Claude Sonnet (Anthropic)", "systemPrompt": "System prompt instructs Claude to provide nonpartisan, factual analysis using neutral language. Full prompt text withheld for security.", "userPromptTemplate": "User prompt template constructs a structured request with voter profile, ballot data, and nonpartisan rules. Full template text withheld for security.", "readingLevelInstructions": { "1": "Adjusts language to high school reading level for first-time voters.", "2": "Uses casual, conversational tone like explaining to a friend.", "3": "(default — no tone instruction added)", "4": "Uses precise political terminology, assumes the reader follows politics.", "5": "Expert-level political science language with policy frameworks.", "7": "Easter egg: Folksy Texas cowboy voice with ranch metaphors." }, "confidenceLevels": { "races": [ "Strong Match", "Good Match", "Best Available", "Symbolic Race" ], "propositions": [ "Clear Call", "Lean", "Genuinely Contested" ] }, "constraints": [ "Must only recommend candidates present in the provided ballot data", "Must never invent or hallucinate candidate information", "Reasoning must reference the voter's specific stated values", "Both parties receive identical prompt structure and formatting", "Output must be valid JSON — no markdown, no prose" ] }, "profileSummary": { "description": "A separate AI call generates a 2-3 sentence voter profile summary. This is displayed to the voter and can be regenerated.", "systemPrompt": "System prompt instructs Claude to provide nonpartisan, factual analysis using neutral language. Full prompt text withheld for security.", "userPromptTemplate": "User prompt template constructs a structured request with voter profile, ballot data, and nonpartisan rules. Full template text withheld for security." }, "candidateResearch": { "description": "County-level candidate data is populated using Claude with the web_search tool. The AI researches official filings and news sources to find candidates, their positions, endorsements, and backgrounds. Each candidate receives individually attributed source citations (URL, title, access date) captured from Claude web_search API responses — sources are per-candidate, not per-race, ensuring every claim can be traced to its origin.", "systemPrompt": "System prompt instructs Claude to act as a nonpartisan election data researcher, use web_search for verified information, follow a 7-tier source priority hierarchy, and resolve conflicting sources by trusting official filings over campaign claims. Full prompt text withheld for security.", "dataSources": [ "Texas Secretary of State candidate filings", "County clerk election offices", "Ballotpedia", "Campaign websites", "Local news sources" ], "candidateFields": { "name": "Full legal name from official filings", "isIncumbent": "Whether they currently hold the office", "summary": "1-2 sentence neutral summary", "background": "Professional and personal background", "education": "Educational background", "keyPositions": "Array of policy positions from campaign materials", "endorsements": "Array of {name, type} objects — type is one of: labor union, editorial board, advocacy group, business group, elected official, political organization, professional association, community organization, public figure", "pros": "Array of strengths/arguments in their favor", "cons": "Array of concerns/arguments against", "polling": "Latest polling data if available, or null", "fundraising": "Fundraising totals if available, or null", "sources": "Array of {url, title, accessDate} objects — source citations for claims about this candidate, captured from Claude web_search API responses", "sourcesUpdatedAt": "ISO timestamp of when sources were last updated" }, "equalTreatment": "Every candidate in a race receives the same structured fields. The same prompt is used for all candidates in all races regardless of party, incumbency, or polling position." }, "dailyUpdater": { "description": "An automated daily cron job re-researches each contested race for new endorsements, polling, fundraising, and news. Updates are validated before being applied. Runs on the usvotes-api worker via daily cron. Both workers share the same KV namespace.", "model": "Claude Sonnet (Anthropic) with web_search tool", "systemPrompt": "System prompt instructs Claude to act as a nonpartisan election data researcher, find verified factual updates, follow the 7-tier source priority hierarchy, and resolve conflicts using the same rules as candidate research. Full prompt text withheld for security.", "raceResearchPromptTemplate": "Template sends current race data and asks Claude to search for new endorsements, polling, fundraising, and news updates since a cutoff date. Returns structured JSON with candidate-level fields. Full template text withheld for security.", "validationRules": [ "Candidate count must remain the same (no additions or removals)", "Candidate names must match exactly (no renaming)", "Endorsement lists cannot shrink by more than 50% (prevents accidental data loss)", "No empty strings in key fields (name, summary)", "Party cannot change between updates", "Empty arrays are rejected — prevents accidental data wipe", "Sources must have valid URLs, no duplicate URLs, max 20 per candidate" ], "mergeStrategy": "Non-null fields from Claude's response overwrite existing values. Null fields are skipped (existing data preserved). Each race is updated independently with 5-second delays between API calls to avoid rate limits. Source citations are captured from Claude web_search API response blocks and merged with deduplication.", "kvKeys": { "statewide": "ballot:statewide:{party}_primary_2026", "manifest": "manifest (version tracking per party)", "updateLog": "update_log:{YYYY-MM-DD} (daily log of all changes and errors)" } }, "dataStructure": { "sampleCandidate": { "id": "gov-jane-doe", "name": "Jane Doe", "isIncumbent": false, "summary": "Former state legislator running on education reform and fiscal responsibility.", "background": "Served 6 years in the Texas House representing District 45.", "education": "UT Austin, BA in Government; Harvard Kennedy School, MPA", "keyPositions": [ "Increase education funding", "Property tax reform", "Border security" ], "endorsements": [ { "name": "Texas Teachers Association", "type": "professional association" }, { "name": "Former Governor Smith", "type": "elected official" } ], "pros": [ "Deep legislative experience", "Strong fundraising", "Bipartisan track record" ], "cons": [ "Limited executive experience", "Some positions have shifted over time" ], "polling": "Leading with 35% in latest University of Texas poll", "fundraising": "$2.1M raised as of Q4 2025", "sources": [ { "url": "https://www.texastribune.org/2026/01/15/jane-doe-governor-race/", "title": "Jane Doe enters governor's race with education platform", "accessDate": "2026-02-22" }, { "url": "https://www.ballotpedia.org/Jane_Doe", "title": "Jane Doe - Ballotpedia", "accessDate": "2026-02-22" } ], "sourcesUpdatedAt": "2026-02-22T14:30:00Z" }, "sampleProposition": { "number": 1, "title": "Education Funding Amendment", "description": "Amends the Texas Constitution to allocate additional funding for public schools.", "background": "Texas ranks 43rd nationally in per-pupil spending.", "fiscalImpact": "Estimated $2B annual increase in education spending from general revenue.", "ifPasses": "Public school funding would increase by approximately $1,500 per student.", "ifFails": "Current funding levels would remain unchanged.", "supporters": [ "Texas Teachers Association", "Parent advocacy groups" ], "opponents": [ "Taxpayer advocacy groups", "Some fiscal conservatives" ] } }, "nonpartisanSafeguards": { "promptLevel": [ "Every system prompt explicitly states 'non-partisan' or 'nonpartisan'", "Explicit prohibition on partisan framing and loaded terms", "Must treat all candidates with equal analytical rigor", "Reasoning must connect to voter's stated values, not party assumptions", "Profile summaries must never use party labels" ], "dataLevel": [ "Both party ballots generated with identical prompts and data structures", "Every candidate gets the same fields: summary, pros, cons, endorsements, positions", "Candidate research uses identical web_search methodology for all candidates", "Validation prevents asymmetric data quality between parties" ], "uiLevel": [ "Candidate order randomized on every page load", "Party labels hidden from candidate cards", "Interview answer options shuffled", "Six-point political spectrum (not binary left/right): Progressive, Liberal, Moderate, Conservative, Libertarian, Independent", "Confidence levels (Strong Match, Good Match, Best Available) prevent false certainty", "Disclaimer on every recommendation screen: 'Do your own research before voting'" ], "translationLevel": [ "Spanish translations use identical grammatical structures for both parties", "Candidate names, office titles, and data terms stay in English for accuracy", "Only the UI display layer is translated", "All translations reviewed for partisan bias" ] }, "sourceRankingPolicy": { "description": "All AI research prompts include an explicit source priority hierarchy to ensure web_search results are evaluated in order of reliability. This was added based on ChatGPT AI audit feedback recommending documented source preferences.", "hierarchy": [ { "tier": 1, "source": "Texas Secretary of State filings", "examples": [ "sos.state.tx.us" ], "trust": "Highest — official government filings" }, { "tier": 2, "source": "County election offices", "examples": [ "{county}.tx.us" ], "trust": "Official local government data" }, { "tier": 3, "source": "Official campaign websites", "examples": [ "candidate campaign sites" ], "trust": "Direct from candidates — verify claims against filings" }, { "tier": 4, "source": "Nonpartisan references", "examples": [ "ballotpedia.org", "votesmart.org" ], "trust": "Established nonpartisan voter information" }, { "tier": 5, "source": "Established Texas news outlets", "examples": [ "texastribune.org", "dallasnews.com" ], "trust": "Professional journalism with editorial standards" }, { "tier": 6, "source": "National wire services", "examples": [ "apnews.com", "reuters.com" ], "trust": "Factual reporting with editorial oversight" }, { "tier": 7, "source": "Blogs, social media, opinion sites", "examples": [], "trust": "Lowest — avoided unless no other source exists" } ], "conflictResolution": "When sources disagree: official filings override campaign claims, and campaign claims override news reporting.", "enforcement": "SOURCE PRIORITY and CONFLICT RESOLUTION rules are embedded in the system prompts of both the daily updater (updater.js) and the county data seeder (county-seeder.js). The web_search tool is Claude's built-in tool — we cannot filter its results at the API level, so prompt-level preferences are the pragmatic enforcement mechanism.", "promptsIncludingPolicy": [ "updater.js researchRace()", "county-seeder.js callClaudeWithSearch()" ] }, "interviewQuestions": { "description": "The voter interview collects preferences through neutrally-framed questions. No question assumes or implies a correct answer. Answer options are shuffled on every load to prevent order bias.", "phases": [ { "name": "Party Selection", "description": "Voter selects which party primary they want to vote in. Both primaries are presented equally." }, { "name": "Political Spectrum", "description": "Six options presented with descriptions. Includes 'No wrong answers' reassurance." }, { "name": "Top Issues", "description": "Voter selects their 3-5 most important issues from a comprehensive list covering all political perspectives." }, { "name": "Policy Deep Dives", "description": "For each selected issue, the voter answers specific policy questions with 4 balanced answer options. Options are shuffled." }, { "name": "Candidate Qualities", "description": "Voter selects what qualities they value most in candidates from a list of 10 options." }, { "name": "Free-form", "description": "Optional open text field: 'Anything else you want the AI to know about your views?'" }, { "name": "Address Lookup", "description": "Address used only for district resolution via Census Bureau API. Not stored on server." }, { "name": "Guide Generation", "description": "Profile + ballot data sent to Claude. Both party ballots generated with identical methodology." } ], "issues": [ { "value": "Economy & Cost of Living", "icon": "💰" }, { "value": "Housing", "icon": "🏠" }, { "value": "Public Safety", "icon": "🛡️" }, { "value": "Education", "icon": "🎓" }, { "value": "Healthcare", "icon": "❤️" }, { "value": "Environment & Climate", "icon": "🌿" }, { "value": "Grid & Infrastructure", "icon": "⚡" }, { "value": "Tech & Innovation", "icon": "💻" }, { "value": "Transportation", "icon": "🚗" }, { "value": "Immigration", "icon": "🌎" }, { "value": "Taxes", "icon": "💵" }, { "value": "Civil Rights", "icon": "⚖️" }, { "value": "Gun Policy", "icon": "🎯" }, { "value": "Abortion & Reproductive Rights", "icon": "⚕️" }, { "value": "Water & Land", "icon": "💧" }, { "value": "Agriculture & Rural", "icon": "🌾" }, { "value": "Faith & Religious Liberty", "icon": "🕌" }, { "value": "Criminal Justice", "icon": "⚖️" }, { "value": "Energy & Oil/Gas", "icon": "🛢️" }, { "value": "LGBTQ+ Rights", "icon": "🏳️" }, { "value": "Voting & Elections", "icon": "🗳️" } ], "politicalSpectrum": [ { "value": "Progressive", "description": "Bold systemic change, social justice focused" }, { "value": "Liberal", "description": "Expand rights and services, government as a force for good" }, { "value": "Moderate", "description": "Pragmatic center, best ideas from both sides" }, { "value": "Conservative", "description": "Limited government, traditional values, fiscal discipline" }, { "value": "Libertarian", "description": "Maximum freedom, minimal government" }, { "value": "Independent / Issue-by-Issue", "description": "I decide issue by issue, not by party" } ], "candidateQualities": [ "Competence & Track Record", "Integrity & Honesty", "Independence", "Experience", "Fresh Perspective", "Bipartisan / Works Across Aisle", "Strong Leadership", "Community Ties", "Faith & Values", "Business Experience" ], "policyDeepDives": { "Housing": { "question": "On housing, where do you land?", "options": [ { "label": "Build, build, build", "description": "Ease zoning, encourage density, let the market work" }, { "label": "Smart growth", "description": "More housing with affordability guardrails" }, { "label": "Protect property rights", "description": "Keep property taxes low, limit government land-use rules" }, { "label": "It's complicated", "description": "Case by case — depends on the community" } ] }, "Public Safety": { "question": "On public safety, what's your approach?", "options": [ { "label": "Fully fund police", "description": "Hire more officers, strong prosecution" }, { "label": "Reform + fund", "description": "Fund police but invest in alternatives too" }, { "label": "Redirect funding", "description": "Move money toward prevention and social services" }, { "label": "Major overhaul needed", "description": "Fundamental changes to how we approach safety" } ] }, "Economy & Cost of Living": { "question": "On taxes and government spending?", "options": [ { "label": "Cut taxes & spending", "description": "Government does too much, let people keep their money" }, { "label": "Redirect spending", "description": "Redirect existing funds toward higher-priority programs" }, { "label": "Invest more if it works", "description": "Willing to pay more for effective programs" }, { "label": "Tax the wealthy more", "description": "Fund services through progressive taxation" } ] }, "Tech & Innovation": { "question": "On tech and AI regulation?", "options": [ { "label": "Hands off", "description": "Let innovation lead, regulate later if needed" }, { "label": "Light touch", "description": "Basic guardrails but don't slow things down" }, { "label": "Proactive regulation", "description": "Get ahead of problems before they happen" }, { "label": "Strong oversight", "description": "Tech companies have too much unchecked power" } ] }, "Education": { "question": "On public education, what's your priority?", "options": [ { "label": "School choice first", "description": "Vouchers, charters, let parents decide" }, { "label": "Fix public schools", "description": "More funding and support for neighborhood schools" }, { "label": "Teacher-focused", "description": "Raise pay, reduce class sizes, trust educators" }, { "label": "Back to basics", "description": "Focus on core academics, less politics in schools" } ] }, "Healthcare": { "question": "On healthcare, where do you stand?", "options": [ { "label": "Free market", "description": "Less regulation, more competition to lower costs" }, { "label": "Expand Medicaid", "description": "Texas should accept federal Medicaid expansion" }, { "label": "Universal coverage", "description": "Everyone deserves healthcare regardless of income" }, { "label": "Local solutions", "description": "Community health centers and county programs" } ] }, "Environment & Climate": { "question": "On environment and climate?", "options": [ { "label": "Don't overreact", "description": "Protect energy jobs, market-driven solutions" }, { "label": "All of the above", "description": "Renewables and fossil fuels, pragmatic transition" }, { "label": "Go green fast", "description": "Aggressive renewable targets and climate action" }, { "label": "Local focus", "description": "Clean air and water, green spaces, urban heat" } ] }, "Grid & Infrastructure": { "question": "On the power grid and infrastructure?", "options": [ { "label": "Deregulate more", "description": "Competition drives reliability, less ERCOT control" }, { "label": "Weatherize & invest", "description": "Mandate upgrades, spend what it takes to prevent outages" }, { "label": "Connect the grid", "description": "Link Texas to national grid for backup" }, { "label": "Local resilience", "description": "Microgrids, batteries, community-level solutions" } ] }, "Transportation": { "question": "On transportation, what's the priority?", "options": [ { "label": "Build more roads", "description": "Expand highways, farm-to-market roads, reduce congestion" }, { "label": "Public transit", "description": "Rail, better buses, less car dependence in metro areas" }, { "label": "Balanced approach", "description": "Roads, transit, bikes, and walkability together" }, { "label": "Rural infrastructure", "description": "Fix rural roads, improve connectivity between small towns" } ] }, "Immigration": { "question": "On immigration, what's your view?", "options": [ { "label": "Secure the border", "description": "Enforcement first, then talk about reform" }, { "label": "Enforce but reform", "description": "Secure borders AND create legal pathways" }, { "label": "Welcoming approach", "description": "Immigrants strengthen our communities, expand protections" }, { "label": "State should stay out", "description": "Immigration is a federal issue, not a state priority" } ] }, "Civil Rights": { "question": "On civil rights and equality?", "options": [ { "label": "Equal treatment", "description": "Same rules for everyone, no special categories" }, { "label": "Protect what we have", "description": "Maintain current protections, don't roll them back" }, { "label": "Expand protections", "description": "Stronger anti-discrimination laws and enforcement" }, { "label": "Systemic change", "description": "Address root causes of inequality, not just symptoms" } ] }, "Gun Policy": { "question": "On gun policy, where do you stand?", "options": [ { "label": "Expand gun rights", "description": "Broaden carry permissions, reduce permitting requirements" }, { "label": "Maintain current laws", "description": "Keep current firearm laws without additional restrictions" }, { "label": "Ownership with safeguards", "description": "Support gun ownership with background checks and safety rules" }, { "label": "Strengthen regulations", "description": "Universal background checks, red flag laws, waiting periods" } ] }, "Abortion & Reproductive Rights": { "question": "On abortion and reproductive rights?", "options": [ { "label": "Pro-life, no exceptions", "description": "Protect life from conception, support current Texas ban" }, { "label": "Pro-life with exceptions", "description": "Ban most abortions but allow rape, incest, life of mother" }, { "label": "Restore some access", "description": "Current ban goes too far, allow early-term abortion" }, { "label": "Pro-choice", "description": "Women should make their own reproductive decisions" } ] }, "Water & Land": { "question": "On water and land use in Texas?", "options": [ { "label": "Property rights first", "description": "Landowners should control their water and land" }, { "label": "Protect rural water", "description": "Ban large-scale water exports, protect aquifers" }, { "label": "Conservation focus", "description": "Stricter regulations to prevent water waste and pollution" }, { "label": "Major investment", "description": "Build new reservoirs, desalination, and infrastructure" } ] }, "Agriculture & Rural": { "question": "On agriculture and rural Texas?", "options": [ { "label": "Support family farms", "description": "Protect small farms, limit corporate agriculture dominance" }, { "label": "Free market farming", "description": "Less regulation, let farmers compete globally" }, { "label": "Rural investment", "description": "Broadband, hospitals, schools — invest in rural communities" }, { "label": "Sustainable agriculture", "description": "Incentivize conservation, regenerative farming practices" } ] }, "Taxes": { "question": "On taxes, what's your priority?", "options": [ { "label": "Cut taxes across the board", "description": "Lower property and sales taxes for everyone" }, { "label": "Reform, not raise", "description": "Close loopholes, make the system fairer without raising rates" }, { "label": "Tax the wealthy more", "description": "Higher-income Texans should pay a larger share" }, { "label": "No income tax, ever", "description": "Protect Texas's no-income-tax status at all costs" } ] }, "Faith & Religious Liberty": { "question": "On faith and religious liberty?", "options": [ { "label": "Protect religious freedom", "description": "Strong legal protections for faith-based beliefs and practices" }, { "label": "Accommodate both", "description": "Protect religious freedom while respecting others' rights" }, { "label": "Strict separation", "description": "Keep religion out of government and public policy" }, { "label": "Faith guides policy", "description": "Moral and religious values should shape our laws" } ] }, "Criminal Justice": { "question": "What's your approach to criminal justice?", "options": [ { "label": "Strengthen law enforcement", "description": "Increase funding for police, prosecution, and victim services" }, { "label": "Maintain current system", "description": "Texas's approach to law and order is working, keep sentences firm" }, { "label": "Reform sentencing laws", "description": "Reduce mandatory minimums, address racial disparities in sentencing" }, { "label": "Focus on rehabilitation", "description": "Invest in re-entry programs, reduce recidivism through support services" } ] }, "Energy & Oil/Gas": { "question": "How should Texas manage its energy industry?", "options": [ { "label": "Maximize production", "description": "Support oil and gas expansion, reduce regulations on producers" }, { "label": "Mixed energy strategy", "description": "Maintain fossil fuels while investing in renewables and grid stability" }, { "label": "Accelerate clean energy", "description": "Transition away from fossil fuels toward wind, solar, and storage" }, { "label": "Let the market decide", "description": "Remove subsidies for all energy sources, let competition set the course" } ] }, "LGBTQ+ Rights": { "question": "What's the right approach to LGBTQ+ rights?", "options": [ { "label": "Full equality protections", "description": "Add sexual orientation and gender identity to anti-discrimination laws" }, { "label": "Accommodate both", "description": "Protect LGBTQ+ individuals while preserving faith-based exemptions" }, { "label": "Current laws are sufficient", "description": "Existing legal protections are adequate, no new legislation needed" }, { "label": "Parental rights focus", "description": "Parents should direct decisions about children's healthcare and education" } ] }, "Voting & Elections": { "question": "What matters most for elections?", "options": [ { "label": "Expand voter access", "description": "Make registration easier, extend early voting, allow mail-in ballots for all" }, { "label": "Strengthen ID requirements", "description": "Require photo ID, verify citizenship, secure the voter rolls" }, { "label": "Combined approach", "description": "Improve access and security together with bipartisan oversight" }, { "label": "Local control", "description": "Let counties and cities set their own election rules and procedures" } ] } } }, "countySeeder": { "description": "County-level data is populated using Claude with web_search for each of Texas's top 30 counties by population (~75% of voters). Four data artifacts are generated per county: voting logistics, Republican ballot, Democratic ballot, and precinct map.", "model": "Claude Sonnet (Anthropic) with web_search tool", "systemPrompt": "System prompt instructs Claude to act as a nonpartisan election data researcher for Texas counties, use web_search for verified information, follow the 7-tier source priority hierarchy, and never fabricate information. Full prompt text withheld for security.", "countyInfoPrompt": "Template asks Claude to research voting logistics (vote centers, elections website, early voting dates, phone-in-booth rules) for a specific Texas county. Returns structured JSON. Full template text withheld for security.", "countyBallotPrompt": "Template asks Claude to research all local primary races for a specific Texas county, including county judge, commissioners, clerks, sheriffs, and other county-level offices. Returns structured JSON with candidate details. Full template text withheld for security.", "precinctMapPrompt": "Template asks Claude to research County Commissioner precinct boundaries using multi-step strategy: county GIS portals, PDF maps, voting precinct first-digit convention, and county-specific hints. Maps ZIP codes to commissioner precinct numbers (1-4) using majority-precinct assignment. Uses 15 web searches. Returns validated structured JSON. Full template text withheld for security.", "dataSources": [ "Texas Secretary of State candidate filings", "County clerk election offices", "County elections websites", "Ballotpedia", "Local news sources", "County GIS and precinct boundary data" ], "topCounties": [ "Harris", "Dallas", "Tarrant", "Bexar", "Travis", "Collin", "Denton", "Hidalgo", "Fort Bend", "Williamson", "Montgomery", "El Paso", "Nueces", "Galveston", "Brazoria", "Kaufman", "Johnson", "Parker", "Lubbock", "Cameron", "McLennan", "Bell", "Gregg", "Randall", "Potter", "Smith", "Victoria", "Jefferson", "Midland", "Ector" ], "kvKeyStructure": { "countyInfo": "county_info:{fips}", "countyBallot": "ballot:county:{fips}:{party}_primary_2026", "precinctMap": "precinct_map:{fips}" }, "equalTreatment": "Both party ballots for each county use identical prompt structure. The same candidate fields (summary, pros, cons, endorsements, positions) are generated for every candidate regardless of party or incumbency.", "sourceValidation": "The county seeder validates source citations during data population. Sources must have valid URLs with no duplicates, capped at 20 per candidate. The 7-tier source priority hierarchy is enforced at the prompt level, and CONFLICT RESOLUTION rules ensure official filings take precedence over campaign claims and news reporting." }, "balanceChecks": { "description": "Automated pros/cons balance checks ensure every candidate receives equal analytical treatment. The /api/balance-check endpoint runs symmetry scoring across all races and flags imbalances at critical, warning, and info severity levels. Results are integrated into the Data Quality Dashboard.", "endpoint": "/api/balance-check", "scoring": "Each race is scored 0-100 based on symmetry of pros/cons counts, detail length, and consistent coverage across all candidates. Combined score is the average across both party ballots.", "severityLevels": { "critical": "Major imbalance that could appear biased (e.g., one candidate has 5 pros and another has 0)", "warning": "Moderate imbalance worth reviewing (e.g., significant difference in detail length)", "info": "Minor asymmetry that is acceptable but noted for transparency" }, "integration": "Balance scores are displayed on the Data Quality Dashboard with drill-down flag details. The balance check runs automatically and is available as a public JSON API." }, "biasReporting": { "description": "A 'Flag this info' button on candidate cards allows voters to report potential bias or inaccuracy. Reports are sent to flagged@txvotes.app with structured issue types for review and correction.", "feature": "Flag this info button on candidate cards in the PWA", "reportEmail": "flagged@txvotes.app", "issueTypes": [ "Factual inaccuracy", "Biased framing", "Missing information", "Outdated information", "Other" ], "workflow": "Voter taps 'Flag this info' on a candidate card, selects an issue type, optionally adds details, and submits. The report is emailed for manual review and correction." }, "strengthsConcernsDisplay": { "description": "Candidate strengths and concerns are displayed directly on ballot recommendation cards using green (strengths) and orange (concerns) styled boxes. This gives voters immediate visibility into the balanced analysis for each candidate without needing to expand the full profile." }, "toneVariants": { "description": "Candidate summaries, pros, cons, and proposition text are pre-generated at multiple reading levels (tones). This allows voters to read ballot information at their preferred complexity without re-calling the AI at guide-generation time. Tone 3 is the default (standard news level). Other tones are generated by asking Claude to rewrite the original text while preserving factual accuracy.", "model": "Claude Sonnet (Anthropic)", "availableTones": { "1": { "label": "Simple", "description": "High school reading level. Simple, everyday language. No jargon. Written as if for a first-time voter." }, "2": { "label": "Casual", "description": "Like explaining politics to a friend. Conversational and approachable. Minimal jargon." }, "3": { "label": "Standard (default)", "description": "News-level writing. No tone instruction added — this is the original researched text." }, "4": { "label": "Detailed", "description": "More depth and nuance. Precise political terminology. Assumes the reader follows politics." }, "5": { "label": "Expert", "description": "Political science professor level. Precise terminology, policy frameworks and precedents, deep familiarity assumed." }, "7": { "label": "Texas Cowboy", "description": "Easter egg: Folksy Texas cowboy voice. Y'all, reckon, fixin' to. Ranch metaphors and campfire wisdom. Candidate names and office titles remain accurate." } }, "candidateFields": [ "summary", "pros", "cons" ], "propositionFields": [ "description", "ifPasses", "ifFails", "background", "fiscalImpact" ], "rewritePromptTemplate": "Template asks Claude to rewrite text fields in a specified tone while preserving factual content. Returns JSON with field names and rewritten text. Full template text withheld for security.", "storageFormat": "Each field that has tone variants is stored as an object keyed by tone level: { \"1\": \"simple version\", \"3\": \"original version\", \"4\": \"detailed version\" }. Fields without variants remain plain strings. The resolveTone() function extracts the appropriate version at display time, defaulting to tone 3.", "constraints": [ "Tone rewrites must preserve all factual content — only language style changes", "Candidate names, office titles, and numerical data are never modified", "Each tone variant is a separate KV write to limit API costs", "Tone 3 is always the original researched text, never rewritten" ] } }