---
name: polylith-migrate-isolate-shared-and-project-logic
description: "[Internal sub-skill of `polylith-migrate-orchestrator`. Do not load directly — load `polylith-migrate-orchestrator` first, which drives all phases.] Identify and isolate shared and project-specific logic in monolithic components (e.g., `models`, `schemas`, or similar)."
---

# Skill: polylith-migrate-isolate-shared-and-project-logic

> 📐 **Scope vs sibling skills.** This skill is **cross-project**: it separates code used by **two or more projects** (shared) from code used by **a single project** (project-specific), potentially creating new shared *and* project-specific components. Don't confuse with:
> - `polylith-migrate-split-big-component` — within one project; splits one component into multiple components.
> - `polylith-migrate-split-component-internals` — within one component; splits one `core.py` into multiple files.
> - `polylith-migrate-dedupe` — opportunistic deduplication, broader than just shared-vs-project-specific.
>
> 💡 **When to skip this skill.** On the **first** project migration there is usually no second project to compare against. Skip this skill until at least one prior project has been migrated. The orchestrator still calls it after `polylith-migrate-extract-standalone-modules` — that's the right place when overlap exists.

## Goal
Identify and isolate shared and project-specific logic in monolithic components (e.g., `models`, `schemas`). Extract shared logic into reusable components and isolate project-specific logic into project-specific components.

## Inputs
From `migration/<PROJECT>/state.md`:
- `TARGET_TOP_NS`
- `INITIAL_BASE_NAME`
- Verification commands (`RUN_TEST_CMD`, `RUN_LINT_CMD`, `RUN_TYPECHECK_CMD`).

From `migration/<PROJECT>/manifest.md`:
- Module map of components.

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

## Steps

### 1. Identify Monolithic Components
- Scan the workspace for monolithic components (e.g., `models`, `schemas`).
- Focus on components with large `core.py` files or mixed domain logic.

### 2. Analyze Usage
- Use `grep` to trace imports of each definition in the component.
- Classify definitions as:
  - **Shared**: Used by multiple projects.
  - **Project-Specific**: Used by only one or a few projects.
  - **Similar**: Definitions that could reuse shared logic (e.g., similar models).

### 3. Extract Shared Logic
- Create a new shared component (e.g., `models_shared`, `schemas_shared`).
- Move shared definitions into the new component.
- Update imports in all projects to reference the shared component.

### 4. Isolate Project-Specific Logic
- Create project-specific components (e.g., `models_project_a`, `schemas_project_b`).
- Move project-specific definitions into the appropriate component.
- Update imports in the relevant projects.

### 5. Refactor Similar Models
- For similar models, extract shared logic into the shared component.
- Update the project-specific models to reuse the shared logic.

### 6. Update `pyproject.toml`
- Add the new shared and project-specific components to the workspace's `pyproject.toml`.
- Update the project's `pyproject.toml` to reference the new components.

### 7. Verify Changes
- Run `RUN_TEST_CMD` to ensure no regressions.
- Run `RUN_LINT_CMD` and `RUN_TYPECHECK_CMD` if set.
- Run `POLY_CMD_PREFIX check` to validate the workspace structure.

## Verify
- All tests pass (`RUN_TEST_CMD`).
- Linting and type-checking pass (if set).
- The workspace structure is valid (`POLY_CMD_PREFIX check`).

## Common failure modes

| Symptom | Likely cause | Remediation |
|---------|--------------|-------------|
| Only one project exists in the workspace, so there's nothing to compare against | Running this skill on the **first** project migration. | Skip the skill entirely. Record `polylith-migrate-isolate-shared-and-project-logic: skipped (single-project workspace)` in `migration/<PROJECT>/state.md` and proceed to `polylith-migrate-distribute-wiring`. Revisit when a second project is migrated. |
| A definition looks shared but is actually used by one project via two different bases inside that project | Bases within one project both use it — still single-project usage. | Leave it project-specific. Cross-project sharing requires consumers in **different** projects under `projects/`. |
| Two projects each have a "same" class with subtle field differences (extra fields, different defaults) | Silent merging would change behaviour. | Do **not** merge silently. Either create a shared base class + project-specific subclasses, or keep the implementations separate and accept the duplication. Confirm with the user. |

## Done When
- Shared logic is extracted into reusable components.
- Project-specific logic is isolated into project-specific components.
- Similar models reuse shared logic where possible.
- All tests and checks pass.
- The workspace structure is valid.

## Commit

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

```bash
git add -A && git commit -m "migrate(<PROJECT>): phase <N> — isolate-shared-and-project-logic"
```

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.