polylith-migrate-split-component-internals

name	polylith-migrate-split-component-internals
description	[Internal sub-skill of `polylith-migrate-orchestrator`. Do not load directly — load `polylith-migrate-orchestrator` first, which drives all phases.] Split monolithic `core.py` files in shared components into domain-focused modules.

Skill: polylith-migrate-split-component-internals

📐 Scope vs sibling skills. This skill operates inside one already-extracted component, splitting its core.py into multiple sibling Python files. No new components are created — only the internal file layout changes. Don't confuse with:

• polylith-migrate-split-big-component — splits one component into multiple components. Use that when the unit being broken up is a component, not a file.
• polylith-migrate-isolate-shared-and-project-logic — separates shared vs project-specific code across components and projects; may create new components.
• polylith-migrate-extract-standalone-modules — pulls foundational modules out of the residual big component into new standalone components.

Goal

Split monolithic core.py files in shared components (e.g., models_shared, schemas_shared, or similar) into domain-focused modules. This skill ensures that shared components remain well-organized and maintainable.

Inputs

From migration/<PROJECT>/state.md:

• TARGET_TOP_NS
• Verification commands.

From migration/<PROJECT>/manifest.md:

• Current component list and structure.

All inputs from state.md are assumed to satisfy the validation rules in polylith-migrate-discover (### Validation rules). Validate before proceeding.

Steps

1. Identify Candidates

• Scan components for large core.py files.
• A component is a candidate if:
  • The file contains definitions from multiple domains.
  • The file contains helper/utility functions alongside class definitions.
  • The file exceeds a reasonable size threshold.

2. Group Definitions by Domain

• Group definitions by the domain concept they serve.
• Example domains: ORM models, schema/dataclass clusters, helper functions.

3. Create New Modules

• Create domain-focused modules (e.g., merchant.py, transaction.py).
• Move relevant definitions from core.py to the new modules.

4. Update __init__.py

• Re-export public names from the new modules in __init__.py.

5. Handle core.py

• Delete core.py if all definitions have been moved.
• Keep core.py if it serves as a composition point.

Verify

• RUN_TEST_CMD succeeds.
• If set, RUN_LINT_CMD and RUN_TYPECHECK_CMD succeed.

Common failure modes

Symptom	Likely cause	Remediation
core.py is small (<100 lines) but mixes two domains	The component itself is too small to warrant an internal split.	Leave it. Splitting adds indirection without benefit at this size; revisit when the file grows.
After splitting, an import like from <ns>.<component> import <symbol> fails	__init__.py was not updated to re-export the symbol from its new module.	Add from <ns>.<component>.<new_module> import <symbol> to __init__.py. The component's public API must remain stable across the split.
New files inside the component now circularly import each other (e.g., models/user.py ↔ models/transaction.py)	Domain split was too aggressive; the two files genuinely share a concept.	Extract the shared concept into a third file (e.g., models/_base.py) and have both depend on it.

Commit

After verification passes, commit this phase to the migration branch:

git add -A && git commit -m "migrate(<PROJECT>): phase <N> — split-component-internals"

Substitute <PROJECT>, <N>, and <phase-name> from state.md and the orchestrator's phase table. Do not proceed to the next phase without a clean commit — the per-phase commit is the rollback point for the next phase's failure-mode tables.