US Individual Tax Preparation
US Individual Federal Tax Preparation (Form 1040 and its schedules) is Spectral’s first world-model domain. The selection rationale lives in ADR-029; this subtree is the operator-facing and dev-facing companion — a problem-space breakdown, a source-material inventory, and a rule-coverage overview that evolves as the Operations-app dogfooding proceeds.
Why tax prep
Section titled “Why tax prep”Three things have to be true of the first domain: it has to bootstrap the action registry +
rule corpus + module store at non-trivial scale, it has to be interesting enough to stay in the
apps/test-agents harness indefinitely, and it has to be something a careful generalist can
validate without an SME on call. US individual federal tax prep clears all three bars —
publication-grade Authoritative sources (IRS publications + Form 1040 instructions) are freely
available; the action surface is genuinely diverse (filing status, deductions, credits,
schedules); and a careful generalist can validate rules against published IRS text without a
CPA’s sign-off per rule.
See ADR-029 for the full selection analysis and the rejected alternatives (Healthcare PA, Legal Contract Analysis, Building Codes, Financial Compliance).
Tax year, jurisdiction, form surface:
- Jurisdiction: United States federal individual income tax only. No state, no local, no foreign-tax-credit-as-primary. (State and local come later; foreign-tax-credit appears only as a line item on Form 1040 / Schedule 3 within the federal return.)
- Form surface: Form 1040 and the schedules attached by individuals — Schedules A, B, C, D, E, SE, 1, 2, 3, plus the 1040-instruction content that governs them.
- Tax year discipline: The world model is versioned per tax year. Rule corrections across
years flow through the release-notes restatement mechanism
(per ADR-026) — prior years’
WorldModelCards remain authoritative for those years. - Taxpayer type: Individuals. Businesses (Form 1120 / 1120-S / 1065) are out of scope, even for pass-through income reported on the individual return.
Out of scope (permanently, for this domain):
- State income tax, local income tax, sales tax, property tax, payroll-tax withholding beyond what appears on the 1040
- Corporate, partnership, and trust returns
- Estate and gift tax (Forms 706 / 709)
- International filing complexity beyond what Form 1040 itself accommodates
Problem spaces in scope
Section titled “Problem spaces in scope”The problem spaces in scope are selected to reach the 50-enshrined-rule floor across two registered actions while exercising the full authoring path (context schema + configuration block + action registry + rule code-generation + both gates):
| Problem space | Action(s) | Why |
|---|---|---|
| Filing status determination | filing.determine_status | Narrow, decidable, high edge-case density (married-filing-separately qualifying conditions, head-of-household dependency rules, qualifying widow(er) continuation). Exercises applies_when filters and the four-state status taxonomy (GREEN / GREEN-SKIP / YELLOW / RED). |
| Standard deduction | deduction.compute_standard | Tightly coupled to filing status — natural pair. Covers age / blindness / dependent modifiers; exercises configuration-block behavior (amounts change annually from a single primary source, baked into predicate code at code-gen time per World Model). |
These two together give roughly 50–70 enshrinable rules — enough to cross the bootstrap floor and enough variety (status classification + quantitative modifier lookup + edge-case handling) to stress-test the full decision-time pipeline end-to-end.
Problem spaces enumerates the full list, including problem spaces not yet in scope and their prerequisites.
Problem spaces not yet in scope
Section titled “Problem spaces not yet in scope”The tax domain is rich; the world model’s current scope deliberately starts narrow. The following problem spaces are not yet in scope; each is listed with why it waits and what would lead the operator to pull it in.
- Dependents (qualifying child / qualifying relative tests)
- Itemized deductions (Schedule A — medical, SALT cap, charitable, home-mortgage interest)
- Self-employment income + SE tax (Schedule C + Schedule SE)
- Capital gains and losses (Schedule D, short-term vs long-term, wash-sale rules)
- Tax credits (Child Tax Credit, Earned Income Credit, education credits)
- Retirement contributions + distributions (IRA, 401(k), RMDs)
- AMT (Alternative Minimum Tax triggers and computation)
See problem-spaces.mdx for the why-not-yet and pull-in-trigger for each.
Why this domain double-duties as the test-agent backbone
Section titled “Why this domain double-duties as the test-agent backbone”apps/test-agents is home to the tax_prep agent that exercises the full decision-time pipeline
end-to-end as a real external customer. The agent consults /decide before every consequential
judgment and honors the four-state outcome Spectral returns — it holds no tax-judgment logic of its
own. It is one LangGraph orchestrator run two ways over the same graph: a reproducible validation
driver that fail-loud asserts a set of full-taxpayer personas (spanning GREEN, YELLOW-held,
RED-recovered) — the standing system: gate — and an interactive shell for live human runs. See
Test Agents for the backbone reference.
The world-model domain and the test-agent agent are the same thing: the deployed action modules the tax-prep test agent calls into come from the published tax world model. This is deliberate — it means a CI decision-time invocation and a real design-partner invocation go through the same decision-server against the same module store entries.
When a second domain ships
Section titled “When a second domain ships”Spectral is domain-agnostic infrastructure by construction — no customer domain-specific structure, features, or knowledge is designed into the system. Tax-prep is the first world model, not the only one the system supports. A second world-model domain ships when three conditions are met: an operator commits to the curation work for the second domain (the operator-walkthrough effort is the gating cost — bootstrap of a new world model end-to-end); the source-material inventory clears the same Authoritative-grounding bar tax-prep cleared (domain authority publishes specifications, regulatory text, or standards-body material that can ground the rule corpus); and the test-agent harness expands to cover the second domain so CI exercises both. The criteria for picking domain #2 are commercial — driven by design-partner demand and operator-team capacity — and live outside the Codex.
Pages in this subtree
Section titled “Pages in this subtree”- Problem spaces — full enumeration, scope boundaries, prerequisites for pulling each space into scope
- Source materials — IRS publication inventory (links, revision years, relevance per problem space)
- Rules — rule-coverage overview; populated as bootstrap proceeds
Related reading
Section titled “Related reading”- ADR-029 — the selection decision and rejected alternatives
- World Model — the context-schema + configuration + action-registry + rule shape this domain populates
- Operations App — the surface that authors the world model