Filed from the Madison walkthrough audit (cog_explorer/docs/walkthroughs/FINDINGS.md, 2026-07-28). Verdict: definitional — the package's behaviour is the friendlier choice and is not wrong; the conversion is simply not stated where most readers meet the package.
Root cause
The raw Census source files report thousands of dollars. uscogdata multiplies by 1000 and returns amt_nominal, amt_real, amt_per_capita_nominal, and amt_per_capita_real in full US dollars. The conversion is real, correct, and recorded in the return value's provenance:
Meanwhile cog_explorer's CLAUDE.md states, correctly of the raw amt column and misleadingly of everything else: "All raw amt values are in $1,000s." A reader who applies that rule to amt_nominal overstates every figure by 1000x.
Where it is and isn't already documented (checked 2026-07-29, after the audit was written)
Surface
States the conversion?
?cog_spending / man/cog_spending.Rd@return
Yes — "Amounts are returned in full U.S. dollars (the raw corpus stores them in $1,000s; this verb multiplies by 1000…)"
So the finding's proposed data-dictionary sentence has partly landed already. What remains is that a reader who meets this package through its README, a vignette, the agent-facing llms.txt, or cog_explorer's own conventions doc gets no signal at all — and one of those actively points the wrong way.
Findings resolved
Finding
Severity
Summary
F-004
high
amt_nominal is full dollars, not the raw $1,000s
Reproduction (verbatim from FINDINGS.md, verified against the live corpus)
cog_spending(govid="552025209777",years=2022L)|>dplyr::filter(category=="Fire",spend_subtype=="capital")#> amt_nominal = 1317000 (i.e. $1.317M, not $1.317B)
Why it matters
This is the highest-consequence definitional gap the audit found. A 1000x overstatement produces a plausible-looking dollar amount, not an obvious error — nothing downstream will flag it. The correction is entirely available to the reader; it just isn't where the reader is.
Definition of done
README.md states the units once, in the first place a returned data frame is shown. The audit's proposed wording:
amt_nominal, amt_real, amt_per_capita_nominal and amt_per_capita_real are expressed in full US dollars. The underlying Census source files report thousands of dollars; uscogdata performs this conversion for you.
Both vignettes carry the same statement where they first print amounts.
Secondary task, cog_explorer/CLAUDE.md: its Data Conventions section needs a clause distinguishing raw amt (thousands) from amt_nominal and friends (full dollars). cog_explorer has no git remote, so it cannot carry its own issue; recorded here because this package performs the conversion. Whoever fixes (1) should make that edit in the same pass.
Secondary task, cog-api:llms.txt should carry the same sentence — data-dictionary.md already does, but llms.txt is the surface this API names for agent consumption and it is silent on units.
Test goes green: tests/testthat/test-amount-units-documented.R → test_that("returned amounts are documented as full US dollars where readers meet the package", ...). It asserts README.md and both vignettes state the conversion, and pins it numerically against the fixture — Madison FY2020 amt_nominal sums to exactly 1000 × the raw corpus's amt for the same government-year, read straight from the parquet partitions rather than through the verb — so the documented claim and the behaviour cannot drift apart. It deliberately does not assert on the .Rd files, which already carry the statement. Remove the skip() on line 1 of the test body to activate.
Severity: high. Verdict: definitional (documentation, plus a disclosure already present in provenance that the prose should point at).
Filed from the **Madison walkthrough audit** (`cog_explorer/docs/walkthroughs/FINDINGS.md`, 2026-07-28). Verdict: **definitional** — the package's behaviour is the friendlier choice and is not wrong; the conversion is simply not stated where most readers meet the package.
## Root cause
The raw Census source files report **thousands of dollars**. `uscogdata` multiplies by 1000 and returns `amt_nominal`, `amt_real`, `amt_per_capita_nominal`, and `amt_per_capita_real` in **full US dollars**. The conversion is real, correct, and recorded in the return value's provenance:
```r
attr(cog_spending("552025209777", 2020L), "provenance")$transformations$units_conversion
#> $applied TRUE
#> $source_unit "$1,000s (raw Census)"
#> $target_unit "$USD"
#> $multiplier 1000
```
Meanwhile `cog_explorer`'s `CLAUDE.md` states, correctly of the raw `amt` column and misleadingly of everything else: *"All raw `amt` values are in $1,000s."* A reader who applies that rule to `amt_nominal` overstates every figure by 1000x.
## Where it is and isn't already documented (checked 2026-07-29, after the audit was written)
| Surface | States the conversion? |
|---|---|
| `?cog_spending` / `man/cog_spending.Rd` `@return` | **Yes** — "Amounts are returned in **full U.S. dollars** (the raw corpus stores them in $1,000s; this verb multiplies by 1000…)" |
| `?cog_revenue` / `man/cog_revenue.Rd` `@return` | **Yes** — same wording |
| `provenance$transformations$units_conversion` | **Yes** |
| `README.md` | **No** |
| `vignettes/total-spending.Rmd`, `vignettes/population-denominators.Rmd` | **No** |
| `cog-api`'s `data-dictionary.md` | **Yes** (since 2b71b41, 2026-07-18) |
| `cog-api`'s `llms.txt` — the agent-facing surface | **No** |
| `cog_explorer/CLAUDE.md` | **No, and states the opposite rule** |
So the finding's proposed data-dictionary sentence has partly landed already. What remains is that a reader who meets this package through its README, a vignette, the agent-facing `llms.txt`, or `cog_explorer`'s own conventions doc gets no signal at all — and one of those actively points the wrong way.
## Findings resolved
| Finding | Severity | Summary |
|---|---|---|
| **F-004** | high | `amt_nominal` is full dollars, not the raw $1,000s |
## Reproduction (verbatim from FINDINGS.md, verified against the live corpus)
```r
cog_spending(govid = "552025209777", years = 2022L) |>
dplyr::filter(category == "Fire", spend_subtype == "capital")
#> amt_nominal = 1317000 (i.e. $1.317M, not $1.317B)
```
## Why it matters
**This is the highest-consequence definitional gap the audit found.** A 1000x overstatement produces a plausible-looking dollar amount, not an obvious error — nothing downstream will flag it. The correction is entirely available to the reader; it just isn't where the reader is.
## Definition of done
1. `README.md` states the units once, in the first place a returned data frame is shown. The audit's proposed wording:
> `amt_nominal`, `amt_real`, `amt_per_capita_nominal` and `amt_per_capita_real` are expressed in **full US dollars**. The underlying Census source files report thousands of dollars; uscogdata performs this conversion for you.
2. Both vignettes carry the same statement where they first print amounts.
3. **Secondary task, `cog_explorer/CLAUDE.md`:** its Data Conventions section needs a clause distinguishing raw `amt` (thousands) from `amt_nominal` and friends (full dollars). `cog_explorer` has **no git remote**, so it cannot carry its own issue; recorded here because this package performs the conversion. Whoever fixes (1) should make that edit in the same pass.
4. **Secondary task, `cog-api`:** `llms.txt` should carry the same sentence — `data-dictionary.md` already does, but `llms.txt` is the surface this API names for agent consumption and it is silent on units.
5. Test goes green: **`tests/testthat/test-amount-units-documented.R`** → `test_that("returned amounts are documented as full US dollars where readers meet the package", ...)`. It asserts `README.md` and both vignettes state the conversion, and pins it numerically against the fixture — Madison FY2020 `amt_nominal` sums to exactly `1000 ×` the raw corpus's `amt` for the same government-year, read straight from the parquet partitions rather than through the verb — so the documented claim and the behaviour cannot drift apart. It deliberately does **not** assert on the `.Rd` files, which already carry the statement. Remove the `skip()` on line 1 of the test body to activate.
**Severity: high. Verdict: definitional** (documentation, plus a disclosure already present in provenance that the prose should point at).
Taking this over. No kodor activity since assignment on 2026-07-29 — no branch, no PR, no comment — so I am picking it up rather than leaving it queued. Reassign back if kodor is simply slow and you would rather it land there; I will not push until this repo is otherwise quiet.
Being fixed together with the other two kodor/fix issues in one PR: they are all single-file, all have committed acceptance tests, and two of them touch the same documentation surfaces.
Taking this over. No kodor activity since assignment on 2026-07-29 — no branch, no PR, no comment — so I am picking it up rather than leaving it queued. Reassign back if kodor is simply slow and you would rather it land there; I will not push until this repo is otherwise quiet.
Being fixed together with the other two `kodor/fix` issues in one PR: they are all single-file, all have committed acceptance tests, and two of them touch the same documentation surfaces.
Fixed and merged in PR #22 (8db944e on main). Closing manually: that PR said "Closes #16, #15, #14", and Gitea only parsed the first reference, so #16 auto-closed while this one stayed open. The keyword needs repeating per issue.
Verified present on main, not just claimed.
Fixed and merged in PR #22 (`8db944e` on `main`). Closing manually: that PR said "Closes #16, #15, #14", and Gitea only parsed the first reference, so #16 auto-closed while this one stayed open. The keyword needs repeating per issue.
Verified present on `main`, not just claimed.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Filed from the Madison walkthrough audit (
cog_explorer/docs/walkthroughs/FINDINGS.md, 2026-07-28). Verdict: definitional — the package's behaviour is the friendlier choice and is not wrong; the conversion is simply not stated where most readers meet the package.Root cause
The raw Census source files report thousands of dollars.
uscogdatamultiplies by 1000 and returnsamt_nominal,amt_real,amt_per_capita_nominal, andamt_per_capita_realin full US dollars. The conversion is real, correct, and recorded in the return value's provenance:Meanwhile
cog_explorer'sCLAUDE.mdstates, correctly of the rawamtcolumn and misleadingly of everything else: "All rawamtvalues are in $1,000s." A reader who applies that rule toamt_nominaloverstates every figure by 1000x.Where it is and isn't already documented (checked 2026-07-29, after the audit was written)
?cog_spending/man/cog_spending.Rd@return?cog_revenue/man/cog_revenue.Rd@returnprovenance$transformations$units_conversionREADME.mdvignettes/total-spending.Rmd,vignettes/population-denominators.Rmdcog-api'sdata-dictionary.mdcog-api'sllms.txt— the agent-facing surfacecog_explorer/CLAUDE.mdSo the finding's proposed data-dictionary sentence has partly landed already. What remains is that a reader who meets this package through its README, a vignette, the agent-facing
llms.txt, orcog_explorer's own conventions doc gets no signal at all — and one of those actively points the wrong way.Findings resolved
amt_nominalis full dollars, not the raw $1,000sReproduction (verbatim from FINDINGS.md, verified against the live corpus)
Why it matters
This is the highest-consequence definitional gap the audit found. A 1000x overstatement produces a plausible-looking dollar amount, not an obvious error — nothing downstream will flag it. The correction is entirely available to the reader; it just isn't where the reader is.
Definition of done
README.mdstates the units once, in the first place a returned data frame is shown. The audit's proposed wording:Both vignettes carry the same statement where they first print amounts.
Secondary task,
cog_explorer/CLAUDE.md: its Data Conventions section needs a clause distinguishing rawamt(thousands) fromamt_nominaland friends (full dollars).cog_explorerhas no git remote, so it cannot carry its own issue; recorded here because this package performs the conversion. Whoever fixes (1) should make that edit in the same pass.Secondary task,
cog-api:llms.txtshould carry the same sentence —data-dictionary.mdalready does, butllms.txtis the surface this API names for agent consumption and it is silent on units.Test goes green:
tests/testthat/test-amount-units-documented.R→test_that("returned amounts are documented as full US dollars where readers meet the package", ...). It assertsREADME.mdand both vignettes state the conversion, and pins it numerically against the fixture — Madison FY2020amt_nominalsums to exactly1000 ×the raw corpus'samtfor the same government-year, read straight from the parquet partitions rather than through the verb — so the documented claim and the behaviour cannot drift apart. It deliberately does not assert on the.Rdfiles, which already carry the statement. Remove theskip()on line 1 of the test body to activate.Severity: high. Verdict: definitional (documentation, plus a disclosure already present in provenance that the prose should point at).
Taking this over. No kodor activity since assignment on 2026-07-29 — no branch, no PR, no comment — so I am picking it up rather than leaving it queued. Reassign back if kodor is simply slow and you would rather it land there; I will not push until this repo is otherwise quiet.
Being fixed together with the other two
kodor/fixissues in one PR: they are all single-file, all have committed acceptance tests, and two of them touch the same documentation surfaces.Fixed and merged in PR #22 (
8db944eonmain). Closing manually: that PR said "Closes #16, #15, #14", and Gitea only parsed the first reference, so #16 auto-closed while this one stayed open. The keyword needs repeating per issue.Verified present on
main, not just claimed.