Prayer_for_Relief_Docs/docs/workflows/python-work.md

Python and Quantitative Work Workflow

1. Inspect before changing

Determine:

• Python version and execution environment;
• package manager and lockfile;
• existing dependencies, style, tests, and entry points;
• data schema, units, keys, time indexes, missing values, and expected outputs;
• whether the task is exploratory, production, or evidentiary.

Do not replace the project's toolchain without a task-specific reason.

2. Design the smallest adequate solution

Prefer:

• existing dependencies before new dependencies;
• small functions with explicit inputs and outputs;
• pathlib for paths;
• type hints for nontrivial interfaces;
• deterministic random seeds;
• clear units, index conventions, and numerical tolerances;
• scripts or modules as the reproducible source of truth, even when a notebook is used for exploration.

Avoid hidden global state, silent data coercion, and unrelated refactoring.

3. Protect data and secrets

• Treat raw data as immutable.
• Write intermediate and final results to designated derived-data or artifact paths.
• Never print, commit, or transmit secrets.
• Confirm before accessing external systems, installing production dependencies, or performing costly computation.
• Record material transformations and exclusions.

4. Validate

Select checks proportionate to the task:

• syntax/import check;
• targeted unit tests;
• smoke test on a small sample;
• edge cases and failure paths;
• schema, uniqueness, merge, and index-alignment checks;
• missing-value and outlier checks;
• unit and dimensional consistency;
• tolerance-based numerical assertions;
• independent formula or implementation;
• benchmark or regression test against a known result;
• look-ahead, survivorship, leakage, and timing checks for empirical finance or econometrics.

5. Report

State:

• files changed;
• commands actually run;
• tests and numerical checks;
• results;
• data or environment assumptions;
• warnings, failures, and untested branches;
• reproduction steps.

Never convert an unexecuted suggestion into a claim that the code works.