forensic-coordination-analysis
Use when investigating merge conflicts, reducing communication overhead, detecting modules with high coordination complexity, or identifying files edited by many contributors and cross-team - reveals coordination bottlenecks and team communication issues
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- Updated: 2025-11-22
Download the latest version (v1.0.0) from this page.
SKILL.md
---
name: forensic-coordination-analysis
description: Use when investigating merge conflicts, reducing communication overhead, detecting modules with high coordination complexity, or identifying files edited by many contributors and cross-team - reveals coordination bottlenecks and team communication issues
---
# Forensic Coordination Analysis
## 🎯 When You Use This Skill
**State explicitly**: "Using forensic-coordination-analysis pattern"
**Then follow these steps**:
1. Count **unique contributors** per file (threshold: >9 = high risk)
2. Identify **cross-team hotspots** (files edited by multiple teams)
3. Detect **concurrent edit patterns** (multiple developers within 1 week)
4. Cite **research** when presenting findings (>9 contributors = 2-3x defect rate)
5. Suggest **integration** with knowledge-mapping and organizational-alignment at end
## Overview
Coordination analysis identifies files and modules requiring high levels of team coordination. Research shows coordination issues predict defects better than code complexity alone. This analysis reveals:
- **High-contributor files** - Too many people editing the same code
- **Cross-team coordination** - Files edited by multiple teams
- **Concurrent edits** - Overlapping work causing merge conflicts
- **Contributor churn** - High turnover indicating instability
- **Communication bottlenecks** - Where team coordination breaks down
**Core principle**: More contributors = more coordination overhead = higher defect risk. Files with >9 contributors have 2-3x higher bug rates.
## When to Use
- Investigating frequent merge conflicts in specific areas
- Reducing team communication overhead
- Planning team reorganizations (Conway's Law)
- Identifying files needing clear ownership
- Post-mortem analysis of coordination failures
- Quarterly health checks on team collaboration
- Before splitting teams or services
## When NOT to Use
- Insufficient git history (<6 months unreliable)
- Small team (<3 people, coordination not an issue)
- Greenfield projects (no patterns yet)
- When you need bug prediction (use hotspot analysis instead)
- For understanding code dependencies (use coupling analysis)
## Core Pattern
### ⚡ THE COORDINATION THRESHOLD (USE THIS)
**This is the research-backed contributor threshold - don't use arbitrary numbers**:
```
Coordination Risk = Unique Contributors (12 months)
Risk Thresholds:
- >9 contributors: CRITICAL (2-3x higher defect rate - Google Research)
- 6-9 contributors: HIGH (elevated coordination overhead)
- 3-5 contributors: MODERATE (manageable with communication)
- 1-2 contributors: LOW (minimal coordination needed)
Concurrent Edit Risk = Developers editing within 7-day window
Cross-Team Risk = Number of different teams contributing
- 3+ teams: HIGH (requires formal coordination)
- 2 teams: MODERATE (requires communication)
- 1 team: LOW (internal team coordination)
```
**Critical**: Always check for BOTH high contributors AND cross-team involvement for maximum risk.
### 📊 Research Benchmarks (CITE THESE)
**Always reference the research when presenting coordination findings**:
| Finding | Impact | Source | When to Cite |
|---------|--------|--------|--------------|
| High contributors | **2-3x** higher defect rate | Google Research | "Research shows >9 contributors correlates with 2-3x defect rate (Google)" |
| Cross-team changes | **40-60%** slower velocity | Microsoft DevOps | "Cross-team coordination reduces velocity by 40-60% (Microsoft)" |
| Contributor churn | **35-50%** higher bugs | Software Engineering Studies | "High contributor turnover increases bugs by 35-50%" |
**Always cite the source** when presenting coordination hotspots to justify process or organizational changes.
## Quick Reference
### Essential Git Commands
| Purpose | Command |
|---------|---------|
| **Count contributors** | `git log --since="12 months ago" --format="%an" -- FILE \| sort -u \| wc -l` |
| **List contributors** | `git log --since="12 months ago" --format="%an" -- FILE \| sort \| uniq -c \| sort -rn` |
| **Find high-contributor files** | `for f in $(git ls-files); do echo "$(git log --since="12 months ago" --format="%an" -- "$f" \| sort -u \| wc -l)\|$f"; done \| sort -rn \| head -20` |
| **Concurrent edits** | `git log --since="12 months ago" --format="%ad\|%an" --date=short -- FILE` |
### Risk Classification
| Contributors | Team Count | Concurrent Edits | Risk | Action |
|--------------|------------|------------------|------|--------|
| **>9** | 3+ | High | CRITICAL | Urgent: Assign ownership, refactor |
| **6-9** | 2-3 | Medium | HIGH | Establish ownership, improve docs |
| **3-5** | 1-2 | Low | MODERATE | Monitor, maintain communication |
| **1-2** | 1 | None | LOW | Normal maintenance |
### Coordination Complexity Score
| Score | Level | Meaning | Action |
|-------|-------|---------|--------|
| **9-10** | CRITICAL | Severe coordination overhead | Immediate restructuring |
| **7-8** | HIGH | Significant coordination needs | Establish protocols |
| **4-6** | MODERATE | Manageable coordination | Monitor trends |
| **0-3** | LOW | Minimal coordination | Normal state |
## Implementation
### Step 1: Identify High-Contributor Files
**For each file in codebase**:
```bash
# Find files with >9 contributors (last 12 months)
for file in $(git ls-files "*.js" "*.ts" "*.py" "*.go"); do
contributor_count=$(git log --since="12 months ago" --format="%an" -- "$file" | sort -u | wc -l)
if [ $contributor_count -gt 9 ]; then
echo "CRITICAL: $file - $contributor_count contributors"
elif [ $contributor_count -gt 6 ]; then
echo "HIGH: $file - $contributor_count contributors"
fi
done | sort -rn
```
**Priority**: Files with >9 contributors are CRITICAL (research-backed threshold).
### Step 2: Detect Cross-Team Coordination
**If team mapping available**:
```python
# Pseudocode for cross-team detection
# Map contributors to teams
team_mapping = {
"Alice": "Backend",
"Bob": "Frontend",
"Carol": "Platform",
# ...
}
def analyze_cross_team_coordination(file):
contributors = git_log_contributors(file, since="12 months ago")
teams = set()
for contributor in contributors:
team = team_mapping.get(contributor, "Unknown")
teams.add(team)
if len(teams) >= 3:
return "CRITICAL - Cross-team coordination bottleneck"
elif len(teams) == 2:
return "HIGH - Requires cross-team communication"
else:
return "LOW - Single team ownership"
```
**Why it matters**: Cross-team coordination requires formal communication, slowing velocity by 40-60%.
### Step 3: Find Concurrent Edit Patterns
**Identify merge conflict risk**:
```python
# Detect multiple developers editing within 7-day window
def find_concurrent_edits(file, window_days=7):
commits = git_log_with_dates(file, since="12 months ago")
# Group by week
weeks = defaultdict(list)
for commit in commits:
week_key = commit.date.strftime("%Y-W%U")
weeks[week_key].append(commit.author)
# Find weeks with multiple authors
concurrent_weeks = []
for week, authors in weeks.items():
unique_authors = set(authors)
if len(unique_authors) > 2:
concurrent_weeks.append({
'week': week,
'authors': unique_authors,
'commit_count': len(authors),
'risk': 'HIGH' if len(unique_authors) > 3 else 'MODERATE'
})
return concurrent_weeks
```
**Interpretation**: >3 developers in same week = high merge conflict risk.
### Step 4: Calculate Coordination Complexity Score
**Weighted formula**:
```python
def calculate_coordination_score(file_metrics):
# Weights based on impact
contributor_weight = 0.40 # 40% - primary factor
team_diversity_weight = 0.30 # 30% - cross-team overhead
concurrent_edits_weight = 0.20 # 20% - conflict risk
churn_weight = 0.10 # 10% - instability
# Normalize each factor to 0-10 scale
contributor_score = min(file_metrics.contributor_count / 10, 1.0) * 10
team_score = min(file_metrics.team_count / 4, 1.0) * 10
concurrent_score = min(file_metrics.concurrent_events / 5, 1.0) * 10
churn_score = file_metrics.contributor_churn_rate * 10
# Weighted sum
coordination_score = (
contributor_score * contributor_weight +
team_score * team_diversity_weight +
concurrent_score * concurrent_edits_weight +
churn_score * churn_weight
)
return coordination_score # 0-10 range
```
**Thresholds**: >9 = CRITICAL, 7-8 = HIGH, 4-6 = MODERATE, 0-3 = LOW
## Output Format
### 1. Executive Summary
```
Coordination Analysis (forensic-coordination-analysis pattern)
Files Analyzed: 487
Coordination Hotspots: 23 (5% of codebase)
Critical (>9 contributors): 5 files
High (6-9 contributors): 12 files
Cross-Team Hotspots: 8 files
Research shows >9 contributors correlates with 2-3x defect rate (Google).
```
### 2. Top Coordination Hotspots Table
```
Rank | File | Contributors | Teams | Concurrent | Churn | Risk
-----|----------------------|--------------|-------|------------|--------|----------
1 | core/config.js | 14 | 4 | 8 events | HIGH | CRITICAL
2 | api/v1/users.js | 11 | 3 | 5 events | MED | CRITICAL
3 | models/user.js | 9 | 2 | 12 events | HIGH | HIGH
4 | utils/validation.js | 8 | 3 | 3 events | LOW | HIGH
```
### 3. Detailed Hotspot Analysis
```
=== HOTSPOT #1: core/config.js ===
Coordination Metrics:
Contributors (12mo): 14 (CRITICAL - exceeds threshold of 9)
Teams Involved: 4 (Backend, Frontend, Platform, QA)
Total Commits: 67
Concurrent Edit Events: 8 (multiple developers within 1 week)
Contributor Churn: HIGH (7 new contributors in 6 months)
Coordination Score: 8.5/10 (HIGH)
Research: >9 contributors correlates with 2-3x defect rate (Google).
Top Contributors:
1. Alice (Backend): 25 commits (37%)
2. Bob (Frontend): 18 commits (27%)
3. Carol (Platform): 12 commits (18%)
4. +11 other contributors (18%)
Risk Factors:
⚠️ Too many contributors (14 vs threshold 9)
⚠️ Multiple teams editing same file
⚠️ High concurrent edit frequency
⚠️ No clear ownership (largest share: 37%)
Recent Concurrent Edit (Oct 2024):
- Oct 1: Alice added config key
- Oct 2: Bob refactored structure
- Oct 3: Carol added validation
→ Likely merge conflicts or coordination needed
RECOMMENDATIONS:
1. IMMEDIATE: Assign Backend team as primary owner
2. SHORT-TERM: Implement config schema validation
3. MEDIUM-TERM: Split into domain-specific modules
4. PROCESS: Require cross-team review for changes
5. COMMUNICATION: Create #config-changes channel
```
### 4. Cross-Team Coordination Matrix
```
Files with Multi-Team Involvement:
File | Team A | Team B | Team C | Velocity Impact
--------------------|-----------|----------|----------|------------------
api/users.js | Frontend | Backend | Mobile | -60% (Microsoft)
models/user.js | Backend | Platform | - | -40%
core/config.js | All teams | - | - | -60% (CRITICAL)
Research: Cross-team coordination reduces velocity by 40-60% (Microsoft).
```
## Common Mistakes
### Mistake 1: Not checking contributor threshold
**Problem**: Flagging all files with >3 contributors without using research-backed threshold.
```bash
# ❌ BAD: Arbitrary threshold
flag all files with >3 contributors
# ✅ GOOD: Research-backed threshold
flag files with >9 contributors (CRITICAL)
flag files with 6-9 contributors (HIGH)
```
**Fix**: **Always use >9 contributor threshold** from Google Research showing 2-3x defect correlation.
### Mistake 2: Ignoring cross-team coordination
**Problem**: Only counting total contributors, missing cross-team overhead.
```bash
# ❌ BAD: Just contributor count
if contributors > 9:
flag_as_hotspot()
# ✅ GOOD: Check cross-team involvement
if contributors > 9 OR team_count >= 3:
flag_as_coordination_hotspot()
check_velocity_impact() # 40-60% reduction
```
**Fix**: **Always flag cross-team files** (3+ teams) even if contributor count is moderate.
### Mistake 3: Not tracking concurrent edits
**Problem**: Missing merge conflict patterns from temporal analysis.
```bash
# ❌ BAD: Only historical count
count_total_contributors()
# ✅ GOOD: Detect concurrent patterns
find_weeks_with_multiple_authors()
flag_concurrent_edit_risk()
```
**Fix**: **Always analyze temporal patterns** - concurrent edits within 7 days = merge conflict risk.
### Mistake 4: Not suggesting ownership changes
**Problem**: Identifying hotspots without recommending who should own the code.
**Fix**: For every coordination hotspot, recommend:
- Primary team owner (based on largest contribution %)
- Cross-team review process if multi-team
- Refactoring to reduce coordination needs
## ⚡ After Running Coordination Analysis (DO THIS)
**Immediately suggest these next steps to the user**:
1. **Map ownership patterns** (use **forensic-knowledge-mapping**)
- High coordination + single owner leaving = disaster scenario
- Identify which hotspots are also knowledge silos
- Calculate truck factor for coordination hotspots
2. **Check organizational alignment** (use **forensic-organizational-alignment**)
- Coordination hotspots = Conway's Law violations
- Architecture may not match team structure
- Suggest team/architecture realignment
3. **Correlate with defect data** (if available)
- Validate 2-3x defect rate prediction
- Prioritize hotspots with actual bug history
- Use for executive justification
4. **Track coordination trends** (re-run monthly)
- Is coordination increasing or decreasing?
- Are process changes working?
- Early warning system for emerging hotspots
### Example: Complete Coordination Analysis Workflow
```
"Using forensic-coordination-analysis pattern, I analyzed 487 files.
COORDINATION HOTSPOTS FOUND:
CRITICAL: core/config.js
Contributors: 14 (exceeds threshold of 9)
Teams: 4 (Backend, Frontend, Platform, QA)
Concurrent Edits: 8 events in 12 months
Coordination Score: 8.5/10
Research shows >9 contributors correlates with 2-3x defect rate (Google).
Cross-Team Impact: 4 teams editing = 60% velocity reduction (Microsoft).
RECOMMENDATIONS:
1. Assign Backend team as primary owner (currently 37% Alice)
2. Establish cross-team review process
3. Split into domain-specific config modules
NEXT STEPS:
1. Map ownership (forensic-knowledge-mapping) - Is Alice the only expert?
2. Check team alignment (forensic-organizational-alignment) - Conway's Law violation?
3. Correlate with bugs - Validate 2-3x defect prediction
4. Track monthly - Set up coordination monitoring
Would you like me to proceed with the ownership mapping?"
```
**Always provide this integration guidance** - coordination issues often indicate deeper organizational or architectural problems.
## Advanced Patterns
### Contributor Churn Analysis
**Track stability over time**:
```
File: legacy/payment.js
Q1 2024: Alice, Bob (stable)
Q2 2024: Carol, Dave (Alice/Bob left) ← CHURN EVENT
Q3 2024: Eve, Frank (Carol left) ← INSTABILITY
Q4 2024: Grace, Henry (Dave left) ← CRITICAL
Pattern: High turnover, no stable ownership
Impact: 35-50% higher bugs (research)
Recommendation: Establish stable ownership or deprecate
```
### Coordination + Hotspot Intersection
**Most critical combination**:
```
CRITICAL INTERSECTION:
core/config.js:
- Coordination: 14 contributors (CRITICAL)
- Hotspot: 67 commits, high complexity
- Cross-team: 4 teams involved
Combined Risk: EXTREME
- 2-3x defects from coordination (Google)
- 4-9x defects from hotspot (Microsoft)
- Estimated: 8-27x normal defect rate
URGENT ACTION REQUIRED
```
### Team Handoff Patterns
**Detect when teams stop/start editing**:
```
File: api/v1/users.js
Jan-Jun: Backend team (35 commits)
Jul-Dec: Frontend team took over (28 commits)
Pattern: Team handoff occurred (July)
Risk: Knowledge transfer gap
Recommendation: Ensure handoff documentation
```
## Research Background
**Key studies**:
1. **Google Research** (2011): Organizational metrics as defect predictors
- >9 contributors = 2-3x higher defect rate
- More predictive than code complexity
- Recommendation: Use 9 as critical threshold
2. **Microsoft DevOps Research** (2016): Cross-team coordination cost
- 40-60% slower velocity with cross-team changes
- Formal communication overhead
- Recommendation: Minimize cross-team dependencies
3. **Herbsleb & Mockus** (2003): Conway's Law empirical validation
- Architecture mirrors organization structure
- Coordination issues = architectural misalignment
- Recommendation: Align teams with module boundaries
4. **Nagappan et al** (2008): Organizational complexity metrics
- Number of developers > code complexity for defect prediction
- Contributor churn increases bugs 35-50%
- Recommendation: Track organizational metrics alongside code metrics
**Why coordination matters more than code**: Social factors (communication, coordination) predict bugs better than technical factors (complexity, LOC).
## Integration with Other Techniques
**Combine coordination analysis with**:
- **forensic-knowledge-mapping**: Coordination + single owner = critical knowledge silo
- **forensic-organizational-alignment**: Coordination hotspots reveal Conway's Law violations
- **forensic-hotspot-finder**: Coordination + change frequency = highest defect risk
- **forensic-refactoring-roi**: Coordination overhead = quantifiable velocity cost
**Why**: Coordination issues are organizational problems, not just technical problems. Integration reveals whether to fix with process, architecture, or team changes.