Model Card Worksheet

A model card is not documentation. It is the short-form artifact a reviewer needs when the full spec is too long to read on the way to a meeting.

Every calculator a team ships benefits from a one-page model card. The card is a compressed version of the full spec, structured so that a reviewer, a support agent, a partner, or a new team member can read it in five minutes and know what the calculator does, what it does not do, and where the substance lives. This worksheet is the template for authoring one. The fields below are the working set; add fields specific to the calculator only when they are necessary to understanding, not to comprehensiveness.

The twelve fields

The card is short by design. A card longer than one page is a document, not a card, and defeats the purpose. Fields marked required are load-bearing; fields marked optional exist for calculators where the field is genuinely informative.

• ✓Name (required). The short name of the calculator as users see it.
• ✓Purpose (required). One sentence naming the specific question the calculator answers.
• ✓Audience (required). The specific user the calculator is designed for.
• ✓Inputs (required). Every input with its label, type, and valid range.
• ✓Outputs (required). Every output with its label and unit.
• ✓Assumptions (required). The plain-language version of what the calculator does not consider.
• ✓Sentinels (required). Every non-numeric or extreme-value output condition, named.
• ✓Sources (required). Every constant the calculator uses, with the source name and period.
• ✓Spec URL (required). The link to the full specification.
• ✓Version (required). The current spec version pinned by the integration.
• ✓Related models (optional). Any adjacent models the caller commonly composes with this one.
• ✓Roadmap (optional). Named future changes that would affect this calculator’s behavior.

How to write each field

The name field takes the calculator’s user-facing name. Not the model identifier the API uses. If the calculator is called Refinance Break-Even in the UI, the card says Refinance Break-Even; the model identifier lives in the spec URL that the card also carries.

The purpose field takes exactly one sentence. Not two. Not a paragraph. If the calculator does more than one thing and the purpose cannot be compressed to a sentence, the calculator should probably be two calculators; the card is exposing a scope problem the spec should resolve upstream.

The audience field takes the specific user, not the general audience. A retirement projection is not for people who want to retire; it is for people at least a decade from retirement who have a taxable and a tax-advantaged account and are trying to size the tradeoff. The specificity is the point; a card whose audience field reads consumers is a card that has not been thought through.

The inputs and outputs fields take exhaustive lists. Every input the user supplies is listed with its label, type, and valid range. Every output the calculator returns is listed with its label and unit. Descriptions are not required; the card is a reference, not a tutorial.

The assumptions field takes a plain-language version of what the calculator does not consider. This is often the field a reviewer reads first, because it is where the calculator’s honesty is on display. A field that reads none is almost always wrong; every calculator has assumptions, and the discipline of naming them is what makes the card useful.

The sentinels field takes every non-numeric or extreme-value output condition, named. If the calculator can return an infinity value when savings are non-positive, the card names infinity. If the calculator can return an age of one hundred when a target is never reached, the card names one hundred. Sentinels are where UI bugs originate; naming them on the card prevents a downstream engineer from rendering them as raw strings to a user.

The sources field takes every constant the calculator uses. Values are not required; the point is to name what the calculator depends on, so a reviewer knows what moves and when. A card that lists no sources for a calculator that clearly depends on tax-year constants is a card whose author skipped the field.

Where the card lives

The card is published somewhere durable and linked from the calculator itself. Publishing formats vary: a dedicated cards directory on the docs site, a page adjacent to the spec, or an internal wiki visible to reviewers and partners. What matters is that the card is retrievable at click distance from the calculator, so a user or reviewer who wonders what this thing is has an answer that does not require reading the full spec first.

Card maintenance

The card updates when the spec updates. Any change to inputs, outputs, assumptions, sentinels, or sources triggers a card update as part of the release. Cards that drift from their specs are worse than no card at all, because they misinform confidently. A version identifier on the card matching the spec version it describes is the working discipline that keeps the two in sync.

“The full spec is the truth. The card is the summary a reviewer can read on the way to a meeting.”

A note on the template versus the practice

The twelve-field template is a starting point. A team may add one or two calculator-family-specific fields — for example, a jurisdiction field for calculators that ship in multiple regions, or a currency field for calculators that display monetary outputs. The additions are welcome. What is not welcome is fields that pad the card without adding information; a longer card is not a better card, and the discipline of keeping the card to one page is what makes it worth reading.

Who reads the card, and what they use it for

The reviewer reads the card to know what the calculator does and does not do. This is the most common use, and it is the reason the assumptions field is load-bearing. The support agent reads the card to answer a specific user question without escalating. The compliance reviewer reads the card during an annual audit to confirm the calculator is behaving as it was documented. The new team member reads the card during onboarding to understand what the team is responsible for. Each of these readers is different, and the card is compressed enough to serve all of them without any of them needing to open the full spec.

A specific audience the card is not written for is the end user. End users see the calculator; they benefit from the assumptions surface being visible or one click away, but they do not typically read the model card. Confusing the two audiences produces cards that read like marketing copy or cards that read like source code; neither serves the readers the card exists for. The card is an internal-facing artifact, and its audience is people who work on or with the calculator.

How the card composes across a family

A pack of related calculators — the mortgage-decisions pack, the retirement pack, the equity-compensation pack — benefits from a family-level card in addition to per-calculator cards. The family-level card names the shared assumptions, shared sources, and shared response envelope, so each per-calculator card can inherit them by reference rather than repeating them. The per-calculator card then focuses on what makes each calculator different: its specific purpose, its specific inputs, its specific outputs. This pattern keeps every card short and makes maintenance easier when a shared decision changes for the whole pack.