Skip to content

docs(Tanzania): back-casting is a country fact, not a food_acquired quirk (+ dispatcher rule)#652

Merged
ligon merged 2 commits into
developmentfrom
docs/contents-org-standing-rule
Jul 22, 2026
Merged

docs(Tanzania): back-casting is a country fact, not a food_acquired quirk (+ dispatcher rule)#652
ligon merged 2 commits into
developmentfrom
docs/contents-org-standing-rule

Conversation

@ligon

@ligon ligon commented Jul 22, 2026

Copy link
Copy Markdown
Owner

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 #114 entry, in the context of food_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 design section records:

variable label
UPHI Uniform Panel Household Identifier at NPSY4
r_hhid NPS HHID: y1_hhid, y2_hhid, y3_hhid, y4_hhid
round rows distinct UPHI distinct r_hhid
1 20,039 5,594 2,956
2 155,097 8,163 3,924
3 189,962 9,998 5,010
4 84,337 4,961 4,341

In round 1, 1,526 r_hhid carry more than one UPHI, 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 UPHI the index is unique, so nothing warns — absence of duplicates is not evidence the key is sound. Keyed on r_hhid the 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 inconsistentfood_acquired de-duplicates to r_hhid (408,707 → 228,281); 2008-15 shocks keys on UPHI — and that resolving this is a maintainer grain decision, not something to change as a side effect of unrelated work. The #114 entry 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.org 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.

Three things it adds beyond "read the file":

  • read the LOGBOOK/WAITING/TODO entries too — a closed GitHub issue can still have a live caveat parked there (#114 is closed; its entry is still WAITING);
  • a finding that contradicts CONTENTS.org is a result to report and quote, not licence to assume the file is stale;
  • add any genuine idiosyncrasy found that is not recorded.

The cost that motivated it

An agent reviewing Tanzania's .first() sites concluded shocks had a broken key because its i values shared nothing with household_roster. I endorsed that, then flagged it as a regression, then withdrew both — because Tanzania/_/CONTENTS.org already documented the whole phenomenon. Two rounds of confident, wrong framing from skipping one file.

Docs only. No behaviour change; the UPHI/r_hhid question is deliberately left open (see PR #651).

Sue the Coder and others added 2 commits July 21, 2026 20:42
…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>
@ligon
ligon merged commit 76c865c into development Jul 22, 2026
10 checks passed
@ligon
ligon deleted the docs/contents-org-standing-rule branch July 22, 2026 04:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant