Skip to main content

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.

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 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:
// 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).
// 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