⚠️ Assumptions & judgment calls — check these

• source limitSavings are computer-modelled, not measured from utility bills.

  Every energy number comes from NRCan's HOT2000 model of the house, not real meter readings. Real usage varies with weather and behaviour — studies of modelled-vs-metered typically find models overpredict savings for deep retrofits.

  ✅ Verify it yourself ⏱️ 15 min

  1. Open the tool, enter your own postal code, and find a home similar to yours in the table.
  2. Compare its pre-retrofit total energy (kWh/yr) to your own annual gas + hydro bills converted to kWh (gas m³ × 10.36). Same ballpark = the modelling is sane; a big gap tells you how much to trust absolute numbers vs comparisons.

  docs/RETROFITS.md §"Data notes & caveats"; also stated on the page itself.
• source limitThe sample is self-selected — savings likely look better than average.

  Only homes that finished their retrofit AND booked a follow-up audit are counted — mostly rebate-program participants (e.g. Greener Homes required the follow-up). A random renovation would probably save less.

  ✅ Verify it yourself ⏱️ 15 min

  1. Compare the tool's median saving (~13% ON) against a published program evaluation — NRCan's Greener Homes reporting or Efficiency Canada's program reviews quote similar per-participant figures, which confirms the data is program participants, not typical renovators.

  docs/RETROFITS.md §"Data notes & caveats" → "The sample is self-selected".
• judgment callWhat counts as "the same home": area change ≤ 10%, same type/storeys/units.

  Pairs are dropped unless the before and after audits agree on these.

  Other options: stricter (≤ 5% area — fewer homes, cleaner pairs), looser (≤ 20% — more homes, more risk an addition or a different building sneaks in), or no area check at all. There's no "right" number; 10% balances sample size against contamination.

  ✅ Verify it yourself

  • ⏱️ 2 min: in any FSA view, expand a few homes and eyeball that pre/post floor area, type and storeys genuinely match.
  • ⏱️ deeper: edit the 10% constant in Python/ers_web_pipeline.py, re-run one province, and compare the median saving. If it barely moves (±1–2 points), the choice doesn't matter — that's the robustness test.

  docs/RETROFITS.md §"The data pipeline" step 1, rules 2–3.
