Building Your First Bill: A Step-by-Step Guide to the Bill Builder

Building Your First Bill: A Step-by-Step Guide to the Bill Builder

Learn how to design, score, and share custom policy bills that project real impacts on American households.

David H. Friedel Jr.· 2026-05-17 ·Policy tax tariff spending Bill

Introduction

Policy debates often feel abstract—tax rates, tariff schedules, spending caps. But every policy choice ripples through the economy and lands differently on real households. Civitas brings those impacts into focus with the Bill Builder, a design surface where you compose policy provisions into full legislative packages, score them against a baseline economy, and see exactly how they affect personas representing different wealth quintiles and life stages.

Whether you're exploring a universal basic income, modeling a carbon tax, or stress-testing a new tax reform, the Bill Builder gives you a macroeconomic flight simulator cockpit. This guide walks you through your first bill—from selecting provisions to interpreting the household-level results that matter most.

What You'll Learn

  • How to open the Bill Builder and understand its layout
  • How to select and combine policy provisions into a cohesive bill
  • What the scoring results mean (deficits, inflation, GDP, and more)
  • How to compare impacts across personas and interpret distributional verdicts
  • How to save, share, and iterate on your bill designs
  • Pro tips for designing effective, balanced policy packages

Understanding Policy Provisions

Before you build a bill, you need to understand the building blocks: policy provisions. In Civitas, a provision is a discrete policy event—a single lever pull or set of coordinated lever changes that represent a real-world policy action.

What's in a Provision?

Each provision modifies one or more of the ~30 economic levers in the simulation engine:

  • Fiscal levers: IncomeTaxRate, CorporateTaxRate, CapitalGainsTaxRate, FederalSpending, UniversalBasicIncome
  • Monetary levers: FedFundsRate, QuantitativeEasing
  • Trade levers: TariffRate, TradeAgreementBoost
  • Labor & demographics: ImmigrationRate, AILaborDisplacement
  • Hazard channels: HeatIntensity, PandemicIntensity, WarIntensity

Builtin vs. Custom Provisions

Civitas ships with 15+ historical bills (TCJA, CARES Act, ACA, OBBBA 2025, etc.) and dozens of standalone provisions (UBI variants, carbon taxes, tariff packages, immigration reforms). You can also create custom provisions in the Provisions page—useful for modeling hypothetical policies or tweaking existing ones.

Composing Provisions: Additive, Not Overwrite

When you add multiple provisions to a bill, Civitas uses PolicyEventComposer to merge them additively:

This additive logic lets you layer policies naturally—combine a tax cut with a spending increase, or pair a UBI with a carbon tax to model revenue-neutral packages.

Opening the Bill Builder

The Bill Builder is your policy design studio. Here's how to access it and understand its layout.

