You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
research/: add a README index; revise topic files instead of adding dated run records #279
If we do it: a reader who never saw the issue can find what link has settled from one index, and future parity runs revise one topic file instead of adding a dated sibling. If we never do: the largest research/ in the fleet (26 files) stays discoverable only through eight path citations in CLAUDE.md, and each provincial run adds another file that duplicates its own PWF archive.
Problem
research/ holds 26 files and no README.md; README.md at the repo root never mentions the directory. Measured 2026-09-06:
roughly two-thirds are point-in-time run records — provincial_parity_2026_05_01/_11/_12/_25.md, parity_accessible_habitat_2026_07_03.md, run_record_2026_08_31_cypher_pilots.md, distributed_2hosts_2026_05_01.md — each opening with Run / Hardware / Software / Configuration blocks and each with one revision
one-third are living documents — bcfishpass_methodology.md (3 revisions), study_area_run.md (8), provincial_run_runbook.md (3), the bcfp_* reference files — which is the shape that moves the state of knowledge
three filename patterns coexist: topic.md, topic_YYYY_MM_DD.md, and run_record_YYYY_MM_DD_x.md
The soul convention now says: one topic file revised in place, git as the version record, run records in the PWF archive README plus committed logs, and a README index with a naming cutover line — conventions/planning.md, "research/ — what is known, outliving the issue that found it" (NewGraphEnvironment/soul#202).
Proposed solution
Add research/README.md: one row per file with what it covers (rfp's is the model), a "Related work" list (fresh, bcfishpass, db_newgraph), and the cutover line:
Naming: `<topic>.md`, revised in place, from 2026-09-06.
Files dated before that carry a `_YYYY_MM_DD` suffix; they are not being renamed.
Do not rename anything — CLAUDE.md, PR bodies and issues cite these paths.
Going forward, a provincial parity run revises provincial_parity.md (create it from the 2026-05-25 state, header naming the archive and log prefix that last moved it) rather than adding provincial_parity_<date>.md; the run record itself goes in that issue's planning/archive/<issue>/README.mdMeasurement / Evidence sections.
CLAUDE.md links the README once; keep the individual citations only where a rule depends on the file (bcfp_divergence_taxonomy.yml read by lnk_parity_annotate() is one).
Activity