# 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.