Polylith Migrate Detect Circular Imports
Testing & Qualitypolylith-migrate-detect-circular-importsPolylith Migrate Detect Circular Imports is an Agent Skill for testing & quality published in the DavidVujic/python-polylith repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
[Internal sub-skill of `polylith-migrate-orchestrator`. Do not load directly — load `polylith-migrate-orchestrator` first, which drives all phases.] Detect and report circular imports introduced by the namespace migration.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/DavidVujic/python-polylith/blob/HEAD/.agents/skills/polylith/migrate-project/polylith-migrate-detect-circular-imports/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/polylith-migrate-detect-circular-imports, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Skill: polylith-migrate-detect-circular-imports
⛓ Conditional phase (4b). Runs only when
SHIM_STRATEGY=shim(chosen inpolylith-migrate-analyze-imports). On the shimless path this phase is skipped — a pure namespace rename introduces no base↔shim cycles. See thepolylith-migrate-orchestratorworkflow.
Goal
Detect and report circular imports introduced by the namespace migration, particularly between the new base location and the compatibility shim.
Inputs
- Project name (from
migration/<project-name>/state.md) - Original namespace (from
migration/<project-name>/state.md) - New namespace (from
migration/<project-name>/state.md) - Import updates report (from
migration/<project-name>/import_updates.md)
Steps
1. Analyze the import graph
- Manually inspect the import graph to identify circular dependencies:
- Between the new base location (
bases/${TARGET_TOP_NS}/${INITIAL_BASE_NAME}/) and the compatibility shim (projects/${PROJECT}/${ORIG_TOP_NS}/__init__.py) - Within the new base location itself
- Between the new base location (
2. Report circular imports
- Record all circular import chains in
migration/${PROJECT}/circular_imports.md. - For each circular import chain, document:
- The files involved (use full paths like
bases/${TARGET_TOP_NS}/${INITIAL_BASE_NAME}/module.py) - The import statements causing the circularity
- Suggested resolution steps
- The files involved (use full paths like
Output
- A report file:
migration/<project-name>/circular_imports.mdlisting all circular import chains
Verify
- Confirm that
migration/<project-name>/circular_imports.mdexists. - Verify that the report includes:
- A list of circular import chains
- The files involved in each chain
- Suggested resolution steps
Commit
git add migration/${PROJECT}/circular_imports.md
git commit -m "migrate(${PROJECT}): phase <N> — detect-circular-imports"
<N>is this phase's number from thepolylith-migrate-orchestratortable (the single source of truth) — do not hardcode it.