Skip to content

ADR-0013 — Seed compilation scope for seed-backed scrapers

Status: Accepted Date: 2026-05-21 Supersedes: — Superseded by: — Related: ADR-0011 (per-scraper inheritance pattern); cycle 10.5 (universe-only precedent); cycle 11 commit c8d90d4 (empirical basis)

Context

Cycle 10.5 set a precedent for seed compilation scope: the NGO-TARGETS seed was compiled against the current screen universe only (8 of 17 financials). Institutions outside the current universe were excluded, with a note that a broader compilation pass was parked for cycle 15.

Cycle 11 (CHRB + FOREST500, commit c8d90d4) departed from that precedent. Both seeds were pre-populated against the current universe plus known near-term expansion targets (institutions designated for cycle 15b / 15c). This produced seeds that will light up signals automatically when those institutions are added in cycle 15, without a seed-side touchup at that point.

The departure raised the question of whether cycle 10.5's universe-only scope was the intended standing pattern or whether cycle 11's broader scope was better. This ADR records the answer.

Decision

Pre-seed against the current universe plus known near-term expansion targets. This is the standing pattern for all seed-backed scrapers going forward.

Concretely: when compiling a seed file, include entries for: - All institutions currently in the screen universe, and - All institutions designated as known near-term additions (e.g. cycle 15a/b/c targets as of the compilation date).

Do not include speculative or unknown future additions.

Rationale

(a) Cheaper at expansion time. When new institutions are added in cycle 15, seeds already carrying their entries will produce signals on the first run without a seed-side touchup. Universe-only seeds require a retrofit at the point of each expansion.

(b) Eliminates the parked-work pattern. Cycle 10.5's universe-only scope created a parked item ("NGO-TARGETS comprehensive pass — defer to cycle 15"). This pattern generates follow-up debt proportional to the number of expansion targets known at compilation time.

(c) No incremental compilation cost. Seed files are compiled from public-data sources. Including an expansion-target entry costs the same as any other entry. The work happens once at seed creation time rather than twice (creation + retrofit).

(d) Universe-only seeds are strictly worse. The only argument for universe-only scope is simplicity. But the simplicity is illusory — the follow-up work still exists, it's just deferred rather than front-loaded.

Consequences

  • NGO-TARGETS retrofit: the cycle 10.5 NGO-TARGETS seed is universe-only and does not yet follow this pattern. A one-time retrofit (adding C15 expansion targets to the seed) is a candidate for C15a prep. Decision deferred per backlog.
  • Cycle 11 seeds: CHRB and FOREST500 follow this pattern from the start. No action needed.
  • At cycle 15: newly-added institutions may surface in current seeds beyond what was pre-seeded (e.g. an institution added in 15d that wasn't known at C11 compilation time). Seeds still need a check pass at cycle 15. The pattern reduces the check cost, not eliminates it.
  • Future scrapers: INFLUENCEMAP, CA100PLUS (cycle 12) and any beyond follow this pattern. Record the expansion-target baseline at seed compilation time in the seed file's _metadata block.

References

  • Cycle 10.5 NGO-TARGETS seed compilation (universe-only precedent)
  • Cycle 11 CHRB + FOREST500 seed build, commit c8d90d4 (empirical basis for this decision)
  • ADR-0011 (per-scraper inheritance pattern — complementary; same "explicit per-scraper decision" philosophy)
  • Backlog: NGO-TARGETS seed comprehensive-pass parked item (C15a prep candidate)