OpenParable
Skip to content
← Back to skills

Polylith Migrate Detect Circular Imports

Testing & Quality
polylith-migrate-detect-circular-imports

Polylith 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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 in polylith-migrate-analyze-imports). On the shimless path this phase is skipped — a pure namespace rename introduces no base↔shim cycles. See the polylith-migrate-orchestrator workflow.

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

  1. 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

2. Report circular imports

  1. Record all circular import chains in migration/${PROJECT}/circular_imports.md.
  2. 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

Output

  • A report file: migration/<project-name>/circular_imports.md listing all circular import chains

Verify

  1. Confirm that migration/<project-name>/circular_imports.md exists.
  2. 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 the polylith-migrate-orchestrator table (the single source of truth) — do not hardcode it.