forensic-organizational-alignment
Use when team reorganization planning, identifying coordination inefficiencies, validating Conway's Law, assessing team-architecture fit, or planning service splits - analyzes alignment between code module boundaries and team structures revealing organizational bottlenecks
When & Why to Use This Skill
The Forensic Organizational Alignment skill analyzes the relationship between your codebase architecture and team structure based on Conway's Law. By processing git history, it identifies coordination bottlenecks, orphaned modules, and architectural misalignments that hinder development velocity, providing data-driven insights for team reorganizations and service splits.
Use Cases
- Team Reorganization Planning: Use historical contribution data to identify natural team boundaries and plan structural changes that minimize coordination overhead.
- Microservices Extraction: Determine which code modules are ready to be extracted into independent services by identifying existing single-team ownership patterns.
- Velocity Bottleneck Diagnosis: Investigate slow cross-team delivery by identifying 'multi-team modules' where high contention leads to communication friction and merge conflicts.
- Conway's Law Validation: Audit whether your software architecture accurately reflects your organization's communication structure to ensure long-term system maintainability.
- Post-Merger Integration: Assess the alignment of newly joined teams with existing codebases to identify ownership gaps or overloaded teams during organizational transitions.
| name | forensic-organizational-alignment |
|---|---|
| description | Use when team reorganization planning, identifying coordination inefficiencies, validating Conway's Law, assessing team-architecture fit, or planning service splits - analyzes alignment between code module boundaries and team structures revealing organizational bottlenecks |
Forensic Organizational Alignment Analysis
🎯 When You Use This Skill
State explicitly: "Using forensic-organizational-alignment pattern"
Then follow these steps:
- Map teams to modules (which teams work on which code)
- Calculate alignment score (single-team modules = good, multi-team = misalignment)
- Identify Conway's Law violations (architecture doesn't match org structure)
- Cite research when presenting findings (Conway's Law empirically validated)
- Suggest integration with coordination-analysis and change-coupling at end
Overview
Organizational alignment analysis examines whether code architecture matches team structure. Based on Conway's Law: "Organizations design systems that mirror their communication structures."
This analysis reveals:
- Well-aligned modules - Single team ownership, clear boundaries
- Misaligned modules - Multiple teams editing same code (coordination overhead)
- Orphaned modules - No clear team ownership
- Overloaded teams - Spread across too many modules
- Conway's Law violations - Architecture and organization conflict
Core principle: Architecture should match team boundaries. Misalignment causes coordination overhead, slow velocity, and unclear ownership.
When to Use
- Planning team reorganizations or splits
- Before microservices extraction (which team owns which service?)
- Investigating slow cross-team velocity
- Diagnosing coordination overhead sources
- Quarterly organizational health checks
- After team changes (did architecture adapt?)
- Validating team autonomy
When NOT to Use
- Insufficient git history (<6 months unreliable)
- Small team (<3 people, structure irrelevant)
- No clear team boundaries (everyone works on everything)
- Early-stage projects (structure still forming)
- When you need defect prediction (use coordination-analysis instead)
Core Pattern
⚡ THE ALIGNMENT FORMULA (USE THIS)
This is Conway's Law-based alignment measurement - don't create custom metrics:
Module Alignment Score:
- Single team (>80% contribution): GOOD (10 points)
- Two teams (50-80% primary): MODERATE (5 points)
- Multi-team (<50% each): POOR (0 points)
- Orphaned (no team >50%): CRITICAL (-5 points)
Team Focus Score:
- Focused (1-2 modules owned): GOOD (5 points)
- Spread (3-5 modules): MODERATE (0 points)
- Overloaded (6+ modules): POOR (-5 points)
Cross-Team Coupling Penalty:
- Low (<10% cross-team commits): GOOD (5 points)
- Medium (10-30%): MODERATE (0 points)
- High (>30%): POOR (-5 points)
Overall Alignment = (sum of points / max possible) × 100
Thresholds: >75 = good alignment, 50-75 = moderate, <50 = poor (needs action)
Critical: Single-team modules with <10% cross-team involvement = ideal state.
📊 Research Benchmarks (CITE THESE)
Always reference Conway's Law research when presenting findings:
| Finding | Impact | Source | When to Cite |
|---|---|---|---|
| Conway's Law | Architecture mirrors org structure | Herbsleb & Mockus (2003) | "Conway's Law shows architecture mirrors communication structure (Herbsleb)" |
| Multi-team modules | 40-60% slower velocity | Microsoft DevOps | "Multi-team modules reduce velocity by 40-60% (Microsoft)" |
| Reverse Conway | Org structure can drive architecture | Inverse Conway | "You can reorganize teams to drive architectural change (Inverse Conway)" |
Always cite Conway's Law when recommending organizational or architectural changes.
Quick Reference
Essential Git Commands
| Purpose | Command |
|---|---|
| Contributors by module | git log --since="12 months ago" --format="%an" -- MODULE/ | sort | uniq -c | sort -rn |
| Cross-module commits | git log --since="12 months ago" --name-only --format="COMMIT:%H|%an" |
| Team inference (email) | git log --since="12 months ago" --format="%an|%ae" | sort -u |
| Contribution matrix | git log --since="12 months ago" --numstat --format="%H|%an" -- MODULE/ |
Alignment Classification
| Module State | Primary Team % | Secondary Teams | Alignment | Action |
|---|---|---|---|---|
| Single-team | >80% | None | GOOD | Maintain boundaries |
| Shared | 50-80% | 1 team | MODERATE | Clarify ownership |
| Multi-team | <50% each | 2+ teams | POOR | Refactor or reassign |
| Orphaned | <50% | Many | CRITICAL | Assign owner or deprecate |
Misalignment Patterns
| Pattern | Indicator | Risk | Fix |
|---|---|---|---|
| Multi-team module | >2 teams contribute significantly | HIGH | Assign primary owner, create interfaces |
| Cross-boundary coupling | High co-change across teams | HIGH | API contracts, versioning |
| Orphaned code | No team >50% ownership | CRITICAL | Assign ownership or delete |
| Overloaded team | Team owns 6+ modules | MEDIUM | Split team or consolidate modules |
Implementation
Step 1: Identify Team Structure
If not provided, infer from git data:
# Pseudocode for team inference
def infer_teams(contributors):
# Method 1: Email domains
teams_by_domain = defaultdict(list)
for name, email in contributors:
domain = email.split('@')[1]
teams_by_domain[domain].append(name)
# Method 2: Co-commit patterns (proxy for communication)
teams_by_cocommit = cluster_by_cocommit_frequency(contributors)
# Method 3: Module ownership patterns
teams_by_module = cluster_by_shared_modules(contributors)
# Combine methods for best inference
return merge_team_inferences([teams_by_domain, teams_by_cocommit, teams_by_module])
Ask user for validation: Inferred teams may be wrong - always confirm.
Step 2: Map Teams to Modules
Calculate contribution percentage:
def map_teams_to_modules(modules, contributors, team_mapping):
module_ownership = {}
for module in modules:
# Get all commits to this module
commits_by_team = defaultdict(int)
for commit in get_commits_to_module(module, since="12 months ago"):
author = commit.author
team = team_mapping.get(author, "Unknown")
commits_by_team[team] += 1
# Calculate percentages
total_commits = sum(commits_by_team.values())
ownership_pct = {
team: (count / total_commits * 100)
for team, count in commits_by_team.items()
}
# Find primary owner
primary_team = max(ownership_pct, key=ownership_pct.get)
primary_pct = ownership_pct[primary_team]
module_ownership[module] = {
'primary_team': primary_team,
'primary_pct': primary_pct,
'all_teams': ownership_pct
}
return module_ownership
Step 3: Calculate Alignment Score
Apply scoring formula:
def calculate_alignment_score(module_ownership, team_focus):
score = 0
max_score = 0
# Module alignment scoring
for module, ownership in module_ownership.items():
max_score += 10
primary_pct = ownership['primary_pct']
team_count = len([p for p in ownership['all_teams'].values() if p > 5])
if primary_pct > 80 and team_count == 1:
score += 10 # Single-team (ideal)
elif primary_pct > 50:
score += 5 # Shared but clear primary
elif primary_pct < 50:
score += 0 # Multi-team (poor)
# Orphaned modules
if primary_pct < 50 and team_count > 3:
score -= 5 # Orphaned (critical)
# Team focus scoring
for team, modules_owned in team_focus.items():
max_score += 5
if len(modules_owned) <= 2:
score += 5 # Focused (good)
elif len(modules_owned) <= 5:
score += 0 # Spread (moderate)
else:
score -= 5 # Overloaded (poor)
# Overall alignment percentage
alignment_pct = (score / max_score) * 100 if max_score > 0 else 0
return max(0, min(100, alignment_pct)) # Clamp to 0-100
Step 4: Identify Misalignments
Detect specific patterns:
def identify_misalignments(module_ownership, cross_team_coupling):
misalignments = []
for module, ownership in module_ownership.items():
primary_pct = ownership['primary_pct']
team_count = len(ownership['all_teams'])
# Pattern 1: Multi-team module
if team_count >= 3 and primary_pct < 60:
misalignments.append({
'type': 'MULTI_TEAM_MODULE',
'module': module,
'severity': 'HIGH',
'teams': ownership['all_teams'],
'recommendation': 'Assign primary owner, create interface layer'
})
# Pattern 2: Orphaned module
if primary_pct < 50:
misalignments.append({
'type': 'ORPHANED_MODULE',
'module': module,
'severity': 'CRITICAL',
'recommendation': 'Assign ownership or deprecate'
})
# Pattern 3: High cross-team coupling
if module in cross_team_coupling and cross_team_coupling[module] > 30:
misalignments.append({
'type': 'CROSS_BOUNDARY_COUPLING',
'module': module,
'severity': 'HIGH',
'recommendation': 'Create API contract, reduce coupling'
})
return misalignments
Output Format
1. Executive Summary
Organizational Alignment Analysis (forensic-organizational-alignment pattern)
Teams: 4 (Frontend, Backend, Platform, QA)
Modules: 12
Alignment Score: 68/100 (MODERATE)
Critical Misalignments: 2
Multi-Team Modules: 5
Conway's Law shows architecture mirrors communication structure (Herbsleb).
2. Team-Module Ownership Matrix
Team | Primary Modules | Secondary Modules | Focus Score
------------------|--------------------------|--------------------------|-------------
Frontend Team | frontend/, ui/ | api/ (15%) | GOOD (2)
Backend Team | backend/*, api/ | infrastructure/ (20%) | MODERATE (4)
Platform Team | infrastructure/, db/ | backend/ (25%) | GOOD (2)
QA Team | tests/ | (contributes to all) | FOCUSED (1)
3. Module Alignment Status
Module | Primary Team | Primary % | Other Teams | Status
---------------------|---------------|-----------|----------------------|----------
frontend/ | Frontend | 95% | - | ✅ GOOD
backend/auth/ | Backend | 75% | Platform (20%) | ⚠️ MODERATE
backend/api/ | Backend | 55% | Frontend (30%), QA | ❌ POOR
infrastructure/ | Platform | 70% | Backend (25%) | ⚠️ MODERATE
legacy/old-api/ | (multiple) | 35% | All teams | 🚨 ORPHANED
4. Detected Misalignments
CRITICAL MISALIGNMENT #1: Orphaned Module
Module: legacy/old-api/
Status: No clear ownership (highest contributor: 35%)
Teams: Backend (35%), Frontend (30%), Platform (20%), QA (15%)
Impact: Nobody maintains, unclear responsibility, technical debt accumulates
Conway's Law: Module structure doesn't reflect any team's communication pattern
RECOMMENDATION:
1. IMMEDIATE: Assign Backend team as owner (highest contribution)
2. SHORT-TERM: Document current state, freeze new features
3. MEDIUM-TERM: Plan migration or deprecation
HIGH MISALIGNMENT #2: Multi-Team Module
Module: backend/api/
Primary Team: Backend (55%)
Secondary Teams: Frontend (30%), QA (15%)
Impact: 40-60% slower velocity (Microsoft Research)
Issue: All teams editing API layer = coordination bottleneck
RECOMMENDATION:
1. Establish Backend team as sole owner
2. Create clear API contract (OpenAPI spec)
3. Cross-team changes go through PR review process
4. Consider API versioning strategy
5. Conway's Law Violations
VIOLATION: Monolithic Module, Distributed Teams
Module: core/
Contributing Teams: All 4 teams (no primary >40%)
Pattern: Everyone needs core utilities, no clear boundaries
Conway's Law Violation: Architecture (monolithic) conflicts with organization (4 teams)
RECOMMENDATION (choose one):
A) REFACTOR: Split core/ into team-aligned modules
- core-frontend/, core-backend/, etc.
- Teams maintain their own utilities
B) ORGANIZE: Create dedicated "Platform" ownership
- Assign Platform team as core/ owner
- Other teams submit PRs for changes
C) EXTRACT: Create shared library with versioning
- Extract to separate repo
- Semantic versioning, formal releases
Common Mistakes
Mistake 1: Not validating inferred teams
Problem: Auto-detecting teams from email/commits without user confirmation.
# ❌ BAD: Use inferred teams directly
teams = infer_teams_from_email_domains()
proceed_with_analysis(teams)
# ✅ GOOD: Validate with user
inferred_teams = infer_teams_from_email_domains()
print("Inferred teams:", inferred_teams)
confirmed_teams = ask_user_to_validate(inferred_teams)
proceed_with_analysis(confirmed_teams)
Fix: Always validate inferred teams - automated inference may group incorrectly.
Mistake 2: Treating all multi-team modules as bad
Problem: Flagging every module with >1 team without considering context.
# ❌ BAD: All multi-team = misalignment
if team_count > 1:
flag_as_misaligned()
# ✅ GOOD: Consider primary ownership and purpose
if team_count > 2 AND primary_pct < 60:
flag_as_misaligned()
# Shared modules (60-80% primary) may be acceptable
Fix: Moderate sharing is acceptable - focus on modules with <60% primary ownership or >3 teams.
Mistake 3: Not considering module purpose
Problem: Applying same standards to all modules regardless of their role.
Fix: Different standards for different module types:
- Domain modules (auth/, payments/): Should be single-team
- Infrastructure (db/, logging/): May legitimately be multi-team
- Tests: Expected to be edited by all teams
- Shared utilities: Consider extracting to library
Mistake 4: Ignoring Inverse Conway Maneuver
Problem: Only suggesting architectural changes, not considering organizational changes.
Fix: Conway's Law works both ways:
- Architecture → Organization: Refactor code to match teams
- Organization → Architecture: Reorganize teams to match desired architecture
- Always present both options and let user choose
⚡ After Running Alignment Analysis (DO THIS)
Immediately suggest these next steps to the user:
Check coordination overhead (use forensic-coordination-analysis)
- Misaligned modules likely have high contributor counts
- Validate that >9 contributors correlate with poor alignment
- Coordination + misalignment = severe velocity problem
Find cross-team couplings (use forensic-change-coupling)
- Multi-team modules may have high coupling patterns
- Coupling across team boundaries = architectural debt
- Prioritize decoupling efforts
Calculate reorganization ROI (use forensic-refactoring-roi)
- Misalignment = coordination cost
- Refactoring to align = velocity improvement
- Translate to business value (40-60% velocity gain)
Track alignment trends (re-run quarterly)
- Is alignment improving or degrading?
- Did team changes improve architecture fit?
- Early warning for emerging misalignments
Example: Complete Alignment Analysis Workflow
"Using forensic-organizational-alignment pattern, I analyzed team-module fit.
ALIGNMENT SCORE: 68/100 (MODERATE)
Teams: 4 (Frontend, Backend, Platform, QA)
Modules: 12 analyzed
CRITICAL MISALIGNMENT:
legacy/old-api/:
- Orphaned (no team >40% ownership)
- 4 teams editing (Backend 35%, Frontend 30%, Platform 20%, QA 15%)
- Conway's Law violation: No communication structure owns this
backend/api/:
- Multi-team (Backend 55%, Frontend 30%, QA 15%)
- Impact: 40-60% slower velocity (Microsoft Research)
RECOMMENDATIONS:
Option A (Architectural):
1. Assign clear owners (Backend for both modules)
2. Refactor to reduce cross-team coupling
3. Create API contracts for cross-team changes
Option B (Organizational):
1. Create dedicated API team
2. Deprecate legacy/old-api/
3. Realign teams around module boundaries
NEXT STEPS:
1. Check coordination (forensic-coordination-analysis) - Validate >9 contributors?
2. Find couplings (forensic-change-coupling) - Which files cross teams?
3. Calculate ROI (forensic-refactoring-roi) - Cost of misalignment?
4. Track quarterly - Monitor alignment trends
Would you like me to proceed with coordination analysis?"
Always provide this integration guidance - alignment issues connect to coordination overhead and architectural coupling.
Advanced Patterns
Inverse Conway Maneuver
Use organizational changes to drive architecture:
CURRENT STATE:
Teams: Monolithic (one team, all code)
Architecture: Monolithic (one codebase)
DESIRED STATE:
Architecture: Microservices (separate deployable units)
INVERSE CONWAY:
1. Split team into service-aligned teams FIRST
2. Assign each team a future service boundary
3. Teams will naturally refactor toward separation
4. Architecture follows organizational change
Result: Team structure drives architectural evolution
Alignment Over Time
Track evolution:
Quarterly Alignment Scores:
Q1 2024: 45/100 (POOR) - 3 teams, monolithic codebase
Q2 2024: 58/100 (MODERATE) - Started module boundaries
Q3 2024: 72/100 (GOOD) - Clear ownership established
Q4 2024: 68/100 (MODERATE) - New team added, realignment needed
Insight: Team changes require architectural adaptation
Action: Review module boundaries after team structure changes
Cross-Team Communication Network
Map actual vs desired communication:
Actual Communication (from co-commits):
Frontend ↔ Backend: 45 interactions (HIGH)
Backend ↔ Platform: 32 interactions (HIGH)
Frontend ↔ Platform: 8 interactions (LOW)
Module Coupling:
frontend/ ↔ backend/: Strong coupling
backend/ ↔ infrastructure/: Strong coupling
frontend/ ↔ infrastructure/: Weak coupling
VALIDATION: ✅ Conway's Law confirmed
Communication patterns match coupling patterns
Research Background
Key studies:
Herbsleb & Mockus (2003): Conway's Law empirical validation
- Architecture mirrors organizational communication structure
- Coordination distance predicts defects better than code complexity
- Recommendation: Align architecture with team boundaries
Microsoft DevOps Research (2016): Multi-team module impact
- 40-60% slower velocity for modules with >2 teams
- Clear ownership improves velocity and quality
- Recommendation: Minimize cross-team module editing
Inverse Conway Maneuver (ThoughtWorks, 2015): Organizational architecture
- Team structure can drive architectural change
- Reorganizing teams before refactoring accelerates change
- Recommendation: Consider both architectural AND organizational options
MacCormack et al (2012): Architectural coupling and team structure
- Misalignment correlates with technical debt accumulation
- Well-aligned organizations ship faster
- Recommendation: Regular alignment audits (quarterly)
Why alignment matters: Conway's Law is empirically validated - fighting it causes coordination overhead, slow velocity, and organizational friction.
Integration with Other Techniques
Combine alignment analysis with:
- forensic-coordination-analysis: Misalignment → high contributor counts → coordination overhead
- forensic-change-coupling: Cross-team couplings reveal alignment violations
- forensic-refactoring-roi: Misalignment cost = coordination overhead cost
- forensic-knowledge-mapping: Single-team modules should have clear ownership
Why: Organizational alignment affects all other forensic metrics - fixing alignment improves everything else.