forensic-organizational-alignment

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:

1. Map teams to modules (which teams work on which code)
2. Calculate alignment score (single-team modules = good, multi-team = misalignment)
3. Identify Conway's Law violations (architecture doesn't match org structure)
4. Cite research when presenting findings (Conway's Law empirically validated)
5. 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:

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

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

3. Calculate reorganization ROI (use forensic-refactoring-roi)

   • Misalignment = coordination cost
   • Refactoring to align = velocity improvement
   • Translate to business value (40-60% velocity gain)

4. 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:

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

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

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

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