python-guidelineslisted

<!-- Generated by `basicly skills-build` from skill.yaml. Do not edit; edit the source. --> # Python Guidelines The judgement half of code quality: what a gate can only *report*. Formatting, import order, naming case, docstring shape, return/branch counts, dead code, import layering and module size are already enforced by `ruff`, `pyright`, `vulture`, `lint-imports` and `.scripts/check_module_size.py` — never restate them here or in a review comment. Read this before the build, not after the hook rejects: a violation discovered at the gate has already spent a round. Test quality is out of scope — `test-discipline` owns it. ## Where a module splits - Say the module's responsibility in one sentence. **If the sentence needs an "and", it is two modules.** Write that sentence into the module docstring together with the boundary against its nearest neighbour, in the form "the boundary is X against Y". If you cannot write the boundary, you have not found the seam yet — do not cut. - `.scripts/check_module_size.py` reports **that** a module is over the 4,000-token cap and never **where** to cut it. Moving the last N functions into a `_helpers` module clears the number and cuts nothing. - A real seam does not import back. `read_cost` imports nothing from the package it left; `plan_record` satisfies `plan_gate.PlannedFields` structurally rather than importing the module that judges it. If your extraction needs an import back into its origin, you cut across the