Bus Factor Analysis
Descripcion
Detecta el Bus Factor (BF) de cada modulo de un proyecto analizando el historial git con el algoritmo CST(change-size-ratio):
- BF=1 → CRITICAL: un solo dev conoce el modulo
- BF=2 → HIGH: dos devs, riesgo elevado
- BF=3 → MEDIUM: tres devs, riesgo moderado
- BF>3 → LOW: riesgo bajo
Cuando usar
- Pre-sprint si hay devs de vacaciones o baja
- Tras la salida de cualquier miembro del equipo
- Mensualmente como revision de riesgo organizativo
- Cuando un nuevo dev se incorpora (para generar su plan de onboarding)
- Cuando se detecta siloizacion de conocimiento
Rutas criticas
- Motor Python:
scripts/bus-factor-scan.py - Orquestador:
scripts/bus-factor-scan.sh - Cupulas:
scripts/context-dome-generate.sh - Distribucion:
scripts/bus-factor-distribute.sh - Informe:
scripts/bus-factor-report.sh - Hook PostWrite:
.claude/hooks/bus-factor-warn.sh - Protocolo:
docs/rules/domain/bus-factor-protocol.md - DOMAIN:
.claude/skills/bus-factor-analysis/DOMAIN.md
Flujo de uso
# 1. Escanear proyecto
bash scripts/bus-factor-scan.sh --project <path>
# 2. Generar cupulas para modulos criticos
bash scripts/context-dome-generate.sh --project <path> --min-risk HIGH
# 3. Plan de distribucion para un dev
bash scripts/bus-factor-distribute.sh --project <path> --target <dev-email>
# 4. Informe ejecutivo
bash scripts/bus-factor-report.sh --project <path> --format markdown
Output esperado
JSON en output/bus-factor/<proyecto>-<timestamp>.json con estructura:
{
"project": "...",
"modules": [{"name": "...", "bus_factor": 1, "risk_level": "CRITICAL", ...}],
"summary": {"critical": 2, "high": 3, "medium": 1, "low": 5}
}
Configuracion
Variables de entorno (o .bus-factor.yml en raiz del proyecto):
| Variable | Default | Descripcion |
|---|---|---|
BF_OWNERSHIP_THRESHOLD |
0.50 |
Score minimo para ser owner |
BF_RISK_CRITICAL |
1 |
BF <= N es CRITICAL |
BF_RISK_HIGH |
2 |
BF <= N es HIGH |
BF_MIN_COMMITS |
5 |
Commits minimos por archivo |
BF_MODULE_DEPTH |
2 |
Profundidad de agrupacion |
BF_EXCLUDE_PATTERNS |
vendor/,node_modules/,*.lock |
Patrones a excluir |
BF_OUTPUT_DIR |
output/bus-factor/ |
Directorio de salida |
Limitaciones
- Git blame mide lineas, no comprension real
- Rebases y merges distorsionan el historial
- No detecta conocimiento organizativo (ver org-stakeholder-mapper)
- Human decides: el script solo genera findings, no actua
Integraciones
context-domeskill: genera CONTEXT_DOME.md con conocimiento tacitohuman-code-mapskill: usa el plan de distribucion para onboardingcodebase-memory-mcp: enriquece nodos File con bus_factor property