ImportShield: Circular Import Guard

AI coding agents often break modular applications by introducing silent circular dependencies or duplicate router registrations. These architectural flaws don't always throw clear errors. Instead, they cause the application to freeze at startup or hang indefinitely, leaving you with a traceback that points to the wrong file.

This skill acts as a static analysis guard for modular async codebases. It identifies the root causes of startup failures by mapping import chains and enforcing strict architectural boundaries.

What it does

• Detects import cycles by mapping the full dependency graph to find chains like A → B → C → A.
• Bans root imports to prevent leaf modules from directly importing the application, dispatcher, or bot instance.
• Identifies duplicate routers by scanning for routers mounted multiple times or registered on both a parent and the main dispatcher.
• Enforces interface isolation by ensuring route modules expose a single public interface and do not import from siblings.
• Provides actionable fixes including moving shared logic to service layers, inverting dependencies, or implementing late imports as a last resort.

How it works

1. Identify the root instance by locating the file that creates the FastAPI, Dispatcher, or Express object.
2. Map the import graph by listing imports for every module to detect directed cycles.
3. Scan for architectural violations like leaf modules reaching into the root or cross-module sibling imports.
4. Generate a diagnostic report that traces the exact cycle path and proposes a structural refactor to break it.

Frameworks & tools

Works with modular Python and JavaScript frameworks including aiogram, FastAPI, Flask, Express, and any project using a central dispatcher or router-based architecture.

Why this beats prompting it yourself

Generic prompts often fail to trace deep circular dependencies across multiple files and typically suggest "late imports" as a quick fix. This skill enforces structural integrity, identifying the architectural smell that caused the cycle rather than just patching the symptom.

Use cases

• Debugging an application that freezes on startup after handlers were moved or refactored.
• Auditing a large modular codebase to ensure clean separation between models, services, and handlers.
• Resolving "duplicate router" warnings or silent failures where routes appear twice in logs.

Known limitations

Requires full read access to the project directory, including all __init__.py files. It cannot detect cycles in single-file scripts or runtime errors unrelated to module loading.