davidvujic Skill: polylith-migrate-distribute-wiring
Goal
Distribute app-wiring code from the residual component into the appropriate bases and shared components.
Inputs
From migration/<PROJECT>/state.md:
TARGET_TOP_NSINITIAL_BASE_NAME- Verification commands.
- Base names.
From migration/<PROJECT>/manifest.md:
- Current module map, including what remains in the residual component.
All inputs from
state.mdare assumed to satisfy the validation rules inpolylith-migrate-discover(### Validation rules). Validate before proceeding.
Steps
1. Read the Residual Component
- List every public function remaining in the residual module.
- Confirm it contains only app-wiring code.
2. Identify the Split
- Trace callers of each function (use
grep). - Group callers by base or runner script.
- Map each function to its natural base:
| Function Pattern | Belongs In | Rationale |
|---|---|---|
init_consumer, close_consumer |
Handler/consumer base | Kafka consumer lifecycle is handler-specific |
init_job |
Jobs base | Job bootstrap is jobs-specific |
init_api / app factory |
API base | HTTP server setup is API-specific |
3. Extract Shared Helpers
- Identify shared init functions (e.g.,
init_logging,init_db). - Move shared helpers to a
bootstrapcomponent if needed.
4. Move Composite Functions
- Move composite functions to their respective bases.
- Update runner scripts to import from the base directly.
5. Update Tests
- Update integration tests to monkeypatch the correct module.
6. Clean Up
- Delete the residual component directory.
- Update
pyproject.tomlto remove the residual brick.
Verify
RUN_TEST_CMDsucceeds.- If set,
RUN_LINT_CMDandRUN_TYPECHECK_CMDsucceed. - Run
POLY_CMD_PREFIX checkto validate the workspace structure. - Run
POLY_CMD_PREFIX syncto synchronize the[tool.polylith.bricks]table with actual imports.
Common failure modes
| Symptom | Likely cause | Remediation |
|---|---|---|
Two bases now import the same init_<x> function and the residual still exists |
Step 6 wasn't reached — the function moved into one base but the residual reference wasn't deleted. | Confirm the residual is gone; if init_<x> is genuinely shared by 2+ bases, it belongs in a shared bootstrap component (step 3), not in either base. |
mock.patch("<TARGET_TOP_NS>.<INITIAL_BASE_NAME>.init_api") fails after the move |
The test references the old residual path; the function now lives in a base. | Update mock patch strings to the new location, typically <TARGET_TOP_NS>.<base_name>.<init_func>. |
poly check says the residual brick is still declared but its files are gone |
pyproject.toml [tool.polylith.bricks] still lists the deleted brick. |
Remove the line from [tool.polylith.bricks] and re-run POLY_CMD_PREFIX sync --quiet. |
| Application starts but a runtime feature is missing (e.g., logging, DB) | A shared init helper was moved into one base only. The other base never calls it. | Promote the helper to a shared bootstrap component and call it from every base's startup path. |
| Verification fails and you can't quickly diagnose | Phase commit not yet made. | git reset --hard HEAD to roll back to the previous phase's commit and consult the user. |
Commit
After verification passes, commit this phase to the migration branch:
git add -A && git commit -m "migrate(<PROJECT>): phase <N> — distribute-wiring"
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.