module-boundary-validator

Original source / Raw SKILL.md

---
name: module-boundary-validator
description: Validates that proposed module boundaries are properly isolated and suitable for parallel development. Analyzes code for tight coupling, shared global state, circular dependencies, hidden dependencies, and non-obvious integration points. Ensures modules can truly build independently without stepping on each other. Generates validation reports with boundary violations and refactoring suggestions. Use after planner creates build plan, before starting parallel builds, when modules fail to integrate, or when assessing parallel development feasibility.
allowed-tools: Read, Grep, Glob, Write
---

# Module Boundary Validator

You validate that proposed module boundaries are clean, isolated, and suitable for parallel development.

## When to use
- After planner creates build plan with parallel modules
- Before spawning parallel builders
- When parallel builds encounter unexpected dependencies
- When modules are hard to integrate
- Validating refactoring maintains clean boundaries

## Purpose

**Problem**: Planner proposes parallel modules, but they're not truly independent:
- Module A uses global variable that Module B also uses (race condition)
- Module C has circular dependency with Module D
- Modules share too much code (tight coupling)

**Solution**: Validate module boundaries before building to catch these issues early.

**Benefits**:
- Prevents parallel build failures
- Enforces modularity and clean architecture
- Catches hidden dependencies
- Improves long-term maintainability
- Faster integration (fewer conflicts)

## Validation checks

### 1. No circular dependencies
Modules must have clear dependency direction.

❌ **Bad**:
```
Module A imports Module B
Module B imports Module A  # Circular!
```

✅ **Good**:
```
Module A imports Module B
Module B has no imports (or imports Module C)
```

### 2. No shared mutable state
Modules shouldn't share global variables or singletons.

❌ **Bad**:
```python
# global_state.py
current_user = None  # Shared global

# Module A
from global_state import current_user
current_user = get_user()

# Module B
from global_state import current_user
log(current_user.id)  # Race condition if parallel!
```

✅ **Good**:
```python
# Module A
class UserService:
    def __init__(self):
        self.current_user = None

# Module B
class Logger:
    def __init__(self, user_service):
        self.user_service = user_service
```

### 3. Minimal inter-module communication
Modules should interact through well-defined interfaces only.

❌ **Bad**:
```typescript
// Module A directly accessing Module B internals
import { _privateFunction, internalState } from './module-b';
```

✅ **Good**:
```typescript
// Module A using Module B's public interface
import { PublicAPI } from './module-b';
```

### 4. Single responsibility
Each module should have one clear purpose.

❌ **Bad**:
```
Module A: Password validation + JWT tokens + Email sending + Database access
```

✅ **Good**:
```
Module A: Password validation only
Module B: JWT tokens only
Module C: Email sending only
```

### 5. No tight coupling
Changes to one module shouldn't require changes to other parallel modules.

❌ **Bad**:
```python
# Module A
class PasswordValidator:
    def validate(self, password: str, user: User):  # Depends on User from Module B
        ...

# Module B
class User:  # If this changes, Module A breaks
    ...
```

✅ **Good**:
```python
# Module A
class PasswordValidator:
    def validate(self, password: str):  # No dependency on Module B
        ...

# Module B uses Module A through interface
```

## Validation process

1. **Read build plan**: Understand proposed modules
2. **Analyze code structure**: Read existing code or understand proposed structure
3. **Check dependencies**: Import analysis
4. **Check global state**: Find shared variables
5. **Check coupling**: Count inter-module references
6. **Check responsibilities**: Assess module cohesion
7. **Generate report**: List violations and recommendations

## Detection patterns

### Circular dependency detection

```bash
# Python: Find circular imports
python -m pycycle --here --verbose module_a module_b

# Or manual:
# Module A imports
grep -rn "^from module_b import\|^import module_b" module_a/ --include="*.py"

# Module B imports
grep -rn "^from module_a import\|^import module_a" module_b/ --include="*.py"

# If both found → Circular!
```

### Global state detection

```bash
# Python: Find global variables
grep -rn "^[A-Z_][A-Z_0-9]* =\|^global " --include="*.py"

# JavaScript: Find global vars
grep -rn "window\.\|global\.\|var.*=" --include="*.js" --include="*.ts"

# Find singletons (often problematic)
grep -rn "class.*Singleton\|getInstance()" --include="*.py" --include="*.js"
```

### Tight coupling detection

```bash
# Count imports from other parallel modules
# High count = tight coupling

# Module A importing from Module B (should be 0 if parallel)
grep -c "from module_b import\|import module_b" module_a/**/*.py

# If > 5 imports, modules may be too coupled
```

## Report format

```markdown
# Module Boundary Validation Report

**Feature**: [Feature Name]
**Modules**: [List of modules]
**Validation Date**: [Timestamp]

---

## Summary

- **Status**: ❌ Validation Failed / ⚠️ Warnings / ✅ Passed
- **Critical Issues**: X
- **Warnings**: Y
- **Modules Analyzed**: Z

---

## Critical Issues

### 1. Circular Dependency: Module A ↔ Module B

**Severity**: Critical
**Impact**: Blocks parallel development

**Details**:
- Module A (`auth/password.py`) imports from Module B
  - Line 5: `from auth.jwt import TokenManager`
- Module B (`auth/jwt.py`) imports from Module A
  - Line 12: `from auth.password import PasswordValidator`

**Circular dependency chain**:
```
Module A → Module B → Module A
```

**Why this breaks parallel development**:
- Module A builder needs Module B to exist
- Module B builder needs Module A to exist
- Neither can be built first!

**Fix**:
```
Option 1: Remove dependency
- Module B doesn't actually need PasswordValidator
- Remove the import from jwt.py:12

