Review

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha c439dc5935b0 · 14 Oct 2026Report an issue or request a re-scan

• Publishervladikk GitHub userOwner of the repository this skill is read from
• Source foldervladikk/modularity/skills/reviewThe exact folder we audited
• LicenceNOASSERTIONAs the repository states it
• Commit pinned for this verdictc439dc5935b0A new audit runs when the source changes
• Repository statusNot archivedLast push 44 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its 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…

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

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/vladikk/modularity
git -C modularity checkout c439dc5935b0

Works in

1. 2026-10-14
   ✓SAFE B 89 / 100

   first audit · source c439dc5935b0

Questions about Review

• github.com/vladikk/modularity/tree/main/skills/review — the audited source at commit c439dc5935b0 and every finding aboveObserved · 14 Oct 2026

Spotted something wrong? Report a correction · Methodology