docs(Tanzania): back-casting is a country fact, not a food_acquired quirk (+ dispatcher rule)#652
Merged
Merged
Conversation
…quired quirk Tanzania's NPS handles split-offs differently from most (possibly all) other surveys here: when a child leaves and founds a household, UPD4 creates new observations in the EARLIER waves too, carrying the ancestor's record back under the descendant's own panel id. This was already written up -- but only inside the `#114` entry, in the context of `food_acquired`, which made it read as a food-specific quirk. It is not: it is a property of the panel construction and every 2008-15 table inherits a choice from it. Adds a top-level `* Survey design` section stating it as a country fact, with: - the two identifiers and their Stata labels (`UPHI` = "Uniform Panel Household Identifier at NPSY4"; `r_hhid` = the round-specific id); - measured cardinalities -- round 1 has 2,956 `r_hhid` but 5,594 `UPHI`, with 1,526 households carrying up to 11; - the consequence that NEITHER key produces a signal the usual duplicate-index instruments can see: on `UPHI` the index is unique so nothing warns, and on `r_hhid` the back-cast copies collapse losslessly and silently; - the fact that the tables are currently INCONSISTENT (`food_acquired` de-duplicates to `r_hhid`, 2008-15 `shocks` keys on `UPHI`) and that resolving it is a maintainer grain decision, not a side effect of unrelated work. The `#114` entry gets a scope note pointing up at it, so the food-specific framing can no longer be mistaken for the whole story. ## Why this is in CLAUDE.md too An agent reviewing Tanzania's `.first()` sites concluded the `shocks` key was broken (its `i` values share nothing with `household_roster`). I endorsed that, then flagged it as a regression, then withdrew both -- all of it avoidable by reading one file first. The `add-feature` skill already says "Read existing documentation FIRST ... Start here". The gap is that a dispatched agent reads only what its brief tells it to, so this is the DISPATCHER's responsibility, and that is where the rule now lives. It also notes that a CLOSED issue can still have a live `WAITING` caveat in `CONTENTS.org` (as `#114` does), that a finding contradicting the file is a result to quote rather than grounds to assume staleness, and that undocumented idiosyncrasies should be added. Docs only. No behaviour change; the `UPHI`/`r_hhid` question is left open on purpose. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ules did not bite
The `add-feature` skill ("Read existing documentation FIRST ... Start here") and
CLAUDE.md §"A script is a complication" ("BEFORE editing any script-path table,
read the country's `_/CONTENTS.org` ... Then say what you found") were BOTH
already binding on the 2026-07-21 Uganda `crop_production` task, which is
script-path. Neither bit.
The agent's own diagnosis, which is better than mine: those rules live in files
an agent skims, not in the brief it is handed. A rule that must be internalised
is not enforcement. So the operative fix is a checklist item in the prompt --
plus the existing demand that the agent NAME the idiosyncrasy rather than assert
it checked.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two changes, one cause.
1. The Tanzania NPS back-casting is documented as a country-level fact
Tanzania handles split-offs differently from most — possibly all — other surveys here. When a child leaves and founds a household, UPD4 creates new observations in the earlier waves too, carrying the ancestor's record back under the descendant's own panel identifier.
This was already written up — but only inside the
#114entry, in the context offood_acquired. That framing made it read as a food-specific quirk. It is a property of the panel construction, and every 2008-15 table inherits a choice from it.New top-level
* Survey designsection records:UPHIr_hhidUPHIr_hhidIn round 1, 1,526
r_hhidcarry more than oneUPHI, up to 11.The load-bearing consequence, which is why this needed writing down: neither key produces a signal the usual duplicate-index instruments can see. Keyed on
UPHIthe index is unique, so nothing warns — absence of duplicates is not evidence the key is sound. Keyed onr_hhidthe back-cast copies collapse, and since their payloads are identical the collapse is value-lossless and equally silent.It also records that the tables are currently inconsistent —
food_acquiredde-duplicates tor_hhid(408,707 → 228,281); 2008-15shockskeys onUPHI— and that resolving this is a maintainer grain decision, not something to change as a side effect of unrelated work. The#114entry gains a scope note pointing up at the new section.2. A dispatcher rule in CLAUDE.md
Any agent scoped to a country must be told to read
countries/{C}/_/CONTENTS.orgfirst.The
add-featureskill already says "Read existing documentation FIRST … Start here". The gap is that a dispatched agent reads only what its brief tells it to — so this is the dispatcher's responsibility, and that is where the rule now lives.Three things it adds beyond "read the file":
LOGBOOK/WAITING/TODOentries too — a closed GitHub issue can still have a live caveat parked there (#114is closed; its entry is stillWAITING);CONTENTS.orgis a result to report and quote, not licence to assume the file is stale;The cost that motivated it
An agent reviewing Tanzania's
.first()sites concludedshockshad a broken key because itsivalues shared nothing withhousehold_roster. I endorsed that, then flagged it as a regression, then withdrew both — becauseTanzania/_/CONTENTS.orgalready documented the whole phenomenon. Two rounds of confident, wrong framing from skipping one file.Docs only. No behaviour change; the
UPHI/r_hhidquestion is deliberately left open (see PR #651).