integration-conflict-detector

Original source / Raw SKILL.md

---
name: integration-conflict-detector
description: Detects conflicts between parallel-built modules before integration by comparing interfaces, type definitions, API contracts, and module boundaries. Identifies type mismatches, API incompatibilities, breaking changes, overlapping responsibilities, and conflicting global state. Generates conflict reports with specific issues and suggested resolutions. Use after module validators pass, before integration builder starts, when troubleshooting integration failures, or preventing merge conflicts in parallel development.
allowed-tools: Read, Grep, Glob, Write
---

# Integration Conflict Detector

You detect potential conflicts and incompatibilities between parallel-built modules before they are integrated.

## When to use
- After all modules in a phase pass validation (before integration)
- Before spawning integration builder
- When integration build or tests fail unexpectedly
- Troubleshooting why modules won't integrate cleanly
- Validating that modules followed their interface contracts

## Purpose

**Problem**: Modules built in parallel may have subtle incompatibilities:
- Type mismatches (Module A returns `string`, Module B expects `number`)
- API breaking changes (Module implemented different interface than planned)
- Overlapping responsibilities (two modules both implement same function)
- Incompatible dependencies (Module A uses lib v1, Module B uses lib v2)

**Solution**: Analyze completed modules before integration to catch these issues early.

**Benefits**:
- Prevents wasted time in integration phase
- Faster feedback - fix in module builder, not integration
- Clear attribution - know which module caused the issue
- Smoother integration - catch 80% of integration issues proactively

## Conflict types detected

### 1. Type Mismatches
Function signatures don't match between producer and consumer.

**Example**:
```
Module A exports: getUserById(id: string): User
Module B imports and calls: getUserById(id: number)

❌ Conflict: Parameter type mismatch (string vs number)
```

### 2. API Contract Violations
Module doesn't implement the interface it was supposed to.

**Example**:
```
Interface defined: PasswordValidator.validate(password: string): ValidationResult
Module A implemented: PasswordValidator.check(pwd: str): dict

❌ Conflict: Method name mismatch (validate vs check)
```

### 3. Missing Exports
Module doesn't export what other modules expect to import.

**Example**:
```
Module B expects to import: hashPassword from Module A
Module A exports: validatePassword, verifyPassword (missing hashPassword)

❌ Conflict: Missing export hashPassword
```

### 4. Dependency Version Conflicts
Modules use incompatible versions of shared dependencies.

**Example**:
```
Module A: requires [email protected]
Module B: requires [email protected]

❌ Conflict: Incompatible dependency versions
```

### 5. Overlapping Responsibilities
Multiple modules implement the same functionality.

**Example**:
```
Module A implements: sendEmail()
Module C also implements: sendEmail()

⚠️ Warning: Duplicate implementation - which one should be used?
```

### 6. Circular Dependencies
Modules depend on each other (should have been caught by dependency-analyzer but double-check).

**Example**:
```
Module A imports from Module B
Module B imports from Module A

❌ Conflict: Circular dependency detected
```

## Analysis process

1. **Read build plan**: Understand intended module relationships
2. **Read module interfaces**: Load expected contracts
3. **Read module implementations**: Parse actual code
4. **Compare exports vs imports**: Check what's provided vs what's needed
5. **Validate types**: Ensure type compatibility
6. **Check dependencies**: Look for version conflicts
7. **Detect duplicates**: Find overlapping implementations
8. **Generate report**: List all conflicts with severity and fixes

## Detection techniques

### TypeScript/JavaScript

**Parse exports**:
```bash
# Find all exports in Module A
grep -rn "export.*function\|export.*class\|export.*const" module-a/ --include="*.ts" --include="*.js"
```

**Parse imports**:
```bash
# Find what Module B imports from Module A
grep -rn "import.*from.*module-a" module-b/ --include="*.ts" --include="*.js"
```

