architecture-review

name	architecture-review
description	Analyze Python module architecture using pyscn - class coupling (CBO), cohesion (LCOM), dependency cycles, and module communities. Use when user asks about architecture, module structure, coupling, circular dependencies, or which files to review or change together.

Python Architecture Review with pyscn

Run the pyscn CLI to understand module structure and coupling. No install needed: uvx pyscn@latest <command>.

Commands

User Request	Command
"Check class coupling"	uvx pyscn@latest analyze --select cbo <path>
"Find circular dependencies"	uvx pyscn@latest analyze --select deps <path>
"Check class cohesion"	uvx pyscn@latest analyze --select lcom <path>
"Which files should I review together?"	uvx pyscn@latest analyze --select communities --json <path>
"Map the module architecture"	uvx pyscn@latest analyze --select communities --json <path>

Useful flags: --min-cbo <n> (minimum CBO to report), --json (detailed report file). Report files are NOT written to stdout; they go to .pyscn/reports/ and the path is printed on completion.

Module Communities (context map for agents)

Module community detection is opt-in: run with --select communities --json and read the report file.

The JSON report includes community_analysis.community_context_map, a compact, deterministic map telling you which modules to inspect together:

• bundles[]: clusters of modules that change together. Each has modules, packages, risk_level, the cluster's bridge_modules, an optional suggested_review_scope (path prefix to focus a review on), and a one-line summary. Large bundles cap the module list with a ... +N more marker (module_count always holds the true total).
• bridge_modules[]: modules that couple two or more communities (module, the communities it connects, and a reason). Widen the review scope to include these when touching a bundle they connect.

Use the map to scope reviews and refactors: load all modules in a bundle together, and pull in connected bridge modules before changing cluster boundaries.

Interpreting Coupling Results

• High CBO classes depend on many others; changes ripple widely. Suggest interface extraction or dependency inversion.
• High LCOM4 classes bundle unrelated responsibilities; suggest splitting along the disconnected method groups.
• Dependency cycles are the highest-priority architectural issue; name the modules in each cycle and the weakest edge to break.

Always tie findings back to concrete modules and suggest a specific structural change.

MCP Alternative

If the pyscn-mcp MCP server is connected, you can use its tools instead of the CLI: check_coupling for CBO metrics, or analyze_code with analyses: ["deps"], ["lcom"], or ["communities"] (communities require output_mode: "full"; the full response includes the same community_context_map). Results are returned inline with no report files.