Polylith Migrate Dedupe

Skill: polylith-migrate-dedupe

📐 Scope vs sibling skills. This skill is opportunistic deduplication that may be triggered any time during refactoring when duplication candidates surface. It is not the canonical place for the structural decompositions:

• For "split this big component into smaller ones", use polylith-migrate-split-big-component (it already includes a dedup-analysis subsection — usually sufficient on a first migration).
• For "this component's core.py mixes domains", use polylith-migrate-split-component-internals.
• For "two projects have overlapping code, split shared from project-specific", use polylith-migrate-isolate-shared-and-project-logic.

Use polylith-migrate-dedupe when none of the above fits cleanly — e.g., duplication discovered across already-extracted components that don't map to a structural split.

Goal

Identify duplication candidates during the migration process and execute controlled deduplication for user-approved candidates.

When to Use

• After splitting the big component or extracting standalone modules.
• When potential duplication between components is suspected.

Classification

Use this table when deciding whether a candidate is a real duplicate:

When to parameterize vs. keep separate

• Parameterize when the core logic is identical and only data/config differs.
• Keep separate when control flow or structure diverges (different frameworks, different patterns) — forcing a shared abstraction here creates a brittle "shared core" that grows project-specific flags over time.
• Extract shared base + per-project wrappers when there's a significant shared core but non-trivial project-specific logic around it.

Worked example — logging

Two projects each had their own init_logging. The core (structlog setup, base log levels, JSON formatter) was identical; the differences were:

• Project A added loggers for httpx, backoff.
• Project B added a logger for confluent_kafka_helpers.

The shared component exposed an init(config, *, extra_loggers=None, cache_logger_on_first_use=False) function. Each project's base calls init with its own extra_loggers dict. No coincidental coupling, no version skew, and adding a third project requires only its own dict — not a change to the shared component.

Shared-component naming

When creating a shared component to deduplicate code, name it after the domain or capability it represents, never after how it's used. Good: logging, kafka_client, merchant_serializer. Bad: shared_utils, common, helpers, misc. Generic-named bricks attract more code over time and become the next thing that needs decomposing.

Inputs

From migration/<PROJECT>/state.md:

• TARGET_TOP_NS
• 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 Duplication Candidates

• Use directory_tree and grep to scan for overlapping logic between components.
• Classify candidates by type:
  • Identical: Code that is exactly the same.
  • Similar: Code that serves the same purpose but with minor differences.
  • Coincidental: Code that looks similar but serves unrelated purposes.