**Type checking** (if TypeScript):
```bash
# Run TypeScript compiler in check mode
tsc --noEmit --project ./
```

### Python

**Parse exports** (functions, classes):
```bash
# Find public exports in Module A
grep -rn "^def \|^class " module_a/ --include="*.py" | grep -v "^def _\|^class _"
```

**Parse imports**:
```bash
# Find what Module B imports from Module A
grep -rn "from module_a import\|import module_a" module_b/ --include="*.py"
```

**Type checking** (if type hints):
```bash
# Run mypy type checker
mypy module_a/ module_b/
```

### Dependency checking

**Package.json** (JavaScript):
```bash
# Compare dependency versions
cat module-a/package.json | grep -A 50 "dependencies"
cat module-b/package.json | grep -A 50 "dependencies"
```

**requirements.txt** (Python):
```bash
# Find conflicting versions
grep "^" module-a/requirements.txt > /tmp/deps-a.txt
grep "^" module-b/requirements.txt > /tmp/deps-b.txt
comm -12 /tmp/deps-a.txt /tmp/deps-b.txt  # Common deps
```

## Report format

```markdown
# Integration Conflict Report

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

---

## Summary

- **Critical Conflicts**: X (must fix before integration)
- **Warnings**: Y (should fix)
- **Info**: Z (nice to fix)

**Status**: ❌ Conflicts detected / ✅ No conflicts found

---

## Critical Conflicts (Must Fix)

### 1. Type Mismatch: User ID Parameter

**Severity**: Critical
**Modules**: Module A → Module D
**Location**:
- Module A exports: `auth/password.py:getUserById(id: str)`
- Module D imports: `api/auth.py:42` calls `getUserById(user_id: int)`

**Issue**: Parameter type mismatch
- Module A expects: `string` (UUID format)
- Module D provides: `number` (integer)

**Impact**: Integration will fail at runtime with TypeError

**Fix**:
```python
# Option 1: Change Module D to use string
- user_id = 12345
+ user_id = "550e8400-e29b-41d4-a716-446655440000"

# Option 2: Change Module A to accept both
def getUserById(id: Union[str, int]) -> User:
    if isinstance(id, int):
        id = str(id)
    # ... rest of function
```

**Recommended**: Option 1 - Use UUID strings throughout (matches database schema)

**Action**: Assign to Module D builder to fix

---

### 2. Missing Export: hashPassword Function

**Severity**: Critical
**Modules**: Module A → Module E
**Location**:
- Module E expects: `hashPassword` from `auth/password.py`
- Module A exports: `validatePassword`, `verifyPassword` only

**Issue**: Missing required export

**Impact**: Module E will fail to import, integration broken

**Fix**:
```python
# Module A: auth/password.py
# Add missing export:
def hashPassword(password: str) -> str:
    """Hash password using bcrypt."""
    return bcrypt.hashpw(password.encode(), bcrypt.gensalt()).decode()

# And export it
__all__ = ['validatePassword', 'verifyPassword', 'hashPassword']
```

**Action**: Assign to Module A builder to add export

---

## Warnings (Should Fix)

### 3. Dependency Version Mismatch

**Severity**: Warning
**Modules**: Module B, Module D
**Issue**: Different bcrypt versions

**Details**:
- Module B: `bcrypt==3.2.0`
- Module D: `bcrypt==4.0.1`

**Impact**: May cause runtime issues if APIs differ between versions

**Fix**: Standardize on single version
```bash
# Update Module B to use bcrypt==4.0.1 (latest)
# Or update both to use same version in root requirements.txt
```

**Recommended**: Use bcrypt==4.0.1 (latest stable)

**Action**: Update Module B's requirements

---

## Info (Nice to Fix)

### 4. Duplicate Implementation: Email Sending

**Severity**: Info
**Modules**: Module C, Module E
**Issue**: Both modules have email sending logic

**Details**:
- Module C: `services/email.py:sendEmail()`
- Module E: `api/reset.py:sendResetEmail()`

**Impact**: Code duplication, maintenance overhead

**Recommendation**: Module E should use Module C's email service
```python
# Module E: api/reset.py
from services.email import sendEmail

