[MaxGhenis]

Adds a "Questions" section below the results, written for general visitors, with a "Questions" link in the header. It has nine questions, each a native <details>/<summary> disclosure inside a labelled region:

1. What does GiveCalc calculate?
2. Why did my gift save little or nothing?
3. What changed for 2026?
4. What does "Share of income" do?
5. How does the bunching check work?
6. How does Gift Aid work in GiveCalc?
7. What does GiveCalc leave out?
8. Is my information stored?
9. Where does the model come from?

The copy follows Max's d1646 ruling: general audiences first, with no "pledge" in the copy. It also follows the PolicyEngine message house: active voice, sentence case, no emoji, and boundaries stated flat.

Where the numbers come from

• Results come from production API runs of the households in frontend/src/lib/faqCases.ts. Each household is one the calculator's links open: a single 30-year-old with wages only. bun run faq-numbers sends each request the way the calculator does and writes frontend/src/lib/faqNumbers.json. The run was against production on 2026-10-22.

  • California, $75,000 in wages:
    • $1,000 gift in 2026 saves $220;
    • $5,000 saves $220;
    • $8,000 saves $393, from California's own itemized deduction;
    • $1,000 in 2025 saved $0.
  • New York, $150,000: $30,000 in 2026 and nothing in 2027 saves $2,820 more than $15,000 in each year.
  • Texas, $1,000,000: giving $110,000 instead of $100,000 in 2026 saves $3,500 more, 35 cents a dollar.
  • UK, 2026/27: a £1,000 gift saves £250 at £70,000 and £0 at £35,000.

• Rules come from frontend/src/lib/faqRules.json:

  • $1,000 or $2,000 for non-itemizers;
  • the 0.5%-of-AGI floor;
  • 37% and 2/37;
  • the 20% basic rate;
  • 21% Scottish intermediate;
  • the £100,000 taper.

  tests/test_faq_numbers.py checks each against the policyengine-us 2.49.2 and policyengine-uk 2.134.6 parameters.

• Each US example links to the calculator while the calculator offers its year. In the browser, the links give $780 and $78,522 in cost, and "Saved on the next $1: 35.0%" for Texas.

Invariants (tested)

• Differential. The API code at the uv.lock pins gives the recorded production answer for every FAQ request, to the cent. This is in tests/test_faq_numbers.py.
• Provenance:
  • each recorded request equals what toCalculateRequest / ukApiRequest builds for its case today;
  • each US case is shareable;
  • the fixture records the versions modal_app.py deploys.
• The prose's relations hold in the fixture:
  • "the same $220": the $5,000 savings equal the $1,000 savings;
  • "saved nothing": the 2025 savings are 0;
  • the $8,000 gift saves more than the $5,000 gift, by no more than California's 13.3% top rate on the extra $3,000;
  • the bunching gain equals the bunched savings minus both years' savings, and is positive;
  • the Texas marginal is 0.37 × 35/37;
  • UK basic-rate relief is 0, and higher-rate relief is 20% of the gift grossed up at 20%.
• No calendar time bombs. Example links show only while their year is offered, and exampleHref is tested with explicit year lists.

How the claims were verified

Every mechanism claim was traced to code in this session:

• policyengine-us:
  • charitable_deduction_for_non_itemizers;
  • deductions_if_not_itemizing.yaml;
  • the charitable_deduction floor;
  • itemized_taxable_income_deductions_reduction;
  • tax_unit_itemizes;
  • ca_deductions;
  • the local income tax list;
  • the AZ/MS credit inputs GiveCalc never sets.
• policyengine-uk:
  • gift_aid_grossed_up;
  • calc_income_tax_with_gift_aid;
  • adjusted_net_income, which feeds the personal allowance taper and HICBC.
• GiveCalc:
  • household_for_year;
  • /api/savings;
  • useBunching;
  • householdIncome;
  • ukApiRequest;
  • syncUrl / isShareable.
• Storage answer:
  • no code in api/ or givecalc/ writes files or databases, or logs request bodies;
  • the in-memory LRU caches are keyed on the household;
  • modal app logs givecalc lines carry only method, path, status and timing;
  • the frontend, ui-kit and wizard use no analytics, cookies or local storage.

Checks

• Vitest: 138 passed (the two FAQ files, 25 tests, rerun at 3483ab3).
• Full pytest suite: passed (exit 0), including test_faq_numbers.py (12 passed at 3483ab3).
• next build: passes.
• ESLint: 0 errors. The one warning is the existing <img> in Header.tsx.
• black and isort: clean.
• Browser, 1440 px: the FAQ sits under the results, the header link jumps to it, and nothing overflows.
• Browser, 375 px: the header link wraps below the logo, there is no horizontal scroll, and the answers wrap cleanly. This check caught two missing spaces in the built page that jsdom kept; both are fixed.
• Review: GPT-6.1 Sol requested changes (seven findings: state itemizing, the donor-advised fund placement, local tax scope, the 2/37 base, Gift Aid band limits and Scotland, the in-memory households, losses). All were addressed in 974ba98. Sol's delta review of 974ba98 returned APPROVE and suggested two optional test tightenings, both taken in 3483ab3: the Scottish rule test now asks policyengine-uk which band it extends first, and the California $8,000 check bounds the extra saving by California's top rate. The reviews are in ~/reviews/givecalc-2026-10-16/review-pr92/.

Follow-up

The older "How GiveCalc calculates" explainer in Results.tsx overlaps this section, and one of its lines is incomplete (state itemizing). It should be reconciled or removed separately.

axiom: n/a: UI copy only

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
givecalc	Ready	Preview	Oct 24, 2026 11:29am UTC

[MaxGhenis]

Merge audit: head 3483ab3, base 540ce9a. gh pr checks exit 0 (test 3.13, frontend build/lint/tests, Vercel), mergeable CLEAN, no CHANGES_REQUESTED. Independent review: GPT-6.1 Sol (subfleet run --task review --tier hard) requested seven changes at 13a91de/228193c, all fixed in 974ba98; Sol's delta review of 974ba98 returned APPROVE with two optional test tightenings, both taken in 3483ab3 (tests only). Reviews: ~/reviews/givecalc-2026-10-16/review-pr92/sol-review.md, sol-delta-review.md.