From ccd74633d27d5ab3a84dcf27ce45ccc5a6256504 Mon Sep 17 00:00:00 2001
From: Jen Breese-Kauth <jbreese@stanford.edu>
Date: Wed, 15 Jul 2026 11:18:46 -0700
Subject: [PATCH 01/10] TVM: fix to edge case

---
 .../time-value-money-calculator/page.tsx            | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/app/interactives/time-value-money-calculator/page.tsx b/app/interactives/time-value-money-calculator/page.tsx
index 46dfc13..1f9a459 100644
--- a/app/interactives/time-value-money-calculator/page.tsx
+++ b/app/interactives/time-value-money-calculator/page.tsx
@@ -53,6 +53,12 @@ const CONSTRAINTS = {
 // Ceiling above which a solved output is "Too large to display"
 const OUTPUT_OVERFLOW_CEILING = 1e15
 
+// Cash-flow signs are valid (M1 handles all-same-sign) but no economically
+// meaningful rate exists: the only mathematical root sits below the -100%
+// display floor, so the scan finds no bracket in the sensible range.
+const MSG_NO_MEANINGFUL_RATE =
+  "No interest rate could be calculated for these inputs. Try adjusting your values, or double-check the cash flow amounts and timing."
+
 interface FieldError {
   field: string
   message: string
@@ -399,8 +405,9 @@ export default function Page() {
           }
 
           if (bracketLo === null)
-            // M3
-            throw new Error("No interest rate produces these values. Check that your cash flows include both a negative and a positive amount.")
+            // Signs are already known to be mixed, so this is the
+            // "root exists only at a nonsensical rate" case, not a sign problem.
+            throw new Error(MSG_NO_MEANINGFUL_RATE)
 
           let solvedG = (bracketLo + bracketHi) / 2
           if (bracketLo !== bracketHi) {
@@ -459,7 +466,7 @@ export default function Page() {
       // The high side is intentionally uncapped. -100% exactly is allowed: it
       // is the legitimate total-loss result when fv = 0.
       if (solveFor === "RATE" && calculatedValue < -100)
-        throw new Error("No interest rate produces these values. Check that your cash flows include both a negative and a positive amount.")
+        throw new Error(MSG_NO_MEANINGFUL_RATE)
 
       // M5: output overflow ceiling — never render scientific notation
       if (

From 50c72b0c34d5889a1f060364cc9e46b293adc72c Mon Sep 17 00:00:00 2001
From: Jen Breese-Kauth <jbreese@stanford.edu>
Date: Wed, 15 Jul 2026 11:28:12 -0700
Subject: [PATCH 02/10] fixup

---
 CHANGELOG.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index defbd45..aad380e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,10 @@ Releases are identified by deploy date.
 
 ## [Unreleased]
 
+### [2026-07-15]
+
+- TVM interest-rate tab now reports that no meaningful rate could be calculated, instead of a misleading cash-flow-signs error, when the only root falls below the -100% floor (#___).
+
 ## [2026-07-10]
 
 First tracked production release. Promotes the accumulated calculator work from

From 8de9bcd7277132158f14ae9d756b97f27d2ee454 Mon Sep 17 00:00:00 2001
From: Jen Breese-Kauth <jbreese@stanford.edu>
Date: Thu, 16 Jul 2026 14:53:53 -0700
Subject: [PATCH 03/10] Add Run, Observe, Propose, Verify debugging skill

A four-phase change/debug loop tailored to this repo's manual-verification
workflow (no test suite; per-file calculator math).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../run-observe-propose-verify/SKILL.md       | 98 +++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 .claude/skills/run-observe-propose-verify/SKILL.md

diff --git a/.claude/skills/run-observe-propose-verify/SKILL.md b/.claude/skills/run-observe-propose-verify/SKILL.md
new file mode 100644
index 0000000..bb5487f
--- /dev/null
+++ b/.claude/skills/run-observe-propose-verify/SKILL.md
@@ -0,0 +1,98 @@
+---
+name: run-observe-propose-verify
+description: >-
+  A disciplined loop for diagnosing bugs and validating changes: Run the code,
+  Observe the actual behavior, Propose a minimal fix rooted in evidence, then
+  Verify the fix by re-running and comparing against a known-good baseline. Use
+  when debugging unexpected behavior, changing financial math or validation
+  logic, or before calling any nontrivial change "done" — especially in this
+  repo, which has no automated test suite and relies on manual verification.
+---
+
+# Run, Observe, Propose, Verify (ROPV)
+
+A four-phase loop for changing code with confidence. The rule is simple: **never
+propose a fix from a theory alone, and never call a change done without
+re-observing it.** Evidence bookends every change.
+
+This repo has no test suite (see `CLAUDE.md`) and its financial math is a
+sensitive surface with a history of edge-case regressions. That makes the
+observe/verify halves non-optional here, not ceremony.
+
+## When to use
+
+- A calculator produces wrong or surprising numbers.
+- You're editing financial math, a solver, validation rules, or currency/input
+  handling.
+- You've made any nontrivial change and are about to say it works.
+- You're reviewing someone else's change and want to confirm the claimed effect.
+
+Skip it for pure copy/styling tweaks with no runtime behavior to observe.
+
+## The loop
+
+### 1. Run
+Get the code executing so you can see real behavior, not imagined behavior.
+
+- `yarn dev` and open the affected calculator in the browser, OR
+- `yarn build:local` to confirm it compiles, and `yarn lint`.
+- Reproduce the exact scenario in question: the specific inputs, frequency,
+  edge value (zero rate, very high rate, cross-compounding frequency, empty
+  field).
+
+Write down the inputs you used. A repro you can't restate is not a repro.
+
+### 2. Observe
+Record what actually happens, precisely — before forming any theory.
+
+- Capture the actual output (the number, the date, the error).
+- Capture what you *expected* and where that expectation comes from (a
+  hand-calculation, another calculator, a known-good commit).
+- Note the delta. "Bi-weekly total interest is ~8% high" is an observation;
+  "the divisor is wrong" is already a guess — keep them separate.
+- Localize: does it affect one frequency or all? One tab or both? That narrows
+  cause to a shared helper vs. per-file logic. In these calculators, each
+  `app/interactives/<name>/page.tsx` owns its own math — a bug in one usually
+  does **not** exist in the others; confirm per file.
+
+### 3. Propose
+Only now form a fix, and make it the smallest change that the observation
+justifies.
+
+- State the root cause in one sentence, tied to the observed delta.
+- Prefer a one-line/one-value fix over a rewrite. If the fix is large, your
+  diagnosis is probably incomplete — go back to Observe.
+- Predict, out loud, what the corrected output should be *before* you run it.
+- Check whether the same root cause appears in sibling calculators; fix each
+  only after confirming it's actually present there (don't assume).
+
+### 4. Verify
+Re-run and confirm the prediction. This closes the loop.
+
+- Re-run the exact repro from step 1. Confirm the new output matches the
+  predicted value, not just "looks different."
+- Test the boundaries around it: zero, very large, empty input, the adjacent
+  compounding frequencies, both tabs.
+- Confirm you didn't regress the cases that were already correct.
+- Re-run `yarn lint` (and `yarn build:local` if you touched more than one file).
+- Report faithfully: state the before/after numbers and the exact inputs. If a
+  case still fails or you skipped a check, say so.
+
+## Reporting template
+
+```
+Repro:     <exact inputs / scenario>
+Observed:  <actual output>  (expected <value> from <source>)
+Cause:     <one sentence, tied to the delta>
+Fix:       <file:line, minimal change>
+Verified:  <re-run output = predicted>; boundaries checked: <list>
+```
+
+## Anti-patterns
+
+- Proposing a fix before running the code ("this should be it" — verify it *is*).
+- Verifying only the one case you fixed and declaring victory.
+- A large refactor offered as a bug fix — a symptom of a skipped Observe phase.
+- Assuming a fix in one calculator applies to the `-v2` or sibling versions
+  without checking each file.
+- Calling it done on a green compile alone; compiling is not behaving.

From a6cfe455419648c8e6ee0bed5e8c68f1c044bed7 Mon Sep 17 00:00:00 2001
From: Jen Breese-Kauth <jbreese@stanford.edu>
Date: Thu, 16 Jul 2026 14:54:36 -0700
Subject: [PATCH 04/10] Add CLAUDE.md project guidance

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..2d2ad5e
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,53 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+Educational financial-decision-making prototype for early-career professionals, built with Stanford GSB's Initiative for Financial Decision Making (IFDM). It's a Next.js **static site** of interactive financial calculators, each designed to be embedded via `<iframe>` inside the Mighty Networks platform. Hosted on GitHub Pages.
+
+## Commands
+
+```bash
+nvm use              # match the Node version in .nvmrc before anything else
+yarn install         # this repo uses yarn (yarn@1.22.22), not npm
+yarn dev             # dev server with turbopack at http://localhost:3000
+yarn build:local     # plain next build, no static-export path juggling — use this to check a build compiles
+yarn lint            # next lint (eslint) — runs against app/ only
+```
+
+There is no test suite. Verification is manual: run `yarn dev` and exercise the calculator in the browser.
+
+### Deploying (branch-gated — do not run casually)
+
+Deploys publish to GitHub Pages via `gh-pages`. Each script refuses to run unless you're on the matching branch (`scripts/check-branch.js`):
+
+- `yarn deploy` → production, requires branch `1.x`, publishes to https://ifdm-learning.stanford.edu/
+- `yarn deploy:staging` → staging, requires branch `dev`, publishes to the `ifdm_learning_apps_staging` repo
+
+Flow: feature branch → PR into `dev` → `yarn deploy:staging` (QA) → PR `dev` into `1.x` → `yarn deploy` (prod). Full details in `docs/deployment.md`.
+
+## Architecture
+
+**Static export.** `next.config.ts` sets `output: 'export'`, so this is a fully static site — no server, no API routes, no runtime data fetching. Everything is client-side. `images.unoptimized: true` and `trailingSlash: true` are required for GitHub Pages.
+
+**`basePath` is environment-driven.** Production serves from a custom domain root (empty basePath); staging serves from a subpath and sets `NEXT_BASE_PATH=/ifdm_learning_apps_staging` in `build:staging`. If assets 404 in one environment but not the other, this is almost always the cause — never hardcode absolute asset paths.
+
+**One calculator = one route = one file.** Each calculator lives at `app/interactives/<name>/page.tsx` and is a single self-contained `"use client"` component. They do **not** share calculation logic — each file owns its own state (all inputs held as `string` in `useState`), its own financial math, its own validation/error rules, and constant tables (frequency options, constraints) defined at the top of the file. When fixing a bug in one calculator, do not assume the fix applies elsewhere; check each file. `app/interactives/time-value-money-calculator/page.tsx` is the richest example of the established pattern (typed constants, a `CONSTRAINTS` object, `FieldError[]` validation).
+
+Note the `-v2` variants (`mortgage-calculator-v2`, `present-value-calculator-v2`, `mortgage-refinancing-calculator-v2`) are the current versions; the un-suffixed ones are older and may be superseded — confirm which is linked/embedded before editing.
+
+**The home page auto-discovers routes.** `app/page.tsx` reads the `app/` directory at build time (`fs.readdirSync`) and lists every subdirectory containing a `page.*` file. Adding a calculator directory automatically adds it to the index — no manual registration.
+
+**Shared UI is shadcn/ui.** Reusable primitives live in `app/ui/components/` (button, card, input, select, slider, tabs, etc.), generated via shadcn (`components.json`, "new-york" style, lucide icons). Use `cn()` from `app/lib/utils.ts` (clsx + tailwind-merge) for class composition. Import via the `@/*` alias mapped to the repo root (e.g. `@/app/ui/components/card`).
+
+## Styling conventions
+
+- **Tailwind v4** with CSS-first theming. The brand palette (Stanford colors: `lagunita`, `berry`, `palo-verde`, `navy`, `error #8C1515`, etc.) is defined as CSS variables in `app/ui/globals.css` under `@theme inline`, plus a few legacy tokens in `tailwind.config.js`. Prefer the named tokens over raw hex/rgba.
+- **Dark mode** is class-based (`darkMode: 'class'`). `app/lib/theme-toggle.tsx` toggles the `dark`/`light` class on `<html>` and persists to `localStorage`; it returns a placeholder until mounted to avoid hydration mismatch. Any color you add needs a dark-mode counterpart.
+- Fonts (Open Sans, Poppins) come from `app/ui/fonts.ts` via `next/font/google`.
+
+## Gotchas
+
+- No-cache headers are set in `app/layout.tsx` metadata because embeds are served through iframes and stale caches were a recurring problem.
+- Financial math is the sensitive surface here — the changelog shows repeated fixes to interest-rate solvers, edge cases (zero rate, high rate, cross-compounding frequency), and currency-input handling. Treat validation and solver edits carefully and test boundary values.

From e652b40585a537561543cad48187d12e88e000b2 Mon Sep 17 00:00:00 2001
From: Jen Breese-Kauth <jbreese@stanford.edu>
Date: Thu, 16 Jul 2026 15:05:54 -0700
Subject: [PATCH 05/10] Refine ROPV skill: negative triggers, can't-repro
 branch, verify-fail loop-back

Fold in the strongest ideas from a peer's debug-loop skill:
- description now excludes feature/refactor/style-only changes
- Run phase handles the "cannot reproduce" case explicitly
- Propose requires a falsifiable hypothesis
- adds an explicit verify-fails -> re-Observe loop-back with a report gate

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../skills/run-observe-propose-verify/SKILL.md   | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/run-observe-propose-verify/SKILL.md b/.claude/skills/run-observe-propose-verify/SKILL.md
index bb5487f..8a55cc2 100644
--- a/.claude/skills/run-observe-propose-verify/SKILL.md
+++ b/.claude/skills/run-observe-propose-verify/SKILL.md
@@ -6,7 +6,9 @@ description: >-
   Verify the fix by re-running and comparing against a known-good baseline. Use
   when debugging unexpected behavior, changing financial math or validation
   logic, or before calling any nontrivial change "done" — especially in this
-  repo, which has no automated test suite and relies on manual verification.
+  repo, which has no automated test suite and relies on manual verification. Do
+  NOT use for feature requests, refactors, or style/copy changes with no
+  reported malfunction.
 ---
 
 # Run, Observe, Propose, Verify (ROPV)
@@ -42,6 +44,10 @@ Get the code executing so you can see real behavior, not imagined behavior.
 
 Write down the inputs you used. A repro you can't restate is not a repro.
 
+If you **cannot** reproduce the symptom, say so explicitly and ask the user for
+more detail (browser, console output, screenshot, exact inputs) rather than
+guessing. Do not propose a fix for a bug you haven't seen.
+
 ### 2. Observe
 Record what actually happens, precisely — before forming any theory.
 
@@ -59,7 +65,8 @@ Record what actually happens, precisely — before forming any theory.
 Only now form a fix, and make it the smallest change that the observation
 justifies.
 
-- State the root cause in one sentence, tied to the observed delta.
+- State one specific, falsifiable root-cause hypothesis, tied to the observed
+  delta — something a re-run can prove wrong, not a vague "probably rounding."
 - Prefer a one-line/one-value fix over a rewrite. If the fix is large, your
   diagnosis is probably incomplete — go back to Observe.
 - Predict, out loud, what the corrected output should be *before* you run it.
@@ -78,6 +85,11 @@ Re-run and confirm the prediction. This closes the loop.
 - Report faithfully: state the before/after numbers and the exact inputs. If a
   case still fails or you skipped a check, say so.
 
+### If verification fails
+Do not silently retry a new guess. Stop, report what Verify actually showed, and
+treat that output as **new evidence for another Observe pass**. Each iteration
+ends with a report to the user, not a silent loop.
+
 ## Reporting template
 
 ```

From c8c92f6d6db756a716c7552323184358f1386c12 Mon Sep 17 00:00:00 2001
From: Jen Breese-Kauth <jbreese@stanford.edu>
Date: Thu, 16 Jul 2026 15:36:26 -0700
Subject: [PATCH 06/10] Add rigorous-accountant skill

A mathematically rigorous accounting/finance persona for deriving, reviewing,
and auditing the calculators' financial math: derive from first principles,
cross-check by an independent method (amortization schedule), and probe
boundary cases (zero rate, payment <= interest, high rate, bad input).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .claude/skills/rigorous-accountant/SKILL.md | 98 +++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 .claude/skills/rigorous-accountant/SKILL.md

diff --git a/.claude/skills/rigorous-accountant/SKILL.md b/.claude/skills/rigorous-accountant/SKILL.md
new file mode 100644
index 0000000..cf92f2a
--- /dev/null
+++ b/.claude/skills/rigorous-accountant/SKILL.md
@@ -0,0 +1,98 @@
+---
+name: rigorous-accountant
+description: >-
+  Adopt the mindset of an exceptionally rigorous mathematician who specializes
+  in accounting and finance: derive every financial formula from first
+  principles, cross-check results by an independent method, and reason
+  carefully about compounding, amortization, day-count/period conventions,
+  rounding, and sign conventions. Use when writing, reviewing, auditing, or
+  debugging the financial math in this repo's calculators (interest solvers,
+  amortization, present/future value, mortgages, debt payoff, currency
+  handling) or when the correctness of a number is in question. Do NOT use for
+  layout, styling, copy, or non-numerical UI work.
+---
+
+# The rigorous accountant
+
+You are an exceptionally bright mathematician whose specialty is accounting and
+quantitative finance. You treat every reported number as a claim that must be
+provable. You are calm, precise, and allergic to hand-waving: you would rather
+say "I need to check that" than assert a formula from memory.
+
+This persona exists because the financial math in this repo is its most
+sensitive surface — the changelog shows repeated fixes to interest-rate
+solvers and edge cases (zero rate, high rate, cross-compounding frequency,
+currency input). A wrong formula here silently misleads a real learner about
+their money. Rigor is the job, not a flourish.
+
+## Operating principles
+
+1. **Derive, don't recall.** Write the governing equation from first principles
+   before trusting any closed form. For a level-payment loan, start from the
+   balance recurrence `B_{k+1} = B_k(1 + i) − P` and show how the payment or
+   period count falls out — don't just paste the annuity formula and hope the
+   algebra matches the code.
+
+2. **State conventions explicitly.** Before computing, pin down:
+   - **Periodic rate** `i = annualRate / periodsPerYear` — and confirm the code
+     divides by the *same* `periodsPerYear` it uses for the period count.
+   - **Compounding vs. payment frequency** — in these calculators they are
+     defined to be equal; verify that assumption still holds in the file.
+   - **Day-count / periods per year** — daily 365, weekly 52, bi-weekly 26,
+     monthly 12, quarterly 4, semi-annual 2, annual 1. A single wrong entry
+     here corrupts one frequency while leaving the others correct.
+   - **Sign convention** — cash out vs. cash in; which side principal, interest,
+     and payment sit on.
+   - **Rounding** — round only for display, never mid-calculation; know whether
+     a cent-level discrepancy is expected accumulation or a real bug.
+
+3. **Cross-check by a second method.** A closed-form result must agree with an
+   independent computation before you trust it. Preferred check: run the
+   amortization schedule period by period (`balance = balance*(1+i) − payment`)
+   and confirm it lands at ~0 at the stated payoff, and that the summed interest
+   matches the closed-form total. If the two disagree, the closed form or its
+   inputs are wrong — find out which; do not average them.
+
+4. **Interrogate the boundaries.** Every formula gets tested at its edges:
+   - **Zero rate** (`i = 0`): annuity formulas divide by zero or take `log(1)`;
+     confirm the code special-cases it (payoff time should be `principal /
+     payment`).
+   - **Payment ≤ periodic interest**: the debt never amortizes — the log
+     argument goes non-positive. Confirm this is caught, not returned as `NaN`.
+   - **Very high rate**, **very large principal**, **empty/`NaN` input**,
+     **payment that pays off in a single period**.
+
+5. **Localize, don't generalize.** Each `app/interactives/<name>/page.tsx` owns
+   its own math; a correct derivation for one calculator is not evidence about
+   another (including its `-v2` variant). Re-derive per file.
+
+6. **Show the work.** Every conclusion comes with the numbers: the inputs, the
+   intermediate periodic rate and period count, the closed-form result, and the
+   independent check that agrees with it. "It looks right" is not a finding.
+
+## Method
+
+1. Restate the quantity being computed and its exact inputs (with units and
+   frequency).
+2. Derive the governing equation from first principles; note every convention.
+3. Compute the closed-form result, showing intermediates.
+4. Independently verify — schedule iteration or an alternate formula — and
+   confirm agreement.
+5. Probe the boundary cases relevant to the change.
+6. Report: the result, the derivation, the cross-check, and any discrepancy
+   (with its magnitude and cause). If something is off, name the `file:line`.
+
+## Reference formulas (derive before using; listed only to anchor notation)
+
+Let `i` = periodic rate, `n` = number of periods, `PV` = principal, `P` =
+level payment.
+
+- Payment for a target term: `P = PV · i · (1+i)^n / ((1+i)^n − 1)`;
+  at `i = 0`, `P = PV / n`.
+- Periods to pay off a balance: `n = −ln(1 − PV·i / P) / ln(1 + i)`,
+  valid only when `P > PV·i`; at `i = 0`, `n = PV / P`.
+- Total interest: `total interest = P·n − PV`.
+- Balance recurrence (the ground truth for all of the above):
+  `B_{k+1} = B_k·(1 + i) − P`, `B_0 = PV`.
+
+Treat these as claims to be re-derived and cross-checked, not as authority.

From 99c79832acc3b8174aa31acb0244cd5fe3458685 Mon Sep 17 00:00:00 2001
From: Jen Breese-Kauth <jbreese@stanford.edu>
Date: Thu, 16 Jul 2026 15:53:54 -0700
Subject: [PATCH 07/10] Add new-calculator and calculator-qa skills

- new-calculator: scaffold a calculator following the self-contained TVM
  pattern (typed constants, CONSTRAINTS, FieldError[] validation, string inputs,
  dark-mode tokens, aria).
- calculator-qa: manual QA checklist (boundaries, currency input, validation,
  dark mode, a11y, basePath/iframe) since the repo has no test suite.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .claude/skills/calculator-qa/SKILL.md  | 96 ++++++++++++++++++++++++++
 .claude/skills/new-calculator/SKILL.md | 82 ++++++++++++++++++++++
 2 files changed, 178 insertions(+)
 create mode 100644 .claude/skills/calculator-qa/SKILL.md
 create mode 100644 .claude/skills/new-calculator/SKILL.md

diff --git a/.claude/skills/calculator-qa/SKILL.md b/.claude/skills/calculator-qa/SKILL.md
new file mode 100644
index 0000000..3c22951
--- /dev/null
+++ b/.claude/skills/calculator-qa/SKILL.md
@@ -0,0 +1,96 @@
+---
+name: calculator-qa
+description: >-
+  A manual QA checklist for verifying a calculator in this repo before calling a
+  change done — there is no automated test suite, so verification is by hand.
+  Covers boundary values, currency-input handling, error/validation states,
+  dark mode, keyboard/accessibility, and basePath/iframe behavior. Use after
+  editing or adding a calculator, before merging or deploying. Do NOT use as a
+  substitute for deriving the math (that's rigorous-accountant) or for
+  root-causing a specific bug (that's run-observe-propose-verify).
+---
+
+# Calculator QA checklist
+
+This repo has **no test suite** — verification is manual (`yarn dev`, exercise
+the calculator in the browser). This skill is the coverage list to run before
+calling a calculator change done. It complements, not replaces, the other
+skills: `rigorous-accountant` proves the math is correct; `calculator-qa`
+confirms the *whole calculator* behaves across inputs, states, and environments.
+
+Run against the specific `app/interactives/<name>/page.tsx` you changed. Each
+calculator owns its own math and validation, so results here do **not** transfer
+to sibling calculators or `-v2` variants — QA each file you touched.
+
+## Preconditions
+
+- `yarn lint` passes.
+- `yarn build:local` compiles.
+- `yarn dev` and open `/interactives/<name>/`.
+
+## 1. Correctness (happy path)
+
+- [ ] A known input set produces the expected output; confirm against an
+      independent calculation (invoke `rigorous-accountant` if unsure).
+- [ ] Every "solve for" / mode / tab produces sensible results.
+- [ ] Each compounding/payment frequency gives the right period count
+      (daily 365, weekly 52, bi-weekly 26, monthly 12, quarterly 4,
+      semi-annual 2, annual 1) — a single wrong entry corrupts one frequency
+      only, so check more than the default.
+
+## 2. Boundary & edge values
+
+- [ ] **Zero interest rate** — no divide-by-zero / `log(1)`; result is the
+      linear case (e.g. principal / payment).
+- [ ] **Very high rate** and **very large principal** — no overflow garbage;
+      "too large to display" handled if the file has that concept.
+- [ ] **Non-amortizing case** (payment ≤ periodic interest) — caught with a
+      clear message, not `NaN`/`Infinity` leaking to the UI.
+- [ ] **Single-period payoff** and other extremes at the constraint edges
+      (`CONSTRAINTS` min/max).
+- [ ] **Empty / partial / non-numeric input** (`""`, `-`, `.`, letters) — no
+      crash; sensible empty or error state.
+
+## 3. Currency & number input
+
+- [ ] Comma grouping displays correctly and is stripped before computing.
+- [ ] Decimal entry, leading `.`, and negative values (where allowed) behave on
+      change and on blur.
+- [ ] Output uses `Intl.NumberFormat` currency formatting; non-finite values are
+      guarded (show `-`, not `NaN`).
+
+## 4. Validation & error states
+
+- [ ] Out-of-range inputs surface the correct `FieldError` message on the right
+      field.
+- [ ] Calc-level errors (e.g. no meaningful rate) show the intended message.
+- [ ] Clearing a bad input clears its error.
+
+## 5. Dark mode & styling
+
+- [ ] Toggle dark/light — every color has a proper counterpart; no invisible or
+      low-contrast text.
+- [ ] Named Stanford tokens render correctly in both themes; no raw hardcoded
+      colors that break in dark mode.
+
+## 6. Accessibility
+
+- [ ] Every input has an associated `<Label htmlFor>`; there's an `sr-only`
+      `<h1>`.
+- [ ] Results region is `aria-live="polite"` and announces on change.
+- [ ] Full keyboard operation: tab order, selects reachable/operable, focus
+      visible.
+
+## 7. Embed / environment
+
+- [ ] No hardcoded absolute asset paths (basePath is environment-driven —
+      empty in prod, `/ifdm_learning_apps_staging` in staging).
+- [ ] Layout works at iframe-embed widths (narrow/responsive), since these are
+      embedded in Mighty Networks.
+
+## Report
+
+State exactly what you exercised — which inputs, frequencies, and states — and
+the pass/fail of each area. Call out anything you did **not** test (e.g. "didn't
+verify on a mobile viewport"). A green compile is not a pass; behavior in the
+browser is.
diff --git a/.claude/skills/new-calculator/SKILL.md b/.claude/skills/new-calculator/SKILL.md
new file mode 100644
index 0000000..8649c42
--- /dev/null
+++ b/.claude/skills/new-calculator/SKILL.md
@@ -0,0 +1,82 @@
+---
+name: new-calculator
+description: >-
+  Scaffold a new financial calculator in this repo following the established
+  self-contained pattern (typed constants, a CONSTRAINTS object, FieldError[]
+  validation, all inputs held as string in useState, currency formatting,
+  InfoPopover help, dark-mode tokens, aria). Use when the user asks to add,
+  create, or scaffold a new calculator/interactive/tool. Do NOT use for editing
+  an existing calculator's logic or for non-calculator pages.
+---
+
+# Scaffold a new calculator
+
+Every calculator in this repo is **one route = one file = one self-contained
+`"use client"` component** at `app/interactives/<name>/page.tsx`. Calculators do
+**not** share calculation logic — each owns its own state, math, validation, and
+constant tables. The home page (`app/page.tsx`) auto-discovers any directory
+with a `page.*` file, so no manual registration is needed.
+
+The canonical reference for the pattern is
+`app/interactives/time-value-money-calculator/page.tsx`. Read it before
+scaffolding and mirror its structure — do not invent a new shape.
+
+## Before writing
+
+1. Confirm the calculator name and its route slug (kebab-case, e.g.
+   `auto-loan-calculator`). Check no existing directory (or `-v2` variant)
+   already covers it.
+2. Confirm the inputs, the output(s), and the financial formula(s). If the math
+   is nontrivial, derive and cross-check it first — invoke `rigorous-accountant`.
+3. Decide the constraints (min/max per field) and the validation rules.
+
+## The pattern to follow
+
+Create `app/interactives/<slug>/page.tsx` as a single `"use client"` component.
+Mirror the TVM reference for each of these:
+
+- **Header:** `"use client"`, then imports from `@/app/ui/components/*`,
+  `ThemeToggle` from `@/app/lib/theme-toggle`, and `InfoPopover` from
+  `@/app/ui/components/popover`.
+- **Typed constants at the top of the file:** option tables (e.g.
+  `FREQUENCY_OPTIONS` with `value`/`label`/`perYear`), a `CONSTRAINTS` object
+  with per-field `{ min, max }`, and any fixed message strings. Type them
+  explicitly.
+- **State:** hold **every input as a `string`** in `useState` (not `number`) —
+  this is deliberate for currency/partial-entry handling. Keep result,
+  overflow, and `fieldErrors: FieldError[]` in state.
+- **Input handling:** reuse the reference's `formatWithCommas` /
+  `handleInputChange` / `handleInputBlur` approach for currency inputs; strip
+  commas before `Number(...)`.
+- **Validation:** produce a `FieldError[]` (`{ field, message }`) and surface a
+  calc-level error string; validate against `CONSTRAINTS` and the edge cases
+  the math requires (zero rate, non-amortizing payment, etc.).
+- **Math:** own, self-contained functions in this file. Never divide the annual
+  rate by one periods-per-year and count periods with another. Special-case
+  `rate = 0`. Never round mid-calculation — round for display only.
+- **Formatting:** `Intl.NumberFormat("en-US", { style: "currency", currency:
+  "USD", ... })`; guard non-finite values.
+- **UI:** shadcn primitives (`Card`, `Input`, `Label`, `Select`, `Tabs`),
+  `cn()` from `@/app/lib/utils` for class composition, `InfoPopover` for each
+  field's help text, a `ThemeToggle`.
+- **Accessibility:** `<h1 className="sr-only">`, `<Label htmlFor>` on every
+  input, `aria-live="polite"` on the results region, `aria-describedby` for
+  selects. See the debt-payoff and TVM files.
+
+## Styling
+
+- Tailwind v4 with the Stanford named tokens (`lagunita`, `berry`, `navy`,
+  `--color-teal`, etc. in `app/ui/globals.css`). Prefer named tokens over raw
+  hex/rgba.
+- **Every color needs a dark-mode counterpart** (dark mode is class-based).
+- Never hardcode absolute asset paths — `basePath` is environment-driven
+  (empty in prod, `/ifdm_learning_apps_staging` in staging). Hardcoding breaks
+  one environment.
+
+## After scaffolding
+
+1. `yarn lint` and `yarn build:local` to confirm it compiles.
+2. `yarn dev`, open `/interactives/<slug>/`, and exercise it — there is no test
+   suite, so run the `calculator-qa` checklist (boundary values, dark mode,
+   keyboard/aria) before calling it done.
+3. Confirm it appears on the auto-discovered home index.

From 31f47c5bbe862d18a8a1d1316a89d216a9709baf Mon Sep 17 00:00:00 2001
From: Jen Breese-Kauth <jbreese@stanford.edu>
Date: Thu, 16 Jul 2026 16:29:59 -0700
Subject: [PATCH 08/10] fixup

---
 .claude/skills/calculator-qa/SKILL.md  | 2 ++
 .claude/skills/new-calculator/SKILL.md | 2 ++
 CLAUDE.md                              | 3 +++
 3 files changed, 7 insertions(+)

diff --git a/.claude/skills/calculator-qa/SKILL.md b/.claude/skills/calculator-qa/SKILL.md
index 3c22951..dc8127e 100644
--- a/.claude/skills/calculator-qa/SKILL.md
+++ b/.claude/skills/calculator-qa/SKILL.md
@@ -65,6 +65,8 @@ to sibling calculators or `-v2` variants — QA each file you touched.
       field.
 - [ ] Calc-level errors (e.g. no meaningful rate) show the intended message.
 - [ ] Clearing a bad input clears its error.
+- [ ] Exact token values and rules for each check are in `docs/calculator-global-rules.md`
+(warning hexes `#9A6207` / `#C37C09`, `var(--color-inline-error)`, etc.).
 
 ## 5. Dark mode & styling
 
diff --git a/.claude/skills/new-calculator/SKILL.md b/.claude/skills/new-calculator/SKILL.md
index 8649c42..81876a3 100644
--- a/.claude/skills/new-calculator/SKILL.md
+++ b/.claude/skills/new-calculator/SKILL.md
@@ -29,6 +29,8 @@ scaffolding and mirror its structure — do not invent a new shape.
 2. Confirm the inputs, the output(s), and the financial formula(s). If the math
    is nontrivial, derive and cross-check it first — invoke `rigorous-accountant`.
 3. Decide the constraints (min/max per field) and the validation rules.
+4. Full field-level conventions (error/warning tokens, "Please enter" language,
+currency formatting, sign helper) live in `docs/calculator-global-rules.md`.
 
 ## The pattern to follow
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 2d2ad5e..b9b9e12 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -41,11 +41,14 @@ Note the `-v2` variants (`mortgage-calculator-v2`, `present-value-calculator-v2`
 
 **Shared UI is shadcn/ui.** Reusable primitives live in `app/ui/components/` (button, card, input, select, slider, tabs, etc.), generated via shadcn (`components.json`, "new-york" style, lucide icons). Use `cn()` from `app/lib/utils.ts` (clsx + tailwind-merge) for class composition. Import via the `@/*` alias mapped to the repo root (e.g. `@/app/ui/components/card`).
 
+See `docs/calculator-global-rules.md` for the full calculator conventions (input handling, error/warning states, formatting, math fallbacks).
+
 ## Styling conventions
 
 - **Tailwind v4** with CSS-first theming. The brand palette (Stanford colors: `lagunita`, `berry`, `palo-verde`, `navy`, `error #8C1515`, etc.) is defined as CSS variables in `app/ui/globals.css` under `@theme inline`, plus a few legacy tokens in `tailwind.config.js`. Prefer the named tokens over raw hex/rgba.
 - **Dark mode** is class-based (`darkMode: 'class'`). `app/lib/theme-toggle.tsx` toggles the `dark`/`light` class on `<html>` and persists to `localStorage`; it returns a placeholder until mounted to avoid hydration mismatch. Any color you add needs a dark-mode counterpart.
 - Fonts (Open Sans, Poppins) come from `app/ui/fonts.ts` via `next/font/google`.
+- Inline validation colors use `var(--color-inline-error)` and `var(--color-inline-warning)` (warning resolves to `#9A6207` light / `#C37C09` dark). See `docs/calculator-global-rules.md` sections 4-5.
 
 ## Gotchas
 

From 04659e59bf5a18b15aa847b71709c5d3094303f3 Mon Sep 17 00:00:00 2001
From: Jen Breese-Kauth <jbreese@stanford.edu>
Date: Thu, 16 Jul 2026 16:39:00 -0700
Subject: [PATCH 09/10] fixup

---
 CHANGELOG.md                    |   2 +-
 docs/calculator-global-rules.md | 378 ++++++++++++++++++++++++++++++++
 2 files changed, 379 insertions(+), 1 deletion(-)
 create mode 100644 docs/calculator-global-rules.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index aad380e..506cf45 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,7 +9,7 @@ Releases are identified by deploy date.
 
 ### [2026-07-15]
 
-- TVM interest-rate tab now reports that no meaningful rate could be calculated, instead of a misleading cash-flow-signs error, when the only root falls below the -100% floor (#___).
+- TVM interest-rate tab now reports that no meaningful rate could be calculated, instead of a misleading cash-flow-signs error, when the only root falls below the -100% floor (#159).
 
 ## [2026-07-10]
 
diff --git a/docs/calculator-global-rules.md b/docs/calculator-global-rules.md
new file mode 100644
index 0000000..87c50a0
--- /dev/null
+++ b/docs/calculator-global-rules.md
@@ -0,0 +1,378 @@
+# Global Rules: Financial Calculator Suite
+
+This document covers all policies and patterns that apply to every calculator in the suite. When working on a new calculator or adding error states to an existing one, these rules apply by default.
+
+The four Claude Code skills in `.claude/skills/` are the task-shaped counterparts to this reference: `new-calculator` scaffolds against these patterns, `calculator-qa` verifies them, `rigorous-accountant` owns the math rules (sections 9-11), and `run-observe-propose-verify` is the debugging loop. This file is the source of the specifics they defer to.
+
+---
+
+## 1. Input Handling: Setters Are Unconditional
+
+**The rule:** Always call the state setter with whatever the user typed. Error and warning logic runs independently afterward. Never gate the setter behind a validity check.
+
+**Why it matters:** When the setter is wrapped in a conditional, invalid values disappear from the field instead of staying visible. The user loses the context of what they typed, which is confusing.
+
+```tsx
+// WRONG -- field clears on invalid input
+onChange={(e) => {
+  const val = e.target.value;
+  if (val === "" || (Number(val) >= 0 && Number(val) <= maxValue)) {
+    setMyField(val);
+  } else {
+    setMyFieldError("Value must be between 0 and X.");
+    // setter never called -- field appears to clear
+  }
+}}
+
+// CORRECT -- invalid value stays visible
+onChange={(e) => {
+  const val = e.target.value;
+  setMyField(val); // always runs first
+
+  if (val !== "" && (Number(val) < 0 || Number(val) > maxValue)) {
+    setMyFieldError("Value must be between 0 and X.");
+  } else {
+    setMyFieldError("");
+  }
+}}
+```
+
+When auditing or writing a new calculator, check every `onChange` handler for a setter wrapped inside a conditional and pull it out to the top.
+
+---
+
+## 2. Input Cleanup (Numeric Fields)
+
+Strip leading zeros on numeric inputs so `007` becomes `7`, while still allowing `0.8` or `.8`:
+
+```ts
+const stripped = val.replace(/^0+(?=\d)/, "");
+```
+
+For period/count fields (not currency), cap decimal input to 2 places as the user types:
+
+```ts
+const cleaned = stripped.replace(/(\.\d{2})\d+/, "$1");
+```
+
+Auto-add a leading zero on blur if the user typed a bare decimal like `.8`:
+
+```tsx
+onBlur={(e) => {
+  if (e.target.value.startsWith(".")) {
+    setMyField("0" + e.target.value);
+  }
+}}
+```
+
+---
+
+## 3. Input Icons ($ and %)
+
+Every input that accepts a dollar amount displays a slightly gray `$` on the left side as a permanent fixture. It is always visible, not just on focus.
+
+Every input that accepts a percentage displays a `%` inside the input on the right side, also as a permanent fixture.
+
+In dark mode both icons must use a lighter color. The default dark gray is not readable against the dark background.
+
+These icons are part of the input's base layout, not conditional state. The mortgage calculator is the established reference for how the `$` placement should look.
+
+---
+
+## 4. Error State Styling
+
+CSS variable: `var(--color-inline-error)`
+
+Each field gets a paired error state variable, e.g. `interestRateError`. The field shows a 2px red border and red text below when an error is active.
+
+- Border: `border-[var(--color-inline-error)] border-2`
+- Text: `style={{ color: "var(--color-inline-error)" }}`
+
+Where multiple fields share the same input class, use extracted helpers:
+
+```tsx
+// Base classes shared by all inputs
+const baseInputClass = "border-1 w-full rounded-md shadow-sm py-2 px-3 ...";
+
+// Returns the error/warning border class
+function inputStateClass(error: string, warning: string): string {
+  if (error) return "border-[var(--color-inline-error)] border-2";
+  if (warning) return "border-[var(--color-inline-warning)] border-2";
+  return "";
+}
+```
+
+---
+
+## 5. Warning State Styling
+
+CSS variable: `var(--color-inline-warning)`
+
+The warning color token must resolve to a single color per theme, applied identically to both the border and the text. Using two different orange values for text and outline is a bug.
+
+- Light mode: `#9A6207`
+- Dark mode: `#C37C09`
+
+Warnings are advisory states for technically valid but unusual values (e.g. a 0% interest rate, or a rate above 50%). They do not block calculation.
+
+- Border: `border-[var(--color-inline-warning)] border-2`
+- Text: `style={{ color: "var(--color-inline-warning)" }}`
+
+**Error wins over warning.** The className ternary always checks error first:
+
+```tsx
+className={`${baseInputClass} ${
+  interestRateError
+    ? "border-[var(--color-inline-error)] border-2"
+    : interestRateWarning
+      ? "border-[var(--color-inline-warning)] border-2"
+      : ""
+}`}
+```
+
+Error and warning JSX blocks are independent siblings, not nested. Do not guard the warning block with `!errorState`. Both blocks live next to each other; the state logic keeps only one active at a time.
+
+```tsx
+{/* Independent siblings */}
+{interestRateError && (
+  <p style={{ color: "var(--color-inline-error)" }}>{interestRateError}</p>
+)}
+{interestRateWarning && (
+  <p style={{ color: "var(--color-inline-warning)" }}>{interestRateWarning}</p>
+)}
+```
+
+**Consistency rule:** Every field that has warning text must also have a matching amber border. If a field shows amber text but no amber outline, that is a bug.
+
+---
+
+## 6. Required Field Errors
+
+Required fields fire their error message on `onBlur` (after the user leaves the field while it is empty). A 150ms deferred pattern is used so the error does not flash if the user is tabbing normally.
+
+**Error message language:** All required field errors must start with "Please enter". Do not use a bare "Enter" without the "Please".
+
+```
+"Please enter an interest rate."      correct
+"Please enter an initial amount."     correct
+"Enter an initial amount."            wrong
+```
+
+Fields where an error appearing immediately on load would be jarring use a `touched` state. The error only appears after the user has interacted with the field at least once:
+
+```tsx
+const [yearsToRetirementTouched, setYearsToRetirementTouched] = useState(false);
+```
+
+---
+
+## 7. Result Suppression (anyFieldEmpty)
+
+When any required field is empty, the result panel shows `—` instead of computing with 0 for the blank fields.
+
+Each tab has its own boolean guard derived from its required fields. Optional fields (e.g. `finalAmount` on Present Value) are explicitly excluded from the check.
+
+```tsx
+const singleAnyFieldEmpty =
+  futureValue === "" || interestRate === "" || periods === "";
+
+const singleHasError =
+  singleAnyFieldEmpty || !!futureValueError || !!interestRateError || !!periodsError;
+```
+
+In the result display:
+
+```tsx
+<p>{singleHasError ? "—" : formatCurrency(result)}</p>
+```
+
+---
+
+## 8. Skip Detection
+
+Skip detection flags a required field as errored when the user jumps past it (interacts with a later field while an earlier one is still empty). It is implemented using a `FIELD_ORDER` array and a `flagSkippedFields` helper.
+
+This pattern is applied to the Compounding Frequency calculator and is available to port to other calculators. Not all calculators currently have it.
+
+```tsx
+const FIELD_ORDER = ["principal", "interestRate", "periods"] as const;
+
+function flagSkippedFields(
+  currentField: string,
+  values: Record<string, string>,
+  setErrors: Record<string, (msg: string) => void>
+) {
+  const currentIndex = FIELD_ORDER.indexOf(currentField as typeof FIELD_ORDER[number]);
+  FIELD_ORDER.slice(0, currentIndex).forEach((field) => {
+    if (values[field] === "") {
+      setErrors[field](`Please enter a ${field}.`);
+    }
+  });
+}
+```
+
+---
+
+## 9. Large Number Display
+
+Results use abbreviated formatting once values reach the millions range.
+
+- Under $1M: standard `Intl.NumberFormat` currency format, always 2 decimal places
+- $1M and up: abbreviated with M, B, or T suffix, 2 decimal places by default
+- Above `1e15` (past trillions): render as `"Too large to display"`, never scientific notation
+
+When two paired values (e.g. final balance and interest accrued) would render identically in abbreviated form, extend both to 3 decimal places, then 4 if still identical. Cap at 4. Both values in a pair always render at the same decimal count.
+
+```ts
+function formatCurrency(value: number, decimals: number = 2): string {
+  if (!isFinite(value)) return "-";
+  if (value >= 1e15) return "Too large to display";
+  if (value >= 1_000_000_000_000) return `$${(value / 1_000_000_000_000).toFixed(decimals)}T`;
+  if (value >= 1_000_000_000) return `$${(value / 1_000_000_000).toFixed(decimals)}B`;
+  if (value >= 1_000_000) return `$${(value / 1_000_000).toFixed(decimals)}M`;
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "USD",
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  }).format(value);
+}
+```
+
+When either value in a pair is `"Too large to display"`, show a hint line once, under the first result only:
+
+```
+Try a lower rate or fewer periods.
+```
+
+The hint is styled with `var(--color-inline-error)` and only appears when there is no validation error (i.e. the inputs are valid but the output is out of displayable range).
+
+In comparison tables, each row is its own pair. The decimal extension rule is applied row-by-row.
+
+---
+
+## 10. Zero-Rate Math Fallback
+
+When performing time-value-of-money calculations, the zero-rate fallback must use `=== 0`, not `<= 0`.
+
+Using `<= 0` incorrectly applies simple multiplication (principal x periods) for negative rates, when the present value annuity formula should still be used. Zero is the only case where the formula breaks down and simple multiplication is the correct fallback.
+
+```ts
+// WRONG
+if (rate <= 0) return principal * periods;
+
+// CORRECT
+if (rate === 0) return principal * periods;
+```
+
+---
+
+## 11. Dynamic Period Labels in Error Messages
+
+On calculators with a compounding frequency selector, range error messages use the appropriate period label for the selected frequency rather than the generic word "periods."
+
+```ts
+const periodPluralLabels: Record<CompoundingFrequency, string> = {
+  annually: "years",
+  "semi-annually": "semi-annual periods",
+  quarterly: "quarters",
+  monthly: "months",
+  biweekly: "bi-weekly periods",
+  weekly: "weeks",
+  daily: "days",
+};
+
+// Example output for weekly:
+// "Please enter a number of weeks between 0 and 5,200. (5,200 weeks = 100 years with weekly compounding)"
+```
+
+---
+
+## 12. Sign Helper Text
+
+On calculators where sign (positive/negative) matters for inputs, a helper line appears below the field once the user begins typing:
+
+```
+Money you pay out is negative; money you receive is positive.
+```
+
+Define this as a reusable constant:
+
+```ts
+const SIGN_HELPER = "Money you pay out is negative; money you receive is positive.";
+```
+
+Render it conditionally based on field value:
+
+```tsx
+{fieldValue !== "" && (
+  <p className="text-sm text-muted-foreground mt-1">{SIGN_HELPER}</p>
+)}
+```
+
+---
+
+## 13. Reset Button
+
+Every calculator has a Reset button. Use the shared `Button` component:
+
+```tsx
+<Button variant="lagunita" size="sm" onClick={handleReset}>
+  Reset
+</Button>
+```
+
+On reset, all of the following must clear:
+
+- Field values (back to empty strings or initial defaults)
+- Error state strings
+- Warning state strings
+- Touched state (if used)
+- Results (back to `—`)
+
+---
+
+## 14. Tooltips
+
+All tooltips use the shared `InfoPopover` component. Do not use a custom tooltip implementation.
+
+Tooltip titles are not displayed visually. The title must be present for screen readers but hidden using `sr-only`:
+
+```tsx
+<InfoPopover
+  title={<span className="sr-only">Compounding frequency</span>}
+  description="How often interest is applied to the balance."
+/>
+```
+
+The visible tooltip contains the description only.
+
+---
+
+## 15. Code Comments
+
+Every calculator file has function-level comments. The intent is to orient a new reader to what each block does, not to re-explain the logic line by line. Single-line comments inside components, block comments above standalone functions and helpers.
+
+---
+
+## Summary Table
+
+| Rule | Pattern / Key |
+|---|---|
+| Setter always called | `setMyField(val)` before any conditional |
+| $ icon | Permanent left fixture on all dollar inputs |
+| % icon | Permanent right fixture on all rate inputs |
+| Dark mode icons | Lighter color; dark gray is not readable |
+| Error border | `border-[var(--color-inline-error)] border-2` |
+| Warning border | `border-[var(--color-inline-warning)] border-2` |
+| Warning color (light) | `#9A6207` for both text and border |
+| Warning color (dark) | `#C37C09` for both text and border |
+| Error wins over warning | Error checked first in ternary |
+| Error + warning are siblings | Not nested, not mutually gated |
+| Required error language | Always starts with "Please enter" |
+| Empty field result | Show `—`, not computed value |
+| Too-large result | Show `"Too large to display"` at `>= 1e15` |
+| Abbreviated pair decimals | Extend 2 -> 3 -> 4 until values differ |
+| Zero-rate fallback | `=== 0`, not `<= 0` |
+| Reset clears | Values, errors, warnings, touched, results |
+| Tooltips | `InfoPopover` component; title is `sr-only`, description is visible |
\ No newline at end of file

From 2b6d28e1430393910c119dec283627600a088663 Mon Sep 17 00:00:00 2001
From: Jen Breese-Kauth <jbreese@stanford.edu>
Date: Thu, 16 Jul 2026 16:44:27 -0700
Subject: [PATCH 10/10] fixup

---
 .claude/skills/calculator-qa/SKILL.md | 105 ++++++++++++++++++--------
 1 file changed, 74 insertions(+), 31 deletions(-)

diff --git a/.claude/skills/calculator-qa/SKILL.md b/.claude/skills/calculator-qa/SKILL.md
index dc8127e..bf388e9 100644
--- a/.claude/skills/calculator-qa/SKILL.md
+++ b/.claude/skills/calculator-qa/SKILL.md
@@ -2,31 +2,39 @@
 name: calculator-qa
 description: >-
   A manual QA checklist for verifying a calculator in this repo before calling a
-  change done — there is no automated test suite, so verification is by hand.
-  Covers boundary values, currency-input handling, error/validation states,
-  dark mode, keyboard/accessibility, and basePath/iframe behavior. Use after
-  editing or adding a calculator, before merging or deploying. Do NOT use as a
-  substitute for deriving the math (that's rigorous-accountant) or for
-  root-causing a specific bug (that's run-observe-propose-verify).
+  change done. There is no automated test suite, so verification is by hand.
+  Covers correctness, boundary values, currency-input handling, the repo's
+  validation rules (invalid input stays visible, error vs. warning states,
+  required-field language, result suppression), the Reset contract, dark mode,
+  keyboard/accessibility, and basePath/iframe behavior. Use after editing or
+  adding a calculator, before merging or deploying. Do NOT use as a substitute
+  for deriving the math (that is rigorous-accountant) or for root-causing a
+  specific bug (that is run-observe-propose-verify).
 ---
 
 # Calculator QA checklist
 
-This repo has **no test suite** — verification is manual (`yarn dev`, exercise
-the calculator in the browser). This skill is the coverage list to run before
-calling a calculator change done. It complements, not replaces, the other
-skills: `rigorous-accountant` proves the math is correct; `calculator-qa`
+This repo has **no test suite**. Verification is manual: run `yarn dev` and
+exercise the calculator in the browser. This skill is the coverage list to run
+before calling a calculator change done. It complements, not replaces, the
+other skills: `rigorous-accountant` proves the math is correct; `calculator-qa`
 confirms the *whole calculator* behaves across inputs, states, and environments.
 
 Run against the specific `app/interactives/<name>/page.tsx` you changed. Each
 calculator owns its own math and validation, so results here do **not** transfer
-to sibling calculators or `-v2` variants — QA each file you touched.
+to sibling calculators or `-v2` variants. QA each file you touched.
+
+The behaviors below are the repo-wide rules. Section references like "(§1)"
+point to `docs/calculator-global-rules.md`, which has the exact tokens, hex
+values, and code patterns for each one. Check the behavior here; read the doc
+for the specifics.
 
 ## Preconditions
 
-- `yarn lint` passes.
-- `yarn build:local` compiles.
-- `yarn dev` and open `/interactives/<name>/`.
+- [ ] `yarn lint` passes (eslint, runs against `app/` only).
+- [ ] `yarn build:local` compiles. This is also what surfaces TypeScript errors,
+      since `yarn lint` is eslint only with no separate typecheck.
+- [ ] `yarn dev` and open `/interactives/<name>/`.
 
 ## 1. Correctness (happy path)
 
@@ -35,15 +43,17 @@ to sibling calculators or `-v2` variants — QA each file you touched.
 - [ ] Every "solve for" / mode / tab produces sensible results.
 - [ ] Each compounding/payment frequency gives the right period count
       (daily 365, weekly 52, bi-weekly 26, monthly 12, quarterly 4,
-      semi-annual 2, annual 1) — a single wrong entry corrupts one frequency
+      semi-annual 2, annual 1). A single wrong entry corrupts one frequency
       only, so check more than the default.
 
 ## 2. Boundary & edge values
 
-- [ ] **Zero interest rate** — no divide-by-zero / `log(1)`; result is the
-      linear case (e.g. principal / payment).
+- [ ] **Zero interest rate** — the code special-cases it with `=== 0`, not
+      `<= 0`; no divide-by-zero or `log(1)`; result is the linear case
+      (e.g. principal / payment). (§10)
 - [ ] **Very high rate** and **very large principal** — no overflow garbage;
-      "too large to display" handled if the file has that concept.
+      output above `1e15` renders as "Too large to display", never scientific
+      notation, if the file has that concept. (§9)
 - [ ] **Non-amortizing case** (payment ≤ periodic interest) — caught with a
       clear message, not `NaN`/`Infinity` leaking to the UI.
 - [ ] **Single-period payoff** and other extremes at the constraint edges
@@ -55,35 +65,68 @@ to sibling calculators or `-v2` variants — QA each file you touched.
 
 - [ ] Comma grouping displays correctly and is stripped before computing.
 - [ ] Decimal entry, leading `.`, and negative values (where allowed) behave on
-      change and on blur.
+      change and on blur; a bare leading `.` gets a `0` prepended on blur. (§2)
+- [ ] Leading zeros are stripped on numeric fields (`007` becomes `7`) while
+      `0.8` and `.8` still work. (§2)
+- [ ] Dollar inputs show a permanent `$` on the left; rate inputs show a
+      permanent `%` on the right; both stay readable in dark mode. (§3)
 - [ ] Output uses `Intl.NumberFormat` currency formatting; non-finite values are
-      guarded (show `-`, not `NaN`).
+      guarded (show `—`, not `NaN`). (§9)
 
-## 4. Validation & error states
+## 4. Validation: error & warning states
 
+- [ ] **Invalid input stays visible.** Typing an out-of-range or bad value keeps
+      the value in the field with an error beside it; the field never clears out
+      from under the user. This is the most important validation rule in the
+      repo. A field that blanks on invalid input is a bug. (§1)
 - [ ] Out-of-range inputs surface the correct `FieldError` message on the right
       field.
+- [ ] Required-field error messages start with "Please enter" (e.g. "Please
+      enter an interest rate."), not a bare "Enter". (§6)
 - [ ] Calc-level errors (e.g. no meaningful rate) show the intended message.
 - [ ] Clearing a bad input clears its error.
-- [ ] Exact token values and rules for each check are in `docs/calculator-global-rules.md`
-(warning hexes `#9A6207` / `#C37C09`, `var(--color-inline-error)`, etc.).
-
-## 5. Dark mode & styling
+- [ ] **Empty required field suppresses the result.** When a required field is
+      blank, the result panel shows `—` rather than computing with an implicit
+      zero. Optional fields are excluded from that guard. (§7)
+- [ ] **Warnings work as advisory states.** Technically valid but unusual values
+      (0% rate, rate above 50%) show an amber warning and still calculate; they
+      do not block the result. (§5)
+- [ ] **Error wins over warning.** When a field could show both, the error takes
+      precedence; the ternary checks error first. (§5)
+- [ ] **Warning border matches warning text.** Every field showing amber warning
+      text also has the matching amber border. Amber text with no amber outline
+      (or the reverse) is a bug. (§5)
+
+## 5. Reset
+
+- [ ] The calculator has a Reset button (`Button` with `variant="lagunita"`,
+      `size="sm"`). (§13)
+- [ ] Reset clears **all** of: field values, error strings, warning strings,
+      touched state, and results (back to `—`). Verify each category, not just
+      the visible inputs; a leftover error or stale result is the usual Reset
+      bug. (§13)
+
+## 6. Dark mode & styling
 
 - [ ] Toggle dark/light — every color has a proper counterpart; no invisible or
       low-contrast text.
 - [ ] Named Stanford tokens render correctly in both themes; no raw hardcoded
       colors that break in dark mode.
+- [ ] Inline error and warning colors resolve correctly in both themes
+      (`var(--color-inline-error)`, `var(--color-inline-warning)`). (§4, §5)
 
-## 6. Accessibility
+## 7. Accessibility
 
-- [ ] Every input has an associated `<Label htmlFor>`; there's an `sr-only`
+- [ ] Every input has an associated `<Label htmlFor>`; there is an `sr-only`
       `<h1>`.
 - [ ] Results region is `aria-live="polite"` and announces on change.
+- [ ] Help tooltips use the shared `InfoPopover`; the title is present for
+      screen readers via `sr-only` and the visible content is the description
+      only. (§14)
 - [ ] Full keyboard operation: tab order, selects reachable/operable, focus
       visible.
 
-## 7. Embed / environment
+## 8. Embed / environment
 
 - [ ] No hardcoded absolute asset paths (basePath is environment-driven —
       empty in prod, `/ifdm_learning_apps_staging` in staging).
@@ -92,7 +135,7 @@ to sibling calculators or `-v2` variants — QA each file you touched.
 
 ## Report
 
-State exactly what you exercised — which inputs, frequencies, and states — and
-the pass/fail of each area. Call out anything you did **not** test (e.g. "didn't
+State exactly what you exercised: which inputs, frequencies, and states, and the
+pass/fail of each area. Call out anything you did **not** test (e.g. "did not
 verify on a mobile viewport"). A green compile is not a pass; behavior in the
-browser is.
+browser is.
\ No newline at end of file