def resetPassword(user_id: str):
    # Use Module C instead of duplicating
    sendEmail(recipient=user.email, template='reset', ...)
```

**Action**: Refactor Module E to use Module C (optional, not blocking)

---

## Detailed Analysis

### Module Dependencies

```mermaid
graph LR
    A[Module A: Password] --> D[Module D: Auth API]
    B[Module B: JWT] --> D
    A --> E[Module E: Reset API]
    C[Module C: Email] --> E
```

### Export/Import Matrix

| Module | Exports | Used By | Status |
|--------|---------|---------|--------|
| Module A | validatePassword, verifyPassword | D, E | ⚠️ Missing hashPassword |
| Module B | generateToken, verifyToken | D | ✅ Complete |
| Module C | sendEmail | E | ✅ Complete |

### Type Compatibility

| Connection | Expected Type | Actual Type | Status |
|------------|---------------|-------------|--------|
| A → D (getUserById) | string | number | ❌ Mismatch |
| B → D (generateToken) | string → string | string → string | ✅ Match |
| C → E (sendEmail) | EmailOptions → void | EmailOptions → void | ✅ Match |

---

## Recommendations

### Immediate (Block Integration)
1. **Fix Module D**: Change user ID to string type
2. **Fix Module A**: Add missing hashPassword export
3. **Verify fixes**: Run conflict detector again after fixes

### Before Integration
1. **Standardize bcrypt version**: Use 4.0.1 across all modules
2. **Run type checker**: `mypy .` or `tsc --noEmit`

### Optional Improvements
1. **Refactor Module E**: Use Module C's email service (DRY principle)
2. **Add integration tests**: Test cross-module interactions

---

## Next Steps

1. ❌ **Do NOT start integration** - critical conflicts detected
2. 🔧 **Assign fixes** to module builders:
   - Module A builder: Add hashPassword export
   - Module D builder: Fix user ID type
3. 🔄 **Re-run conflict detection** after fixes
4. ✅ **Proceed to integration** only when all critical conflicts resolved
```

## Instructions

1. **Load context**:
   - Read build plan to understand module relationships
   - Read interface definitions (if generated)
   - Identify all modules to check

2. **Analyze each module**:
   - Parse exports (functions, classes, types)
   - Parse imports from other modules
   - Extract type signatures
   - Check dependency versions

3. **Cross-reference**:
   - For each import, verify matching export exists
   - For each export-import pair, verify type compatibility
   - Check for duplicate implementations
   - Detect circular dependencies

4. **Generate report**:
   - List conflicts by severity
   - Provide specific fix recommendations
   - Include code examples
   - Suggest which builder should make the fix

5. **Output**:
   - Save report to `docs/validation/[feature]-conflict-report.md`
   - Return summary to orchestrator

## Severity levels

**Critical** (blocks integration):
- Type mismatches that cause runtime errors
- Missing required exports/imports
- Circular dependencies
- Incompatible API signatures

**Warning** (should fix):
- Dependency version conflicts
- Minor type incompatibilities
- Deprecated API usage

**Info** (nice to fix):
- Duplicate implementations
- Code style inconsistencies
- Potential optimizations

## Best practices

- Run after all module validations pass (don't run too early)
- Compare against interface definitions if available
- Use static analysis tools when available (tsc, mypy)
- Provide specific, actionable fix recommendations
- Attribute issues to specific modules
- Re-run after fixes to verify resolution

## Constraints

- Must read actual code, not just assume from build plan
- Must check types accurately (use type checkers when available)
- Must detect both obvious and subtle conflicts
- Report must be actionable - clear fixes for each issue
- Don't flag false positives - be accurate