• judgment callWhat counts as an "upgrade": >10% more insulation, >10% tighter air, ≥50% saved = "deep retrofit".

  These cutoffs decide the headline counts ("X% added insulation"). A 9% insulation increase counts as nothing.

  Other options: absolute thresholds (e.g. +0.5 RSI regardless of starting point), any-positive-change (noisy — audit measurement wobble would count), or the industry convention for "deep retrofit" (some use ≥40%, some ≥60%; 50% is the common midpoint and matches NRCan's usage).

  ✅ Verify it yourself

  • ⏱️ 2 min: expand a home flagged "roof insulation upgraded" in the FSA table and check its pre/post RSI values — is the flag intuitive?
  • ⏱️ 15 min: compare the "deep retrofit" definition against NRCan / Pembina publications ("deep retrofit" ≈ 50%+ energy reduction is the standard usage).

  docs/RETROFITS.md §"How each measure is flagged" (full table of rules).
• standard factorAll fuels converted to kWh with published factors (gas 10.36 kWh/m³, oil 10.2 kWh/L, wood 4,167 kWh/t…).

  Standard higher-heating-value energy contents.

  ✅ Verify it yourself ⏱️ 15 min

  1. Cross-check against the published conversion-factor tables (natural gas ≈ 37.30 MJ/m³ ÷ 3.6 = 10.36 kWh/m³ ✓; light fuel oil ≈ 38.80 MJ/L ÷ 3.6 ≈ 10.78 ✓ — StatCan RESD 57-003-X, the same value ECCC's National Inventory Report uses). Any energy-content reference will do.

  docs/RETROFITS.md §"Unit conversions" table.
• source limit"Solar added" may slightly overcount.

  Before-audits rarely record existing panels, so panels present at the after-audit all look "added".

  ✅ Verify it yourself ⏱️ 2 min

  1. In an FSA view, look at homes with solar: the pre-audit PV column is almost always 0 even in areas where some homes certainly had panels before — that's the tell.

  docs/RETROFITS.md §"Data notes & caveats" → "Solar pre vs post".
• judgment callExtreme outliers are clipped from charts (energy intensity > 500 kWh/m², emissions > 30 t/yr, heat loss > 150 kW).

  Purely for chart readability — the homes still exist in the data and in the medians.

  Other options: log-scale axes (keeps everything visible but harder to read), percentile-based clipping (99th), or an explicit "+N above range" bar.

  ✅ Verify it yourself ⏱️ 2 min

  1. Check that a clipped chart's total count still matches the header's "matched homes" count — clipping only hides bars, it doesn't drop homes from the stats.

  docs/RETROFITS.md §"Data notes & caveats" → "Outliers clipped".
• judgment callEmissions default to a calculated basis, not the audit's own reported figure.

  The audit's ERSGHG field is only filled for 50.5% of matched homes (Quebec ~78%, Saskatchewan ~9%), so building every emissions chart on it would have quietly halved the sample. The page now offers 4 bases and defaults to "corrected, at year of audit" — each home's emissions recomputed from its own recorded fuel use, at factors calibrated against the ERS data for that audit year.

  Other options: show only the reported figure (honest but half the data, and biased by which provinces report it); use ECCC's official current factors flat across all years (comparable across eras, but overstates Ontario's historic gas and understates Alberta/Newfoundland electricity by 18–49%); or scale the reported subset up to the full population (assumes the reporting homes are representative, which is exactly what isn't known).

  ✅ Verify it yourself ⏱️ 3 min

  1. Switch the "GHG basis" dropdown to "as reported" and watch the home count under the chart drop — that gap is the coverage problem this exists to solve.
  2. The calibrated basis was validated against the reported one where both exist: national aggregate within −0.66%, every large-sample province within ~±2% except Quebec (−5.3% on a small base).

  docs/RETROFITS.md §"GHG scenarios"; retrofits.html Methodology J; open question in docs/ENERGUIDE_QUESTIONS.md §5.4.

⚠️ What had to be assumed

This is the least settled thing on the site. Every item below is a reason the numbers are directional, not quotable.

• source limitThe cost data is American, unconverted.

  REMDB is a US database in 2023 USD. No currency conversion and no Canadian-labour adjustment has been applied anywhere — the figures are used as-is. Canadian installed costs differ by trade, region and season in ways a flat multiplier would not capture honestly, so none was invented.

  Other options: apply a headline FX rate (cheap, but implies a precision the underlying regression doesn't have); commission or source Canadian per-measure costs (the right answer, no public dataset found); or show ranges only, no point estimates.

  ✅ Verify it yourself ⏱️ 5 min

  1. Compare a mid-band heat-pump figure on the page against any Canadian contractor quote you have. Expect the page to read low — that gap is roughly the size of what's missing.

  docs/RETROFIT_COSTS.md; retrofits.html Methodology H.
• judgment callHouse shape is assumed, because ERS records no envelope areas.

  Insulation is priced per square metre, but the public ERS extract carries no wall or roof area anywhere. Areas are derived from the recorded footprint under an assumed 2:3 rectangle — a stated judgement call, not a sourced distribution of Canadian house shapes.

  Other options: a square footprint (simpler, slightly lower wall area); source a real footprint-aspect distribution from assessment or building-permit data (the intended fix, on the roadmap); or decline to price envelope measures at all.

  ✅ Verify it yourself ⏱️ 10 min

  1. Measure your own house's footprint and compare its true wall area against a 2:3 rectangle of the same floor area. The error is usually small; on a long narrow or L-shaped house it is not.

  docs/RETROFIT_COSTS.md §"Area proxies".
• source limitCoverage is partial, in three separate ways.

  Eight measures are priced (roof/wall/foundation insulation, air sealing, windows, heat pump, solar PV, HRV/ERV). Furnaces, boilers, floor insulation and doors are not priced at all. Apartments, duplexes and triplexes are excluded entirely — 31,389 of the 1,451,433 matched pairs — because REMDB's regressions assume single-dwelling geometry. Of the 1,420,044 that remain, 13% end up with no priced measure. Yukon has no ERS records at all.

  ✅ Verify it yourself ⏱️ 2 min

  1. In a postal-area view, compare the "homes with a cost estimate" count against the matched-home count. The difference is this gap, not a rendering bug.

  docs/RETROFIT_COSTS.md §"Measures explicitly NOT priced"; retrofits.html Methodology H.
• source limitThe payback denominator rests on utility rates we don't fully trust.

  Payback = cost ÷ annual dollars saved, so it inherits every weakness of the rate table. The electricity source was replaced in July 2026 after the previous one was caught quoting a Saskatchewan rate ~67% below SaskPower's own schedule while flagged "high confidence"; the replacement has been cross-checked only for Saskatchewan. Natural gas rates are frozen at a 2024-10-01 effective date across every province, ~21 months stale, with no verified replacement found. Oil, propane and wood are single national screening constants. Every affected home carries a machine-readable flag.

  ✅ Verify it yourself ⏱️ 10 min

  1. Look up your own utility's current residential rate and compare it to what the page uses for your province. Where they diverge, the payback figure moves proportionally.

  docs/RETROFIT_COSTS.md §"Utility rates"; retrofits.html Methodology F and H.
• judgment callThe HRV/ERV price is a class average, not a per-home fit.

  REMDB fits ventilation cost on recovery efficiency and airflow. Neither field survives the main pipeline, so every HRV is priced at fixed midpoint metrics (0.70 SRE, 150 CFM) and tagged flat_placeholder_metrics in the data rather than presented as a per-home number.

  retrofits.html Methodology H.

⚠️ Assumptions & judgment calls — check these

• judgment callZero-measure pairs are excluded from every "what worked" statistic, reported only as a count.

  118,282 pairs (8.6%) logged no tracked upgrade between audits — re-audits, not retrofits. Including them would dilute every measure-effectiveness number with noise.

  Other options: include them as a "0 measures" bucket in the bundle table (the previous approach in retrofits.html's own stats — muddies the "what worked" question this page asks); or try to reclassify some as real (untracked) retrofits (no reliable signal to do so).

  ✅ Verify it yourself ⏱️ 2 min

  1. On the page, the "what worked" section states its denominator (1,326,144) explicitly — check it's smaller than the 1,451,433 hero number, and the gap (125,289) matches the zero-measure count called out in the methodology accordion.

  Python/insights_notes.md §1; docs/archive/ROADMAP_COMPLETED.md item 13 "Honesty rails".
• judgment callThe missed-opportunity ranking is a reader-adjustable weighted composite — the reader can re-weight all 5 factors live and the table re-sorts client-side from stored per-FSA percentiles.

  Default weights: pre-EUI High, pre-GHG Medium, pre-1980 share Low, low participation Medium, low income Off (income is emitted but not weighted by default — see next assumption).

  Other options: a fixed, non-adjustable formula (simpler, but hides the judgment call instead of exposing it); a single "priority score" with no factor breakdown.

  ✅ Verify it yourself ⏱️ 2 min

  1. Open the missed-opportunity section and change a factor's priority slider — the ranking should visibly re-sort without a page reload (nothing is recomputed server-side, it's arithmetic over the stored percentiles).

  Python/build_insights.py "opportunity.json" section (OPP_WEIGHTS + comment); the page's priority controls.
• source limitIncome correlations are ecological (FSA-level), not household-level.

  "This FSA's median income is $X" describes the postal area, not the specific households that got audited. "Rich FSA" ≠ "rich participant" — a common mixing-of-levels trap the page states on-page.

  ✅ Verify it yourself ⏱️ 15 min

  1. Cross-check the national dwelling-weighted median income the page implies (~$82,000) against StatCan's 2020 published Canada median (~$84,000) — close but not identical, since this is a dwelling-weighted FSA aggregate, not a direct household survey figure.

  Python/insights_notes.md intro cross-checks; equity section methodology note on-page.
• source limitParticipation rate mixes ~20 years of cumulative audits over a single 2021 census dwelling snapshot — it can exceed 100%.

  A FSA where more homes have EVER been audited (2004–2026) than existed as dwellings in the 2021 census will show >100% participation. Not a bug; stated on-page wherever the metric appears.

  ✅ Verify it yourself ⏱️ 2 min

  1. Sort the participation leaderboard and check whether any FSA sits above 100% — if so, confirm the page's own caveat text next to that metric explains why.

  docs/archive/ROADMAP_COMPLETED.md item 13 "Honesty rails".
• judgment call"Screened against the DOE Challenge specifications" — never "meets" or "certified for" the Challenge.

  The screen checks published AHRI/ENERGY STAR certificate ratings against Table II-3 of the US DOE Cold Climate Heat Pump Challenge specifications. The Challenge itself is a verification programme with its own H11/H1N lab test protocol we do not hold, so a unit clearing every checkable criterion has rating-consistent performance and nothing more — the output column is named screen_pass, deliberately not "meets" or "certified". Only 4 of 8 Table II-3 criteria are checkable from the ratings we hold; the other 4 (turndown ratio, compressor cut-out/cut-in, electric-heat staging, ENERGY STAR CACHP sections) are shown as explicitly not checkable rather than silently dropped. Of 15,148 models / 439,975 ERS appearances, 4 certificate rows (3 distinct models, 8 appearances, 0.00%) clear every checkable criterion — three of the four sit exactly on the COP threshold, which is expected since Challenge-qualifying products only reached market in 2024–25 and this is a historical audit record.

  Other options: say a passing unit "qualifies for" or "meets" the Challenge (overclaims a lab verification test we never ran); silently drop the 4 uncheckable criteria instead of showing them (hides how much of the spec we can't actually check).

  ✅ Verify it yourself ⏱️ 3 min

  1. Search the "Cold-climate equipment" section and its methodology text for the word "meets" or "certified" next to "Challenge" — it should not appear; the wording is always "screened against the specifications".
  2. Check the qualifying-models table: it should show 4 rows but call out 3 distinct models, since GREE's GUD60W2/NHE-D(U) is AHRI-certified under two reference numbers.

  HeatPump/pipeline/screen_cchp.py docstring; HeatPump/METHODOLOGY.md "US DOE Cold Climate Heat Pump Challenge screen"; docs/archive/ROADMAP_COMPLETED.md item 14.

⚠️ Assumptions & data quirks — check these

• source limitPlan-only homes (no matching as-built record) are excluded entirely.

  Homes still under construction, or where the as-built evaluation was never filed, don't appear anywhere in the tool — there's no "as-built" number to show them with.

  ✅ Verify it yourself ⏱️ 2 min

  1. Compare the total P (plan) record count in a raw ERS CSV for a recent year against newhomes_json's row count for that year — plan-only homes explain the gap.

  docs/NEWHOMES.md "One row per finished, tested new home".
• source limitTier / ACH / ERS-rating availability varies by audit year.

  These fields weren't consistently collected across the full history; the page states year coverage per metric rather than implying full history everywhere.

  ✅ Verify it yourself ⏱️ 2 min

  1. Filter the page to an early audit year and check whether Tier/ACH show real values or an explicit "not collected this year" state.

  docs/NEWHOMES.md "Notes".
• source limitShares every caveat the Retrofit Explorer has about modelled (not metered) energy and self-selection.

  Same HOT2000-modelled energy numbers, same "only audited homes appear" sampling logic — see the Retrofit Explorer section above for the full detail rather than repeating it here.

  docs/RETROFITS.md §"Data notes & caveats" (shared conventions); docs/NEWHOMES.md.

⚠️ Assumptions & judgment calls — check these

• judgment callSuppressed/confidential cells become gaps, never zero.

  Government tables hide some provincial cells ("X"). Treating them as 0 would understate totals; they're shown as missing instead.

  Other options: impute them (Canada total minus the visible provinces) — more complete but invents numbers; or drop the whole series. Null-with-a-gap is the honest middle.

  ✅ Verify it yourself ⏱️ 15 min

  1. Open a provincial table on the OEE site (oee.nrcan.gc.ca → Comprehensive Energy Use Database → any provincial sector table) and find a suppressed cell.
  2. Check the same slice in ceud.html shows a gap, not a zero bar.

  Python/ceud_source_notes.md; the ETL's suppressed-cell handling.
• calibratedProvinces are checked to sum to the Canada total (within ~2%).

  A built-in sanity check on every ETL run.

  ✅ Verify it yourself

  • ⏱️ 2 min: pick one number on ceud.html (say, Ontario residential energy in 2023) and compare it to the same cell in NRCan's own Table 1 web page — they should match exactly.
  • ⏱️ deeper: run python Python/ceud_etl.py and read its printed validation report.

  Python/ceud_etl.py validation printout.
• source limitNo dollar figures anywhere — CEUD tracks energy and emissions, not cost.

  Cost context is a planned separate project (Energy Prices layer, below).

  docs/archive/CEUD_PLAN.md; the source database itself.

⚠️ Assumptions & data quirks — check these

• source limitProvincial "under construction" and "completions" STOP at December 2022.

  CMHC discontinued those provincial series entirely — verified against four different StatCan tables before concluding it's the source, not a bug. Metro areas still have current data. The page annotates the gap.

  ✅ Verify it yourself ⏱️ 15 min

  1. Open StatCan table 34-10-0151 (statcan.gc.ca → search the table number), pick any province, "Under construction".
  2. Confirm the values end at 2022-12 while "Starts" continues — exactly what the dashboard annotates.

  docs/archive/CONSTRUCTION_STATUS.md §"The provincial pipeline-gap saga"; meta.json's provincial_pipeline_gap.
• source limitPermit and investment history only starts 2017–2018.

  StatCan redesigned those programs; older data isn't comparable. Housing starts go back to 1990. Charts mix the two histories.

  ✅ Verify it yourself ⏱️ 2 min

  1. On the dashboard, note where the permits line begins vs the starts line — then confirm on StatCan table 34-10-0292 that its reference period genuinely begins in 2017.

  docs/archive/CONSTRUCTION_STATUS.md milestones; docs/CONSTRUCTION.md.
• judgment callStorage conventions: dollars in millions, unit counts as integers, seasonally-adjusted series preferred.

  Chosen to keep files small and charts smooth.

  Other options: raw unadjusted series everywhere (shows real seasonality but every chart becomes a sawtooth), or shipping both (double the file size). SA-preferred with unadjusted only as fallback is the standard dashboard convention.

  ✅ Verify it yourself ⏱️ 2 min

  1. Open construction_json/meta.json — every series' units and SA status are declared there. Spot-check one against the page.

  docs/archive/CONSTRUCTION_STATUS.md "Decisions log"; construction_json/meta.json.
• source limitThe Bank of Canada overnight-rate series only reaches back to 2009.

  Accepted as-is for the rate-cycle chart.

  ✅ Verify it yourself ⏱️ 2 min

  1. Visit the BoC Valet API page for series V39079 — its earliest observation is 2009.

  docs/archive/CONSTRUCTION_STATUS.md Phase 4a note.

⚠️ Assumptions & judgment calls — check these

• judgment callGround conductivity is GUESSED from the words in drillers' logs.

  A driller wrote "limestone" in 1985 → the map assigns 2.8 W/m·K. Full table: limestone 2.8 · dolostone 3.0 · sandstone 2.3 · shale 1.9 · granite 3.2 · gneiss 3.0 · clay 1.4 · silt 1.5 · sand 2.4 · gravel 2.0 · till 1.8 · fill 1.5 · basalt 2.0 · generic "rock" 2.5. Literature mid-range values, not measurements. Good enough to compare neighbourhoods; NOT good enough to size a borehole field.

  Other options: use the GSC's mapped bedrock geology instead of per-well logs (smoother, ignores real local variation — it's actually the planned fallback for well-sparse areas); carry min–max ranges per rock instead of one value (more honest, harder to map); or use only wells with actual thermal tests (there are essentially none public).

  ✅ Verify it yourself

  • ⏱️ 15 min: compare the bucket values against a published GSHP design table — the standard references are ASHRAE Applications ch. 35, IGSHPA design guides, or the widely-cited VDI 4640 ranges (e.g. limestone 2.5–4.0, granite 2.1–4.1, clay 0.9–2.3 W/m·K). Every bucket value should sit inside its published range.
  • ⏱️ 2 min: on the live map, click wells and check the lithology shown in the popup against the conductivity class it got — do a granite well and a clay well disagree the right way?

  Geothermal/README.md §3.1 "Lithology buckets"; §5 caveat 1.
• judgment callRock-name groupings were decided by Claude (marble counts as limestone, schist as gneiss, "quicksand" as sand, generic "ROCK" gets 2.5 W/m·K…).

  These mappings recovered ~4,800 wells that would otherwise read "unknown". Each is defensible geology (marble IS metamorphosed limestone), but they're calls someone should sanity-check.

  Other options: leave unmapped names as "unknown" (loses 4,800 wells but assumes nothing); or have a geologist review the mapping table (the strongest option, and cheap — it's ~15 lines).

  ✅ Verify it yourself

  • ⏱️ 15 min: open the bucket dictionary in Geothermal/scripts/combine_wells.py and check each folded rock against any geology reference: marble→limestone ✓ metamorphic equivalent; schist→gneiss ✓ both foliated metamorphics ~3 W/m·K; conglomerate→sandstone ✓ both clastic. The one to scrutinize: generic "ROCK" = 2.5 (a guess that it's average bedrock).
  • ⏱️ deeper: re-run the chain with "ROCK" excluded instead, and see if the map's class counts move materially.

  Geothermal/README.md §3.1; the bucket dict in combine_wells.py.
• judgment callInterpolation settings: 500 m grid, 12 nearest wells, distance-squared weighting, no cell further than 2 km from a well.

  Tighter settings = patchier map; looser = smoother but more made-up.

  Other options: kriging (statistically fancier, needs variogram fitting, harder to explain), natural-neighbour interpolation, a finer 250 m grid (4× the cells for little gain at this data density), or no interpolation at all (wells only — honest but unreadable at city scale).

  ✅ Verify it yourself

  • ⏱️ 2 min: on the map, turn on BOTH the grid and the wells layer and zoom somewhere you know — the grid colour should visibly track the nearby wells' colours.
  • ⏱️ deeper: in interpolate_conductivity.py change k from 12 to 6 (or power 2 → 1), re-run, and compare the printed class counts (medium/high/low cell totals). Small movement = robust choice.

  Geothermal/README.md §3.3; interpolate_conductivity.py.
• source limit"Unlikely" for open-loop mostly means "no data", not "proven bad".

  A well screens "viable" only if it has both a water level and a decent pump-test yield (≥ 15 L/min). Most "unlikely" wells are simply missing one of those records.

  ✅ Verify it yourself ⏱️ 2 min

  1. Click a handful of red "unlikely" wells on the map — the popups will mostly show blank yield or blank static level rather than bad values.

  Geothermal/README.md §3.1 "Open-loop screen" + §5 caveat 2.
• source limitWells are rural-biased and Ontario-only.

  Downtown has municipal water (few wells), so urban estimates lean on sparse, older records — watch the confidence flag. The Gatineau side is blank because the well database is Ontario's.

  ✅ Verify it yourself ⏱️ 2 min

  1. Toggle the wells layer and look at Centretown vs rural Osgoode — the density difference is obvious, and downtown grid cells should show the low-confidence flag in their popups.

  Geothermal/README.md §5 caveats 3–4.
• judgment callThe colour classes: low < 2.0 ≤ medium ≤ 2.8 < high (W/m·K).

  These cutoffs decide which cells look green vs red on the map.

  Other options: a continuous colour ramp (no arbitrary cutoffs, but harder to read "is my area good?"), or data-driven terciles (would move with the data rather than meaning something physical). 2.0 ≈ "below this, boreholes get long"; 2.8 ≈ "solid rock territory" — physically meaningful lines.

  ✅ Verify it yourself ⏱️ 15 min

  1. Check the cutoffs against the same GSHP design references as above: soils/clays cluster below 2.0, competent limestone/granite above 2.8 — the classes should separate "overburden" from "good bedrock".

  Geothermal/README.md §3.3.

⚠️ The 5 assumptions that matter most

• judgment callTHE BIG ONE: by default, heat-pump electricity is priced at the "marginal" grid rate (~500 g CO₂e/kWh in Ontario), not the much cleaner average (~97 g).

  The reasoning: plugging in a new load makes the gas plants run more — the nuclear/hydro was already spoken for. This single toggle flips the Ontario gas-vs-heat-pump answer from "−68% emissions" to "+11%".

  Other options: average EF (what most published studies use — flattering to heat pumps); a time-varying hourly marginal (more precise, but Ontario's margin is gas nearly every hour anyway, so it converges to ~flat 500); or a long-run marginal that credits future clean builds (speculative). The chosen flat-500-when-gas-runs is the deliberately pessimistic upper bound — honest for "what does MY new load cause today", harsh vs every headline you've read.

  ✅ Verify it yourself

  • ⏱️ 2 min: flip the Average/Marginal toggle in the page's Advanced mode and watch the verdict flip — then decide which question you're asking.
  • ⏱️ 15 min: open the saved TAF guideline (HeatPump/data/raw/TAF-Ontario-Emissions-Factors-2024.pdf) — it states marginal factors are the correct basis for fuel-switching decisions, average for inventories. The tool's default follows that guidance.
  • ⏱️ 15 min: sanity-check that gas really is Ontario's marginal fuel: IESO's public generator output pages show gas plants ramping with demand while nuclear/hydro run flat.

  HeatPump/METHODOLOGY.md §Phase 1 "Emission factor model"; PLAN.md methodology decision #1; the in-page explainer.
• calibratedOntario gas plants = a flat 500 g CO₂e/kWh, every hour, every year.

  Backed out from The Atmospheric Fund's published factors for 4 separate years (came out 474–526 each time). A constant was chosen over a per-year value for simplicity. Alberta uses coal 1050 / gas 540; Quebec's tiny thermal fleet 700 (NOT independently calibrated — it's 0.5% of QC generation, immaterial).

  Other options: a year-varying factor from the National Inventory Report directly (the documented TODO — the NIR PDF wasn't machine-readable this pass), or per-plant factors (overkill for a screening tool).

  ✅ Verify it yourself ⏱️ 15 min

  1. Open the TAF PDF's factor table (p.11): 2023 average = 67 g/kWh.
  2. Divide by the 2023 gas share of Ontario generation (13.3%, in METHODOLOGY.md's table): 67 ÷ 0.133 ≈ 502. That's the whole calibration — one division you can redo for any year.

  HeatPump/METHODOLOGY.md §"Gas emission factor: 500 g — calibration"; the TAF PDF is saved in the repo.
• judgment callHeat-pump performance curves rest on 4 certified test points per model, connected with straight lines.

  The plan was to digitize manufacturers' detailed engineering tables, but most are locked behind contractor logins (Lennox and Gree documents were downloaded and checked — no temperature tables). Fallback: the 4 AHRI-certified points every unit publishes. Real certified data, but the straight line across the 16 °C gap between −8 °C and +8 °C is an approximation.

  Other options: get contractor-portal access and digitize the full tables (the upgrade path — the pipeline is built to accept more points); fit a physical compressor model (more assumptions, not fewer); or use NREL/EnergyPlus generic curves (not model-specific).

  ✅ Verify it yourself

  • ⏱️ 2 min: look at the sanity plots in HeatPump/data/interim/hp_curve_tier1.png (etc.) — certified points overlaid on each curve.
  • ⏱️ 15 min: open the one public datasheet (HeatPump/data/raw/spec_sheets/mitsubishi/…202401.pdf, Performance table p.2) and compare its numbers to the same model's curve — they agree within ~3% except one 12% COP gap explained by a different indoor unit pairing.
  • ⏱️ deeper: run python HeatPump/pipeline/test_hp_curves.py — 7 automated checks including "curve passes through certified points within 3%".

  HeatPump/METHODOLOGY.md §Phase 3b "Data acquisition — what is public and what is not".
• calibratedHouses stop needing heat above ~8–12 °C outdoors — noticeably lower than the textbook 15–16 °C.

  This "balance point" wasn't assumed — it was solved so each archetype's simulated year reproduces the real audited median energy use. The textbook value would predict ~1.8× too much heating (Ottawa pre-1980: ~41,000 kWh vs the observed 22,990). Likely causes: thermostat setbacks and conservative audit heat-loss figures. Flagged openly as a finding.

  Other options: force 15–16 °C and scale down UA instead (same annual energy, different cold-weather shape — would change the backup-sizing story); or model setbacks explicitly (needs occupancy assumptions nobody has).

  ✅ Verify it yourself

  • ⏱️ 15 min: check against your own home — your gas bills likely drop to ~pilot-light levels by the time daily means hit 10–12 °C (May/June), not 15–16 °C. That's the same effect.
  • ⏱️ deeper: open HeatPump/data/interim/archetype_validation.csv — all 20 archetypes reproduce their audited energy, and the solved Tbalance values are listed per archetype.

  HeatPump/METHODOLOGY.md §Phase 4 "Finding: calibrated Tbalance (8–12 °C)…".
• judgment callA 7% efficiency penalty is applied between −7 °C and +4 °C for defrost cycles.

  Frost forms on outdoor coils in that band and the unit must periodically melt it. 7% is a literature default, not a per-model measurement.

  Other options: 0% (assume the certified ratings already include defrost — they don't for the max-capacity points used here, which was checked); or a per-model measured penalty (data doesn't exist publicly). Field studies report anywhere from ~3% to ~15%, so 7% is mid-range.

  ✅ Verify it yourself

  • ⏱️ 2 min: on the tier sanity plots (data/interim/), see the visible COP dip across the −7…+4 °C band.
  • ⏱️ 15 min: search "defrost penalty cold climate heat pump field study" — NRCan/CanmetENERGY field monitoring reports land in the 3–15% range.

  HeatPump/METHODOLOGY.md §Phase 3b "Curve construction" item 3.

⚠️ Known limitations — check these

• source limitAlberta is NOT live.

  There is no scriptable public source for recent Alberta data — the direct-CSV lead 404'd and AESO's API needs a registered key. Alberta updates only when the monthly files are manually dropped in (current through June 2026). Ontario IS fully live.

  ✅ Verify it yourself ⏱️ 15 min

  1. Try it: AESO's site offers the CSD downloads only interactively, and developer-apim.aeso.ca requires registration. If you want live AB, registering a free API key is the unblock — then the ETL can be extended.

  docs/archive/ROADMAP_COMPLETED.md item 6; Python/grid_etl.py docstring; the page's own AB banner.
• judgment callQuebec is a static context card, not a live series.

  Other options: plot HQ's manually-supplied export file as a live-looking series (misleading — it isn't refreshed), or drop QC entirely (loses useful context for the heat pump story).

  ✅ Verify it yourself ⏱️ 15 min

  1. Hydro-Québec's annual report: ~99.9% of generation is hydro/wind. A flat ~0 g/kWh card loses essentially nothing.

  docs/archive/ROADMAP_COMPLETED.md item 6; grid_json/grid_qc.json; the page's Quebec context card.
• calibratedThe refactor that shared code with the heat-pump pipeline was verified byte-identical.

  ✅ Verify it yourself ⏱️ deeper

  1. Re-run python HeatPump/pipeline/build_grid_ef.py and diff data/processed/grid_ef_on.json against git — no changes expected.

  docs/archive/ROADMAP_COMPLETED.md item 6 "ETL" section.