research-code-parsimony

Research Code Parsimony

Establish The Contract And The Owner First

Before adding code, be able to state:

• the behavior or scientific contract being requested, including what must stay reproducible;
• the module, function, script, or config that already owns this behavior, and which callers actually exercise it;
• whether a maintained dependency or a native language/library capability already provides it.

Search before creating an owner. If none fits a genuinely new capability, create one clear owner rather than forcing unrelated behavior into an existing module.

Reuse Before You Add

• Extend an understood existing owner instead of introducing a parallel one.
• Prefer a maintained dependency when it reduces ownership burden while meeting the scientific and operational contract. Check the standard library and present dependencies first.
• Parsimony means less code to own — not fewest files, shortest diff, or clever one-liners. Readable, explicit code beats a compressed version.
• Never satisfy the request by solving a smaller or easier scientific problem than the one asked for.

Express Cohesive Families As Directories

Prefer a meaningful package hierarchy over a flat directory of long, repeated-prefix filenames. When several modules belong to one scientific or contract family, let the directory carry that context and give the modules short role names: for example, training/concentration_field/diffusion/runtime.py rather than training/concentration_field_diffusion_runtime.py. A separate training/physics_field/direct_inverse/ can own its own data, objective, and QC modules; genuinely shared training infrastructure stays at the shared level. Group by cohesive ownership, not chronology, and add depth only when it makes navigation and responsibilities clearer. Do not create speculative package trees or duplicate a family merely to achieve symmetry.

Apply this preference when choosing a new owner's home. Existing flat families can move in a bounded, authorized pass coordinated with their current owners; this preference does not authorize reorganizing active work during another task. Leave queued/running execution checkouts and immutable run artifacts untouched. Move live imports, entrypoints, config references, and hashed execution declarations together, updating valid source pins according to local policy. Validate the affected execution paths and remove old module routes without compatibility aliases. Completed runs retain their producing layout through their pinned commits, not duplicate source at HEAD.