Launch from the Bills Page

  1. Open Civitas and navigate to the Bills page (sidebar icon: document stack)
  2. Click New Bill in the top toolbar, or select an existing bill and click Edit
  3. The Bill Builder opens with a clean slate (or your selected bill's provisions pre-loaded)

Bill Builder Layout

The Bill Builder is divided into three main areas:

  • Left pane: Provision Library
    Browse all available provisions (historical bills, standalone events, your custom provisions). Search, filter by category, and preview lever changes.

  • Center pane: Bill Canvas
    The provisions you've added to your bill. Drag to reorder, click to remove, see the composite lever summary at the bottom.

  • Right pane: Tabs (Details / Ask AI)

    • Details: Shows the current bill's metadata (name, description, expected CBO scores if available)
    • Ask AI: Chat with Civitas AI to get provision suggestions, explain lever interactions, or brainstorm policy combinations

Naming Your Bill

Give your bill a descriptive name and optional description. This helps when you return to the Bills library later:

Name: "Green New Deal Lite"
Description: "Carbon tax + clean energy subsidies + job retraining"

Selecting and Adding Provisions

Now the fun begins: composing your bill from individual provisions.

Step 1: Browse the Provision Library

In the left pane, you'll see provisions grouped by type:

  • Historical Bills: TCJA, CARES Act, ACA, OBBBA 2025, etc.
  • Tax Reforms: Income tax cuts/hikes, corporate tax changes, capital gains adjustments
  • Spending Programs: Infrastructure, defense, education, UBI variants
  • Trade & Tariffs: Tariff packages, trade agreement boosts
  • Immigration & Labor: Immigration rate changes, AI labor displacement scenarios
  • Hazard Events: Climate intensity, pandemic waves, war shocks
  • Custom Provisions: Your own creations

Step 2: Inspect a Provision

Click any provision to see its lever changes in the preview pane:

Provision: "UBI $1000/month"
Levers:
  UniversalBasicIncome: +12000  # $12k/year per adult
  IncomeTaxRate: +0.05          # 5pp income tax hike to fund

This helps you understand what each provision does before adding it.

Step 3: Add to Your Bill

Drag the provision from the library to the Bill Canvas (center pane), or double-click to add. The provision appears as a card in your bill's composition.

Step 4: Combine Provisions

Add 2-5 provisions to create a realistic policy package. For example, a revenue-neutral climate bill might include:

  1. Carbon Tax ($50/ton) → raises revenue, increases energy costs
  2. Clean Energy Subsidies → federal spending on renewables
  3. UBI Dividend ($500/month) → rebates carbon tax revenue to households

As you add provisions, the Composite Levers summary at the bottom updates to show the net effect:

Net Levers:
  IncomeTaxRate: +0.02
  FederalSpending: +0.03
  UniversalBasicIncome: +6000
  HeatIntensity: -0.1  # Climate mitigation

Step 5: Remove or Reorder

Click the X on any provision card to remove it. Drag cards to reorder (order matters for narrative, but composite levers are always additive).

Scoring Your Bill: What the Numbers Mean

Once your bill is composed, it's time to score it—run the simulation to see how your policy package performs vs. the baseline economy.

Running the Score

Click Score Bill in the top toolbar. Civitas runs two simulations:

  1. Baseline: The economy with no policy changes (current trajectory)
  2. Counterfactual: The economy with your bill's provisions applied

The simulator projects 120 months (10 years) across 30+ economic levers and every persona in your selected comparison set.

Key Metrics

The scoring results appear in the Details tab (right pane):

Macroeconomic Indicators

  • Deficit Impact: How much your bill adds to (or subtracts from) the federal deficit over 10 years, in trillions
    Example: +$2.1T (increases deficit by $2.1 trillion)

  • Inflation Impact: Percentage point change in inflation rate
    Example: +0.8pp (inflation rises 0.8 percentage points)

  • GDP Impact: Percentage change in GDP growth rate
    Example: -0.3% (GDP growth slows slightly)

  • Unemployment Impact: Percentage point change in unemployment rate
    Example: -0.5pp (unemployment falls half a point)

Validation (Historical Bills Only)

If you're scoring a historical bill (e.g., TCJA), Civitas compares modeled results to expected CBO scores:

Expected Deficit: $1.9T  
Modeled Deficit:  $2.1T  
Verdict: ≈ (Close match)

Verdicts: ✓ (match), ≈ (close), ✗ (divergence)

Understanding the Numbers

These top-line metrics are useful, but they don't tell the whole story. A bill that "grows GDP" might still hurt low-income households if gains accrue to the wealthy. That's why persona-level impacts are the heart of Civitas.

Comparing Persona Impacts

The real power of Civitas is seeing how your bill affects individual households—not just aggregates. After scoring, navigate to the Persona Impacts section.

What Are Personas?

Personas are representative households across the income/wealth distribution:

  • Quintile Representatives: Q1 (Maya, bottom 20%), Q2 (Jamal), Q3 (Aisha), Q4 (Raj), Q5 (Elena), Top 1% (David), Top 0.1% (Charles)
  • Life-Stage Archetypes: Young professional, mid-career family, retiree, single parent
  • Hazard-Exposure Archetypes: Coastal (climate risk), frontline worker (pandemic), etc.

Each persona has a starting wealth, income, consumption pattern, and hazard exposure weights (e.g., coastal personas are more exposed to HeatIntensity).

Reading Persona Impact Cards

For each persona, you'll see:

Maya (Q1, Bottom 20%)
  Wealth Change: +$18,000 (+45%)  
  Income Change: +$3,200/year (+12%)  
  Lived Impact: "Moves from precarious to stable" ✓

Charles (Top 0.1%)
  Wealth Change: -$2.1M (-8%)  
  Income Change: -$85,000/year (-4%)  
  Lived Impact: "Remains ultra-wealthy" ○

Lived Impact Classification

Civitas uses LivedImpactClassifier to frame outcomes by ending wealth tier, not just percentage change. This avoids misleading interpretations like "Charles lost 90%—disaster!" when he still has $2M left.

Lived impact labels:

  • ✓ Transformative gain: Moved up a wealth tier (e.g., precarious → stable)
  • ↑ Meaningful gain: Significant improvement within tier
  • ○ Neutral: Modest change, same tier
  • ↓ Meaningful loss: Significant decline within tier
  • ✗ Severe loss: Dropped a wealth tier (e.g., comfortable → precarious)

Distributional Verdict

At the bottom of the Persona Impacts section, you'll see a distributional verdict:

Distributional Verdict: Progressive ✓
  Q1 (Maya): +45%  
  Top 0.1% (Charles): -8%  
  Gap narrowed by 12 percentage points

Verdicts:

  • Progressive: Q1 gains more (or loses less) than top 0.1%; wealth gap narrows
  • Regressive: Top 0.1% gains more (or loses less) than Q1; wealth gap widens
  • Neutral: Similar impacts across distribution
  • Mixed: Some quintiles gain, others lose (no clear pattern)

This single metric cuts through the noise and tells you who wins and who loses.

Comparing Across Groups

You can switch comparison sets in the Dashboard to see impacts across different groupings:

  • Quintile: Default, shows income/wealth distribution
  • Life-Stage: Young vs. mid-career vs. retiree
  • Hazard Archetypes: Coastal, frontline worker, rural (useful for climate/pandemic bills)
  • Custom Groups: Your own persona groupings (create in the Groups page)

Saving and Sharing Your Bill

Once you're happy with your bill and its scoring results, it's time to save and share.

Saving Your Bill

Click Save Bill in the top toolbar. Your bill is persisted to the SQLite database (via IBillRepository) and appears in the Bills library. You can return to it anytime to:

  • Re-score with updated personas or comparison sets
  • Edit provisions (add/remove/reorder)
  • Compare against other bills in the Dashboard
  • Export for external analysis

Importing Bills

You can also import bills from JSON. Useful for:

  • Loading bills shared by others
  • Restoring bills from backups
  • Batch-loading a library of scenarios

Tips for Effective Bill Design

Designing a good bill is part art, part science. Here are pro tips to help you create realistic, insightful policy packages.

1. Start with a Clear Goal

Before adding provisions, define what you're trying to achieve:

  • Reduce inequality? Focus on progressive tax reforms, UBI, or targeted transfers
  • Stimulate growth? Try corporate tax cuts, infrastructure spending, or immigration boosts
  • Control inflation? Tighten fiscal policy, raise interest rates, or reduce spending
  • Climate resilience? Model carbon taxes, clean energy subsidies, or hazard mitigation

A clear goal helps you select provisions that work together, not at cross-purposes.

2. Balance Revenue and Spending

Unless you're explicitly modeling a deficit-financed stimulus, aim for revenue neutrality:

  • If you add spending (UBI, infrastructure), pair it with revenue raisers (tax hikes, tariffs)
  • If you cut taxes, pair it with spending cuts or efficiency gains

Example: Carbon Tax + UBI Dividend is revenue-neutral by design—carbon tax revenue funds the UBI.

3. Use the AI Chat for Suggestions

Stuck? Click the Ask AI tab and ask:

  • "What provisions pair well with a carbon tax?"
  • "How can I make this bill more progressive?"
  • "What are the trade-offs of raising the corporate tax rate?"

Civitas AI uses function calling to suggest provisions, explain lever interactions, and flag potential issues (e.g., "This bill will spike inflation—consider pairing with monetary tightening").

4. Test Across Multiple Comparison Sets

Don't just score against the default quintile set. Switch to:

  • Life-Stage to see how retirees vs. young workers fare
  • Hazard Archetypes to see how coastal vs. rural households are affected (especially for climate bills)
  • Custom Groups to model your own household or community

This reveals hidden winners and losers that aggregate metrics miss.

5. Iterate and Refine

Your first bill won't be perfect. After scoring:

  • Check the distributional verdict—is it what you expected?
  • Review persona impacts—are there unintended losers?
  • Adjust provisions and re-score

Example: If your UBI bill is too regressive (because it's funded by a flat sales tax), swap the sales tax for a progressive income tax hike.

6. Validate Against Historical Bills

If you're modeling a real-world policy, compare your bill to Civitas's historical bill library:

  • How does your tax reform compare to TCJA?
  • Is your stimulus bigger or smaller than the CARES Act?
  • Does your healthcare plan match ACA's coverage expansion?

This grounds your analysis in real legislative benchmarks.

7. Document Your Assumptions

Use the Description field to note:

  • Why you chose these provisions
  • What trade-offs you accepted
  • What you're trying to test

Example:

Description: "Testing whether a $1000/month UBI funded by a 5pp income tax hike is progressive. Hypothesis: Low-income households gain more from UBI than they lose from tax hike."

This helps you (and others) understand your bill's intent when you revisit it later.

8. Share and Solicit Feedback

Policy design benefits from diverse perspectives. Share your bill URL with:

  • Colleagues or classmates
  • Online communities (Reddit, Twitter, policy forums)
  • Domain experts (economists, policy analysts)

Their feedback will surface blind spots and improve your analysis.

Ready to Build?

You now have the tools to design, score, and share sophisticated policy bills in Civitas. Open the Bill Builder, start composing provisions, and see how your ideas play out across the economy. Remember: every policy choice has winners and losers—Civitas helps you see exactly who they are.

Happy building! 🏛️

Back to Blog