# ADR-006: Tract-Level Geography Bug Fixes
**Status:** Accepted
**Date:** 2026-02-08
**Traces To:** G.9 (implementation_schedule.md), G.4 findings (phase4a_manual_validation.md)
## Context
Phase 4A three-model comparison (G.4) revealed that all three models (Sonnet 4, Sonnet 4.5, Opus 4.6) failed to retrieve tract-level data via `get_acs_data`. The Census API silently returned county-level data instead. Investigation identified two code bugs and one missing capability.
## Problem Analysis
### Bug 1: `elif` Chain Makes Tract Unreachable (census_client.py)
The `get_acs5` method builds geography using an `elif` chain:
```python
if county:
for_geo = f"county:{county}"
elif place:
for_geo = f"place:{place}"
elif tract:
for_geo = f"tract:{tract}"
```
When both `tract` and `county` are provided (which is required by the Census API), `county` wins and tract is never reached. This is a logic error independent of any test case.
Additionally, when tract IS reached (county omitted), it generates `for=tract:X&in=state:Y` — missing the required county in the `in=` clause. The Census API specification requires: `for=tract:X&in=state:Y+county:Z`.
**Classification:** Bug. The code cannot produce a valid tract-level API call under any input combination.
### Bug 2: Silent Fallback on Invalid Geography (server.py)
When a caller passes `tract` without `county`, the server constructs a malformed API call. The Census API doesn't error — it silently returns county-level data. The caller receives data that looks correct but is at the wrong geographic level.
**Classification:** Bug. Silent wrong-level data is worse than an error. Any tool that returns data at a different geography than requested without warning is broken.
### Missing Capability: Wildcard Tract Enumeration
The Census API supports `for=tract:*&in=state:X+county:Y` to enumerate all tracts in a county. Our tool doesn't expose this. This was surfaced by the Owsley test but is a general capability gap — any user wanting tract-level data for a county needs this.
**Classification:** Missing feature, not overfitting. Wildcard enumeration is documented Census API functionality that we simply weren't exposing.
## Decision
### Fix 1: Rewrite geography construction in `census_client.py`
Replace `elif` chain with priority-ordered `if` that handles tract + county correctly. Tract queries build proper `in=state:X+county:Y` clause.
### Fix 2: Add county validation in `server.py`
Return explicit error when `tract` is provided without `county`. Error message explains why county is required and suggests alternatives.
### Fix 3: Update tool description
Document that tract parameter requires county. Add wildcard support note.
## What This Is NOT
These fixes do NOT encode the Owsley County test case findings. Specifically:
- No population threshold checks in code (belongs in pragmatics packs, G.11)
- No "tract equals county" detection (belongs in pragmatics packs, G.11)
- No disclosure avoidance warnings in code (belongs in pragmatics packs, G.10)
The line between bug fix and overfitting: if it's about how the Census API works (specification), it's a bug fix. If it's about how to interpret the data (domain expertise), it's a pack.
## Consequences
- Tract-level queries will work when both state and county are provided
- Callers get explicit errors instead of silent wrong-level data
- Tool description guides LLMs to provide county with tract requests
- Wildcard `tract:*` enables tract enumeration within a county