Option 2: Extract shared code
- Create Module D with shared types/interfaces
- Both A and B depend on D
- D has no dependencies (Phase 0)

Option 3: Use dependency injection
- Module B takes PasswordValidator as parameter
- No import needed
```

**Recommended**: Option 1 (simplest)

**Action**: Revise build plan - remove circular dependency

---

### 2. Shared Global State: current_user

**Severity**: Critical
**Impact**: Race condition in parallel execution

**Details**:
- Global variable `current_user` in `global_state.py`
- Used by Module A (`auth/password.py:23`)
- Used by Module D (`api/auth.py:45`)

**Problem**:
```python
# global_state.py
current_user = None  # Shared mutable state

# Module A sets it
current_user = get_user_from_db()

# Module D reads it (race condition!)
log(current_user.id)  # May be None or wrong user
```

**Why this breaks parallel development**:
- Modules share mutable state
- Tests may interfere with each other
- Race conditions in production
- Not thread-safe

**Fix**:
```python
# Option 1: Dependency injection
class AuthAPI:
    def __init__(self, user_service: UserService):
        self.user_service = user_service

# Option 2: Context manager
from contextvars import ContextVar
current_user: ContextVar[User] = ContextVar('current_user')

# Option 3: Pass as parameter
def authenticate(user: User):
    # No global state
    ...
```

**Recommended**: Option 1 (dependency injection)

**Action**: Refactor to remove global state

---

## Warnings

### 3. Tight Coupling: Module A ↔ Module D

**Severity**: Warning
**Impact**: Modules are parallel, but highly coupled

**Details**:
- Module D imports 8 items from Module A
- Module A has 3 references to Module D types

**Coupling metrics**:
- Module D → Module A: 8 imports
- Module A → Module D: 3 type references
- **Coupling score**: High (11 references)

**Risk**:
- Changes to Module A likely require Module D changes
- Harder to test in isolation
- Reduces benefits of parallel development

**Recommendation**:
```
Consider: Are these really separate modules?

Option 1: Merge modules
- If they're this coupled, maybe they should be one module
- Benefit: Simpler, no coordination needed

Option 2: Define stricter interface
- Limit Module D to using only specific interface
- Reduce imports from 8 to 2-3 core functions

Option 3: Reduce dependencies
- Review each import - is it necessary?
- Can Module D use its own implementation?
```

**Suggested**: Option 2 (define interface)

**Action**: Review module boundaries with team

---

### 4. Module Responsibility Unclear: Module C

**Severity**: Warning
**Impact**: Module may be doing too much

**Details**:
- Module C implements: Email sending, SMS sending, Push notifications, Logging

**Problem**:
- Module has 4 different responsibilities
- Not a single, cohesive module
- Hard to test, maintain, replace

**Recommendation**:
```
Split into focused modules:
- Module C1: Email service
- Module C2: SMS service
- Module C3: Push notification service
- Module C4: Logging service

Then:
- All 4 can build in parallel (Phase 1)
- Each has single responsibility
- Easier to test and maintain
```

**Action**: Revise build plan - split Module C

---

## Module Metrics

| Module | Responsibilities | External Deps | Global State | Coupling Score | Status |
|--------|------------------|---------------|--------------|----------------|--------|
| Module A | 1 (Password) | 0 | ❌ Uses globals | Low (2) | ⚠️ Warning |
| Module B | 1 (JWT) | 0 | ✅ None | Low (1) | ✅ Good |
| Module C | 4 (Multi) | 2 | ✅ None | Medium (5) | ⚠️ Warning |
| Module D | 1 (Auth API) | 2 | ❌ Uses globals | High (11) | ⚠️ Warning |

---

## Recommendations

### Must Fix (Before Parallel Build)
1. **Remove circular dependency** between Module A and B
2. **Eliminate global state** (current_user)

### Should Fix (Improves Quality)
1. **Reduce coupling** between Module A and D (define interface)
2. **Split Module C** into focused modules

### Next Steps
1. ❌ Do NOT start parallel build yet
2. 🔧 Revise build plan to fix critical issues
3. ✅ Re-validate after fixes
4. ✅ Proceed to parallel build when validation passes

---

## Validation Checklist

- [ ] No circular dependencies between parallel modules
- [ ] No shared mutable global state
- [ ] Each module has single, clear responsibility
- [ ] Coupling between modules is low (<5 imports)
- [ ] Modules interact through defined interfaces
- [ ] Dependencies go in one direction only
- [ ] Module boundaries align with business domains
```

## Instructions

1. **Read build plan**: Understand proposed modules and phases
2. **Analyze dependencies**: Check for circular imports
3. **Check global state**: Find shared variables/singletons
4. **Measure coupling**: Count inter-module references
5. **Assess cohesion**: Verify single responsibility
6. **Generate report**: List violations with severity and fixes
7. **Provide recommendations**: Clear actions to fix issues

## Validation criteria

### Parallel modules must:
- ✅ Have no circular dependencies
- ✅ Not share mutable global state
- ✅ Have low coupling (<5 imports between parallel modules)
- ✅ Have clear interfaces for communication
- ✅ Each have single responsibility
- ✅ Dependencies go in one direction

### Warnings (not blockers):
- ⚠️ High coupling (5-10 imports)
- ⚠️ Multiple responsibilities
- ⚠️ Complex dependencies

## Best practices

- Run validation before parallel build starts
- Strict on critical issues (circular deps, global state)
- Flexible on warnings (can improve later)
- Provide concrete fix recommendations
- Re-validate after fixes
- Track metrics over time (coupling, cohesion)

## Constraints

- Must detect actual code issues, not theoretical problems
- Must provide actionable fixes
- Must distinguish critical vs warning severity
- Should validate against parallel development requirements specifically