> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Succession Planning — Integration

> Version: 1.0.0 Last Updated: 2026-03-20 Spec: HR-16 Succession Planning Constitution Reference: Section 1.2 (Core Independence), Section 1.3 (Integration Patte…

**Version:** 1.0.0\
**Last Updated:** 2026-03-20\
**Spec:** [HR-16 Succession Planning](../../../specs/hr/specs/HR-16-succession-planning.md)\
**Constitution Reference:** Section 1.2 (Core Independence), Section 1.3 (Integration Patterns)

***

## Overview

HR-16 manages succession planning, talent pipelines, and readiness assessments. It integrates with HR-10 (Performance) and HR-13 (Skills Matrix) to calculate readiness scores for potential successors.

***

## Integration Points

### Platform Foundation (PF) Dependencies

**Required PF Features:**

* **PF-12 (Reports)**: Succession planning reports, talent pipeline analytics
* **PF-10 (Notifications)**: Succession plan updates, readiness alerts

### Consumer Core Dependencies (Downstream)

**Internal HR Features:**

* **HR-01 (Employee Directory)**: Employee context
* **HR-10 (Performance)**: Performance ratings for talent identification
* **HR-13 (Skills Matrix)**: Skill proficiency levels for readiness assessment

***

## Integration Pattern: HR-13 Skills Integration

**Tables Used:**

* `hr_employee_skills` - Employee skill inventory with proficiency levels
* `hr_position_skill_requirements` - Position skill requirements

**Integration Pattern:**

```typescript theme={null}
// In src/cores/hr/succession/utils/readinessScore.ts

import { supabase } from '@/integrations/supabase/client';

/**
 * Calculate skills score for readiness assessment.
 * Integrates with HR-13 Skills Matrix data.
 */
async function calculateSkillsScore(
  employeeId: string,
  positionId: string,
  organizationId: string
): Promise<number> {
  // Get position requirements from HR-13
  const { data: requirements } = await supabase
    .from('hr_position_skill_requirements')
    .select('skill_id, minimum_proficiency')
    .eq('position_id', positionId)
    .eq('organization_id', organizationId);

  // Get employee skills from HR-13
  const { data: skills } = await supabase
    .from('hr_employee_skills')
    .select('skill_id, proficiency_level, verification_status')
    .eq('employee_id', employeeId)
    .eq('organization_id', organizationId);

  // Calculate match score
  return calculateSkillMatchScore(requirements ?? [], skills ?? []);
}
```

### Readiness Score Calculation Algorithm

**Reference:** This algorithm is used in T12 (Readiness Score Calculation).

```typescript theme={null}
// Proficiency level numeric mapping
const PROFICIENCY_SCORE_MAP: Record<string, number> = {
  'expert': 100,
  'advanced': 75,
  'intermediate': 50,
  'beginner': 25,
  'none': 0,
};

// Performance rating numeric mapping
const PERFORMANCE_SCORE_MAP: Record<string, number> = {
  'exceeds_expectations': 100,
  'meets_expectations': 75,
  'below_expectations': 25,
  'not_rated': 0,
};

/**
 * Calculate combined readiness score (0-100).
 *
 * @param performanceRating - Latest performance rating from HR-10
 * @param employeeSkills - Employee skill proficiency levels from HR-13
 * @param positionRequirements - Target position skill requirements from HR-13
 * @param performanceWeight - Weight for performance (from hr_module_settings)
 * @param skillsWeight - Weight for skills (from hr_module_settings)
 */
function calculateReadinessScore(
  performanceRating: string | null,
  employeeSkills: Array<{ skill_id: string; proficiency_level: string }>,
  positionRequirements: Array<{ skill_id: string; minimum_proficiency: string }>,
  performanceWeight: number = 50,
  skillsWeight: number = 50
): number {
  // Calculate performance score
  const performanceScore = PERFORMANCE_SCORE_MAP[performanceRating ?? 'not_rated'] ?? 0;
  
  // Calculate skills score (average of matched skill proficiencies)
  let skillsScore = 0;
  if (positionRequirements.length > 0 && employeeSkills.length > 0) {
    const skillMap = new Map(employeeSkills.map(s => [s.skill_id, s.proficiency_level]));
    let totalScore = 0;
    let matchedCount = 0;
    
    for (const req of positionRequirements) {
      const employeeProficiency = skillMap.get(req.skill_id);
      if (employeeProficiency) {
        totalScore += PROFICIENCY_SCORE_MAP[employeeProficiency] ?? 0;
        matchedCount++;
      }
    }
    
    skillsScore = matchedCount > 0 ? totalScore / matchedCount : 0;
  }
  
  // Weighted combination
  return (performanceScore * performanceWeight + skillsScore * skillsWeight) / 100;
}
```

***

## Platform Integration Layer Usage

**Consumes:**

* **PF-12 (Reports)**: Succession planning reports, talent pipeline analytics via `@/platform/reports`
* **PF-10 (Notifications)**: Succession plan updates, readiness alerts via `@/platform/notifications`

***

## Security Considerations

### Multi-Tenancy

* ✅ **RLS Enforcement**: All `hr_succession_*` tables filtered by `organization_id` via RLS policies

### Role-Based Access Control

* ✅ **HR Admin**: Full access to all succession planning data
* ✅ **Manager**: View succession plans for direct reports and own position
* ✅ **Staff**: View own succession plan only (if permitted)

### Data Protection

* ✅ **PII Handling**: Succession planning data may contain sensitive employee information; access controlled via RLS
* ✅ **Audit Trail**: All succession plan changes logged via PF-04

***

## Testing Requirements

* [ ] Readiness score calculation algorithm works correctly
* [ ] HR-13 skills integration queries work correctly
* [ ] HR-10 performance rating integration works correctly
* [ ] RLS policies enforce org isolation on succession planning queries
* [ ] Platform integration layer usage works correctly

***

## References

* [HR-16 Spec](../../../specs/hr/specs/HR-16-succession-planning.md)
* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)