skills.rest
PostHog
PostHogOFFICIAL
Explore all skills by this author →
Website𝕏@PostHogGitHub

splitting-oversized-modules

Split oversized Python modules into per-concern packages with AST-based verification.

713|118|Updated Aug 11, 2020
Search Tags:#verification#Python#Refactoring#Testing#ast#Code splitting#module decomposition
One-click install
npx skills add https://github.com/PostHog/posthog-foss --skill splitting-oversized-modules
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: splitting-oversized-modules
Source: https://github.com/PostHog/posthog-foss/tree/main/.agents/skills/splitting-oversized-modules
Command: npx skills add https://github.com/PostHog/posthog-foss --skill splitting-oversized-modules

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Thousand-line Python modules like logic.py or models.py force every change to read the entire file, inflating review cost and token usage. This Skill mechanically splits such a module into a package of one module per concern while proving the move changed no behavior.

Core Features & Use Cases

  • Layout planning: Generates a JSON skeleton of every top-level symbol so you can assign symbols to concern-named modules with an acyclic dependency graph.
  • Verbatim code move: The split_module.py script copies each symbol by AST line range, deepens relative imports, and requalifies cross-module references via tokenize without touching strings or docstrings.
  • Pure-move verification: verify_pure_move.py compares every definition before and after the split, reporting missing, unexpected, changed, or duplicated symbols.
  • Use Case: A 3000-line logic.py with a matching 3000-line test file is split into a logic/ package and mirrored test package, landed as its own PR, with the verifier confirming every definition is identical modulo module qualification.

Quick Start

Ask the AI to split the oversized module products/foo/backend/logic.py into a package of one module per concern and verify the result is a pure move.

Frequently Asked Questions about splitting-oversized-modules

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I split a large Python module into multiple files?▼

Generate a layout skeleton with split_module.py --skeleton, assign each top-level symbol to a concern-named module in the JSON, then run the script to copy symbols verbatim by AST line range. Finish with ruff check --fix, ruff format, and verify_pure_move.py to confirm nothing changed.

How to break up a god object or god module in Python?▼

Map the module's symbols to concerns with an acyclic dependency graph, then move them mechanically rather than hand-editing. The split script refuses to run unless the layout covers every symbol exactly once, preventing code from silently going missing.

When is it not worth splitting a large Python file?▼

Skip the split when the file is under roughly a thousand lines, is cohesive and frozen, is generated, or has several people mid-change in it. Extracting helpers in place leaves everything in the same file, so it does not reduce the read-set.

Does splitting a Django models.py file need special handling?▼

Yes, a models.py split is the one case needing re-exports. Django imports an app's models package but does not recurse into submodules, so model classes must be aggregated in models/__init__.py or they never reach the app registry.

Why do mock patches break after splitting a Python module?▼

Patch targets must move to the module that defines the symbol, since that is the binding callers resolve. Sweep conftest.py as well as test files, and avoid re-export shims in __init__.py, which create two bindings and let patches silently miss internal callers.

How do I verify a module split did not change behavior?▼

Extract the original file from git and run verify_pure_move.py against the new package. It compares every top-level definition before and after, ignoring module qualification and import depth, and reports missing, unexpected, changed, or conflicting symbols.

Related Skills

Explore More Software Engineering Skills→
je3ykje3yk
1

split-branch-for-review

Analyze branch code change size and recommend splitting based on line count and complexity.

Community
Advanced
ArthTech-AIArthTech-AI

precheck

Run local pre-push tests on changed hooks, skills, and manifests.

Official
Advanced
Unique-AGUnique-AG
5

ruff

Automate Python linting and formatting with Ruff auto-fixes.

Official
Intermediate
AskTinNguyenAskTinNguyen

vesper-monolith-refactor

Decompose oversized Vesper owner seams into adjacent modules via facade-first extraction.

Community
Advanced