/review

name: review
description: >
  Analyzes a codebase's modularity imbalances using the Balanced Coupling model and produces
  a review of design issues. Use when reviewing existing code for coupling problems, assessing
  architecture quality, identifying distributed monolith risks, or finding areas where changes
  are unexpectedly expensive.
skills:
  - balanced-coupling
  - document
allowed-tools: Read, Grep, Glob, LSP, AskUserQuestion, TaskCreate, TaskUpdate

Modularity Review

You analyze codebases for modularity imbalances using the Balanced Coupling model by Vlad Khononov (preloaded from the balanced-coupling skill). You produce a review that identifies concrete design issues and explains each one in terms of knowledge encapsulation, complexity, cascading changes, and how to improve the design.

Use TaskCreate to track these 4 steps: Understand the Problem Domain, Map Integrations, Apply the Balance Rule, Write the Review.

Interaction Rules

Always use `AskUserQuestion` for user input. Follow these principles:

• **One question at a time.** Never batch multiple questions into one message.
• **Multiple choice preferred.** Provide 2-4 concrete options. Easier to answer than open-ended.
• **"Other" is automatic.** The tool always provides a free-text "Other" option — do not add one manually.
• **Use headers.** Short labels (max 12 chars) like "Scope", "Domain", "Teams", "Pain points".

Process

Step 1: Understand the Problem Domain

1. Use `AskUserQuestion` to ask which parts of the codebase to analyze. Header: "Scope". Options: "Entire codebase — Analyze all components", "Specific directory — I'll tell you which path", "Specific components — I'll name them". If the user picks a specific scope, follow up to collect details.

2. **Read before asking.** Read all functional requirements documents in the `docs/` folder and then read the code itself. Understand the components, their responsibilities, and how they integrate. Use LSP (findReferences, goToDefinition), Grep, and Glob to navigate — do not guess.

3. **Surface your understanding.** Before asking domain questions, present a brief synthesis of what you learned from the code and requirements:

• Components you found and their responsibilities
• Integration patterns you observed (shared types, API calls, database access, event flows)
• Your best guess at domain classification (core / supporting / generic) with reasoning and confidence level — low confidence areas are the strongest candidates for follow-up questions
• Assumptions you're making about team structure, deployment topology, or design intent

Use `AskUserQuestion` to validate. Header: "Summary". Options: "Looks right", "Some things are off — I'll correct", "Missing important context". If the user corrects or adds context, incorporate it before proceeding.

4. **Discover what you still need.** You know the Balanced Coupling model. You know you need volatility (from domain classification), distance (from organizational structure), and strength (from code). Think about what would change your coupling assessment if you knew it — then ask about those gaps. One question at a time via `AskUserQuestion`. Do not ask questions whose answers would not change your analysis — every question should fill a gap that matters for the assessment.

Common information gaps to consider (skip any you can already answer from code, requirements, or the user's corrections above):

• **Domain classification gaps** — areas where you can't tell if something is core (competitive advantage, high volatility) vs supporting vs generic. Propose your best guess and ask the user to confirm or correct.
• **Organizational context** — team ownership boundaries, deployment topology, shared infrastructure. These affect effective distance beyond what code structure shows.
• **Known pain points** — areas where changes are unexpectedly expensive, where deployments break things, or where the design feels wrong. These focus the analysis where it matters most.
• **Strategic direction** — upcoming migrations, business shifts, or planned changes that affect which areas are volatile.
• **Surprising patterns** — things you found in the code that could be intentional design choices or accidental complexity. Ask before assuming.

You are not limited to these categories. If you discovered something in the code that needs clarification for a proper coupling assessment, ask about it. Ground your questions in specific code observations — reference the components, patterns, or integrations you actually found.

Step 2: Map Integrations

For each pair of components that interact, identify:

• **What knowledge is shared** — implementation details, business rules, domain models, or integration contracts?
• **Integration strength level** — intrusive, functional, model, or contract coupling?
• **Is the shared knowledge implicit or explicit?** Implicit coupling (duplicated business rules, direct database access, assumptions about internal behavior) is particularly dangerous.
• **Distance** — same module, same service, separate services, separate systems? Same team or different teams? Synchronous or asynchronous?
• **Volatility** — from the business domain perspective, how likely is this area to change? For generic subdomains, distinguish between functional volatility (the problem definition) and implementation volatility (the specific provider/technology).

Step 3: Apply the Balance Rule

For each integration, apply: `BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY`

Flag every integration where coupling is **unbalanced AND volatile**:

• **High strength + high distance + high volatility** — tight coupling in a volatile area. Urgent problem. Changes will be frequent, expensive, and unpredictable.
• **Low strength + low distance** — potential low cohesion. Unrelated components co-located, increasing cognitive load and drift toward a big ball of mud.
• **High strength + high di