@forwardimpact/model 0.4.0 → 0.7.0

package/{lib → src}/interview.js

@@ -12,20 +12,46 @@ import {
   Capability,
 } from "@forwardimpact/schema/levels";
 
+import {
+  WEIGHT_SKILL_TYPE,
+  WEIGHT_CAPABILITY_BOOST,
+  WEIGHT_BEHAVIOUR_BASE,
+  WEIGHT_BEHAVIOUR_MATURITY,
+  WEIGHT_SKILL_LEVEL,
+  WEIGHT_BELOW_LEVEL_PENALTY,
+  RATIO_SKILL_BEHAVIOUR,
+} from "./policies/thresholds.js";
+
 /**
  * Default question time estimate if not specified
  */
 const DEFAULT_QUESTION_MINUTES = 5;
 
+/**
+ * Default decomposition question time estimate
+ */
+const DEFAULT_DECOMPOSITION_MINUTES = 15;
+
+/**
+ * Default stakeholder simulation question time estimate
+ */
+const DEFAULT_SIMULATION_MINUTES = 20;
+
 /**
  * Get questions from the question bank for a specific skill and level
  * @param {import('./levels.js').QuestionBank} questionBank - The question bank
  * @param {string} skillId - The skill ID
  * @param {string} level - The skill level
+ * @param {string} [roleType='professionalQuestions'] - Role type ('professionalQuestions' or 'managementQuestions')
  * @returns {import('./levels.js').Question[]} Array of questions
  */
-function getSkillQuestions(questionBank, skillId, level) {
-  return questionBank.skillLevels?.[skillId]?.[level] || [];
+function getSkillQuestions(
+  questionBank,
+  skillId,
+  level,
+  roleType = "professionalQuestions",
+) {
+  return questionBank.skillLevels?.[skillId]?.[roleType]?.[level] || [];
 }
 
 /**
@@ -33,10 +59,64 @@ function getSkillQuestions(questionBank, skillId, level) {
  * @param {import('./levels.js').QuestionBank} questionBank - The question bank
  * @param {string} behaviourId - The behaviour ID
  * @param {string} maturity - The maturity level
+ * @param {string} [roleType='professionalQuestions'] - Role type ('professionalQuestions' or 'managementQuestions')
  * @returns {import('./levels.js').Question[]} Array of questions
  */
-function getBehaviourQuestions(questionBank, behaviourId, maturity) {
-  return questionBank.behaviourMaturities?.[behaviourId]?.[maturity] || [];
+function getBehaviourQuestions(
+  questionBank,
+  behaviourId,
+  maturity,
+  roleType = "professionalQuestions",
+) {
+  return (
+    questionBank.behaviourMaturities?.[behaviourId]?.[roleType]?.[maturity] ||
+    []
+  );
+}
+
+/**
+ * Get decomposition questions from the question bank for a specific capability and level
+ * @param {import('./levels.js').QuestionBank} questionBank - The question bank
+ * @param {string} capabilityId - The capability ID
+ * @param {string} level - The skill level (capabilities use same levels as skills)
+ * @param {string} [roleType='professionalQuestions'] - Role type ('professionalQuestions' or 'managementQuestions')
+ * @returns {import('./levels.js').Question[]} Array of questions
+ */
+function getCapabilityQuestions(
+  questionBank,
+  capabilityId,
+  level,
+  roleType = "professionalQuestions",
+) {
+  return (
+    questionBank.capabilityLevels?.[capabilityId]?.[roleType]?.[level] || []
+  );
+}
+
+/**
+ * Derive capability levels from a job's skill matrix
+ * Uses the maximum skill level in each capability.
+ * @param {import('./levels.js').JobDefinition} job - The job definition
+ * @returns {Map<string, {capabilityId: string, level: string, levelIndex: number}>} Map of capability to level info
+ */
+function deriveCapabilityLevels(job) {
+  const capabilityLevels = new Map();
+
+  for (const skill of job.skillMatrix) {
+    const capabilityId = skill.capability;
+    const levelIndex = getSkillLevelIndex(skill.level);
+
+    const existing = capabilityLevels.get(capabilityId);
+    if (!existing || levelIndex > existing.levelIndex) {
+      capabilityLevels.set(capabilityId, {
+        capabilityId,
+        level: skill.level,
+        levelIndex,
+      });
+    }
+  }
+
+  return capabilityLevels;
 }
 
 /**
@@ -48,31 +128,25 @@ function getBehaviourQuestions(questionBank, behaviourId, maturity) {
 function calculateSkillPriority(skill, includeBelowLevel = false) {
   let priority = 0;
 
-  // Primary skills are highest priority
-  if (skill.type === "primary") {
-    priority += 30;
-  } else if (skill.type === "secondary") {
-    priority += 20;
-  } else {
-    priority += 10;
-  }
+  // Skill type priority from policy weights
+  priority += WEIGHT_SKILL_TYPE[skill.type] || WEIGHT_SKILL_TYPE.broad;
 
   // AI skills get a boost for "AI-era focus"
   if (skill.capability === Capability.AI) {
-    priority += 15;
+    priority += WEIGHT_CAPABILITY_BOOST.ai;
   }
 
   // Delivery skills are core technical skills
   if (skill.capability === Capability.DELIVERY) {
-    priority += 5;
+    priority += WEIGHT_CAPABILITY_BOOST.delivery;
   }
 
   // Higher skill level = higher priority
-  priority += getSkillLevelIndex(skill.level) * 2;
+  priority += getSkillLevelIndex(skill.level) * WEIGHT_SKILL_LEVEL;
 
   // Below-level questions have lower priority
   if (includeBelowLevel) {
-    priority -= 5;
+    priority += WEIGHT_BELOW_LEVEL_PENALTY;
   }
 
   return priority;
@@ -84,10 +158,35 @@ function calculateSkillPriority(skill, includeBelowLevel = false) {
  * @returns {number} Priority score (higher = more important)
  */
 function calculateBehaviourPriority(behaviour) {
-  let priority = 15;
+  let priority = WEIGHT_BEHAVIOUR_BASE;
 
   // Higher maturity level = higher priority
-  priority += getBehaviourMaturityIndex(behaviour.maturity) * 3;
+  priority +=
+    getBehaviourMaturityIndex(behaviour.maturity) * WEIGHT_BEHAVIOUR_MATURITY;
+
+  return priority;
+}
+
+/**
+ * Calculate priority for a capability decomposition question
+ * @param {string} capabilityId - The capability ID
+ * @param {number} levelIndex - The skill level index
+ * @returns {number} Priority score (higher = more important)
+ */
+function calculateCapabilityPriority(capabilityId, levelIndex) {
+  let priority = 0;
+
+  // Delivery and scale capabilities are typically more important for decomposition
+  if (capabilityId === Capability.DELIVERY) {
+    priority += 10;
+  } else if (capabilityId === Capability.SCALE) {
+    priority += 8;
+  } else if (capabilityId === Capability.RELIABILITY) {
+    priority += 6;
+  }
+
+  // Higher level = higher priority
+  priority += levelIndex * WEIGHT_SKILL_LEVEL;
 
   return priority;
 }
@@ -119,7 +218,8 @@ function selectQuestion(questions, deterministic = false) {
  * @param {number} [params.options.maxQuestionsPerSkill=2] - Max questions per skill
  * @param {number} [params.options.maxQuestionsPerBehaviour=2] - Max questions per behaviour
  * @param {number} [params.options.targetMinutes=60] - Target interview length in minutes
- * @param {number} [params.options.skillBehaviourRatio=0.6] - Ratio of time for skills vs behaviours (0.6 = 60% skills, 40% behaviours)
+ * @param {number} [params.options.skillBehaviourRatio=RATIO_SKILL_BEHAVIOUR] - Ratio of time for skills vs behaviours
+ * @param {string} [params.options.roleType='professionalQuestions'] - Role type ('professionalQuestions' or 'managementQuestions')
  * @returns {import('./levels.js').InterviewGuide}
  */
 export function deriveInterviewQuestions({ job, questionBank, options = {} }) {
@@ -129,7 +229,8 @@ export function deriveInterviewQuestions({ job, questionBank, options = {} }) {
     maxQuestionsPerSkill = 2,
     maxQuestionsPerBehaviour = 2,
     targetMinutes = 60,
-    skillBehaviourRatio = 0.6,
+    skillBehaviourRatio = RATIO_SKILL_BEHAVIOUR,
+    roleType = "professionalQuestions",
   } = options;
 
   const allSkillQuestions = [];
@@ -147,6 +248,7 @@ export function deriveInterviewQuestions({ job, questionBank, options = {} }) {
       questionBank,
       skill.skillId,
       targetLevel,
+      roleType,
     );
     let questionsAdded = 0;
 
@@ -176,6 +278,7 @@ export function deriveInterviewQuestions({ job, questionBank, options = {} }) {
         questionBank,
         skill.skillId,
         belowLevel,
+        roleType,
       );
 
       const belowQuestion = selectQuestion(belowQuestions, deterministic);
@@ -199,6 +302,8 @@ export function deriveInterviewQuestions({ job, questionBank, options = {} }) {
       questionBank,
       behaviour.behaviourId,
       targetMaturity,
+      roleType,
+      targetMaturity,
     );
     let questionsAdded = 0;
 
@@ -402,9 +507,14 @@ export function deriveShortInterview({
  * @param {Object} params
  * @param {import('./levels.js').JobDefinition} params.job - The job definition
  * @param {import('./levels.js').QuestionBank} params.questionBank - The question bank
+ * @param {string} [params.roleType='professionalQuestions'] - Role type ('professionalQuestions' or 'managementQuestions')
  * @returns {import('./levels.js').InterviewGuide}
  */
-export function deriveBehaviourQuestions({ job, questionBank }) {
+export function deriveBehaviourQuestions({
+  job,
+  questionBank,
+  roleType = "professionalQuestions",
+}) {
   const interviewQuestions = [];
   const coveredBehaviours = new Set();
 
@@ -417,6 +527,7 @@ export function deriveBehaviourQuestions({ job, questionBank }) {
       questionBank,
       behaviour.behaviourId,
       targetMaturity,
+      roleType,
     );
 
     for (const question of targetQuestions) {
@@ -460,6 +571,7 @@ export function deriveBehaviourQuestions({ job, questionBank }) {
  * @param {import('./levels.js').QuestionBank} params.questionBank - The question bank
  * @param {string[]} [params.focusSkills] - Skill IDs to focus on
  * @param {string[]} [params.focusBehaviours] - Behaviour IDs to focus on
+ * @param {string} [params.roleType='professionalQuestions'] - Role type ('professionalQuestions' or 'managementQuestions')
  * @returns {import('./levels.js').InterviewGuide}
  */
 export function deriveFocusedInterview({
@@ -467,6 +579,7 @@ export function deriveFocusedInterview({
   questionBank,
   focusSkills = [],
   focusBehaviours = [],
+  roleType = "professionalQuestions",
 }) {
   const interviewQuestions = [];
   const coveredSkills = new Set();
@@ -481,6 +594,7 @@ export function deriveFocusedInterview({
       questionBank,
       skill.skillId,
       skill.level,
+      roleType,
     );
     for (const question of questions) {
       interviewQuestions.push({
@@ -504,6 +618,7 @@ export function deriveFocusedInterview({
       questionBank,
       behaviour.behaviourId,
       behaviour.maturity,
+      roleType,
     );
     for (const question of questions) {
       interviewQuestions.push({
@@ -537,3 +652,317 @@ export function deriveFocusedInterview({
     },
   };
 }
+
+/**
+ * Derive Mission Fit interview questions (skill-focused)
+ *
+ * 45-minute interview with Recruiting Manager + 1 Senior Engineer
+ * Focuses on skill questions to assess technical capability and fit.
+ *
+ * @param {Object} params
+ * @param {import('./levels.js').JobDefinition} params.job - The job definition
+ * @param {import('./levels.js').QuestionBank} params.questionBank - The question bank
+ * @param {number} [params.targetMinutes=45] - Target interview length in minutes
+ * @param {string} [params.roleType='professionalQuestions'] - Role type ('professionalQuestions' or 'managementQuestions')
+ * @returns {import('./levels.js').InterviewGuide}
+ */
+export function deriveMissionFitInterview({
+  job,
+  questionBank,
+  targetMinutes = 45,
+  roleType = "professionalQuestions",
+}) {
+  const allSkillQuestions = [];
+  const coveredSkills = new Set();
+
+  // Generate all potential skill questions with priority
+  for (const skill of job.skillMatrix) {
+    const targetLevel = skill.level;
+    const targetLevelIndex = getSkillLevelIndex(targetLevel);
+
+    // Get questions at target level
+    const targetQuestions = getSkillQuestions(
+      questionBank,
+      skill.skillId,
+      targetLevel,
+      roleType,
+    );
+
+    for (const question of targetQuestions) {
+      allSkillQuestions.push({
+        question,
+        targetId: skill.skillId,
+        targetName: skill.skillName,
+        targetType: "skill",
+        targetLevel,
+        priority: calculateSkillPriority(skill, false),
+      });
+    }
+
+    // Also add question from level below for depth
+    if (targetLevelIndex > 0) {
+      const belowLevel = SKILL_LEVEL_ORDER[targetLevelIndex - 1];
+      const belowQuestions = getSkillQuestions(
+        questionBank,
+        skill.skillId,
+        belowLevel,
+        roleType,
+      );
+
+      for (const question of belowQuestions) {
+        allSkillQuestions.push({
+          question,
+          targetId: skill.skillId,
+          targetName: skill.skillName,
+          targetType: "skill",
+          targetLevel: belowLevel,
+          priority: calculateSkillPriority(skill, true),
+        });
+      }
+    }
+  }
+
+  // Sort by priority (highest first)
+  allSkillQuestions.sort((a, b) => b.priority - a.priority);
+
+  // Select questions within budget, prioritizing coverage diversity
+  const selectedQuestions = [];
+  const selectedSkillIds = new Set();
+  let totalMinutes = 0;
+
+  // First pass: one question per skill (highest priority first)
+  for (const q of allSkillQuestions) {
+    if (selectedSkillIds.has(q.targetId)) continue;
+    const questionTime =
+      q.question.expectedDurationMinutes || DEFAULT_QUESTION_MINUTES;
+    if (totalMinutes + questionTime <= targetMinutes + 5) {
+      selectedQuestions.push(q);
+      selectedSkillIds.add(q.targetId);
+      coveredSkills.add(q.targetId);
+      totalMinutes += questionTime;
+    }
+  }
+
+  // Second pass: add more questions if time allows
+  for (const q of allSkillQuestions) {
+    if (selectedQuestions.includes(q)) continue;
+    const questionTime =
+      q.question.expectedDurationMinutes || DEFAULT_QUESTION_MINUTES;
+    if (totalMinutes + questionTime <= targetMinutes + 5) {
+      selectedQuestions.push(q);
+      coveredSkills.add(q.targetId);
+      totalMinutes += questionTime;
+    }
+  }
+
+  // Re-sort by priority
+  selectedQuestions.sort((a, b) => b.priority - a.priority);
+
+  return {
+    job,
+    questions: selectedQuestions,
+    expectedDurationMinutes: totalMinutes,
+    coverage: {
+      skills: Array.from(coveredSkills),
+      behaviours: [],
+      capabilities: [],
+    },
+  };
+}
+
+/**
+ * Derive Decomposition interview questions (capability-focused)
+ *
+ * 60-minute interview with 2 Senior Engineers
+ * Focuses on capability decomposition questions inspired by Palantir's technique.
+ * Capabilities are selected based on the job's skill matrix.
+ *
+ * @param {Object} params
+ * @param {import('./levels.js').JobDefinition} params.job - The job definition
+ * @param {import('./levels.js').QuestionBank} params.questionBank - The question bank
+ * @param {number} [params.targetMinutes=60] - Target interview length in minutes
+ * @param {string} [params.roleType='professionalQuestions'] - Role type ('professionalQuestions' or 'managementQuestions')
+ * @returns {import('./levels.js').InterviewGuide}
+ */
+export function deriveDecompositionInterview({
+  job,
+  questionBank,
+  targetMinutes = 60,
+  roleType = "professionalQuestions",
+}) {
+  const allCapabilityQuestions = [];
+  const coveredCapabilities = new Set();
+
+  // Derive capability levels from the job's skill matrix
+  const capabilityLevels = deriveCapabilityLevels(job);
+
+  // Generate capability questions based on derived levels
+  for (const [capabilityId, levelInfo] of capabilityLevels) {
+    const { level, levelIndex } = levelInfo;
+
+    // Get questions at the derived level
+    const questions = getCapabilityQuestions(
+      questionBank,
+      capabilityId,
+      level,
+      roleType,
+    );
+
+    for (const question of questions) {
+      allCapabilityQuestions.push({
+        question,
+        targetId: capabilityId,
+        targetName: capabilityId, // Capability name can be enhanced if needed
+        targetType: "capability",
+        targetLevel: level,
+        priority: calculateCapabilityPriority(capabilityId, levelIndex),
+      });
+    }
+
+    // Also try level below if available
+    if (levelIndex > 0) {
+      const belowLevel = SKILL_LEVEL_ORDER[levelIndex - 1];
+      const belowQuestions = getCapabilityQuestions(
+        questionBank,
+        capabilityId,
+        belowLevel,
+        roleType,
+      );
+
+      for (const question of belowQuestions) {
+        allCapabilityQuestions.push({
+          question,
+          targetId: capabilityId,
+          targetName: capabilityId,
+          targetType: "capability",
+          targetLevel: belowLevel,
+          priority: calculateCapabilityPriority(capabilityId, levelIndex - 1),
+        });
+      }
+    }
+  }
+
+  // Sort by priority (highest first)
+  allCapabilityQuestions.sort((a, b) => b.priority - a.priority);
+
+  // Select questions within budget, prioritizing coverage diversity
+  const selectedQuestions = [];
+  const selectedCapabilityIds = new Set();
+  let totalMinutes = 0;
+
+  // First pass: one question per capability (highest priority first)
+  for (const q of allCapabilityQuestions) {
+    if (selectedCapabilityIds.has(q.targetId)) continue;
+    const questionTime =
+      q.question.expectedDurationMinutes || DEFAULT_DECOMPOSITION_MINUTES;
+    if (totalMinutes + questionTime <= targetMinutes + 5) {
+      selectedQuestions.push(q);
+      selectedCapabilityIds.add(q.targetId);
+      coveredCapabilities.add(q.targetId);
+      totalMinutes += questionTime;
+    }
+  }
+
+  // Second pass: add more questions if time allows
+  for (const q of allCapabilityQuestions) {
+    if (selectedQuestions.includes(q)) continue;
+    const questionTime =
+      q.question.expectedDurationMinutes || DEFAULT_DECOMPOSITION_MINUTES;
+    if (totalMinutes + questionTime <= targetMinutes + 5) {
+      selectedQuestions.push(q);
+      coveredCapabilities.add(q.targetId);
+      totalMinutes += questionTime;
+    }
+  }
+
+  // Re-sort by priority
+  selectedQuestions.sort((a, b) => b.priority - a.priority);
+
+  return {
+    job,
+    questions: selectedQuestions,
+    expectedDurationMinutes: totalMinutes,
+    coverage: {
+      skills: [],
+      behaviours: [],
+      capabilities: Array.from(coveredCapabilities),
+    },
+  };
+}
+
+/**
+ * Derive Stakeholder Simulation interview questions (behaviour-focused)
+ *
+ * 60-minute interview with 3-4 stakeholders.
+ * Selects the highest-maturity behaviours for the role and picks one chunky
+ * simulation question per behaviour. For most jobs this means 2-3 behaviours
+ * with ~20-minute simulation scenarios each.
+ *
+ * @param {Object} params
+ * @param {import('./levels.js').JobDefinition} params.job - The job definition
+ * @param {import('./levels.js').QuestionBank} params.questionBank - The question bank
+ * @param {number} [params.targetMinutes=60] - Target interview length in minutes
+ * @param {string} [params.roleType='professionalQuestions'] - Role type ('professionalQuestions' or 'managementQuestions')
+ * @returns {import('./levels.js').InterviewGuide}
+ */
+export function deriveStakeholderInterview({
+  job,
+  questionBank,
+  targetMinutes = 60,
+  roleType = "professionalQuestions",
+}) {
+  const coveredBehaviours = new Set();
+
+  // Sort behaviours by maturity (highest first) to prioritize the most emphasized
+  const sortedBehaviours = [...job.behaviourProfile].sort(
+    (a, b) =>
+      getBehaviourMaturityIndex(b.maturity) -
+      getBehaviourMaturityIndex(a.maturity),
+  );
+
+  // Select one question per behaviour, highest maturity first, within budget
+  const selectedQuestions = [];
+  let totalMinutes = 0;
+
+  for (const behaviour of sortedBehaviours) {
+    const targetMaturity = behaviour.maturity;
+
+    // Get questions at target maturity
+    const questions = getBehaviourQuestions(
+      questionBank,
+      behaviour.behaviourId,
+      targetMaturity,
+      roleType,
+    );
+
+    // Pick the first available question (1 per behaviour)
+    const question = questions[0];
+    if (!question) continue;
+
+    const questionTime =
+      question.expectedDurationMinutes || DEFAULT_SIMULATION_MINUTES;
+    if (totalMinutes + questionTime > targetMinutes + 5) break;
+
+    selectedQuestions.push({
+      question,
+      targetId: behaviour.behaviourId,
+      targetName: behaviour.behaviourName,
+      targetType: "behaviour",
+      targetLevel: targetMaturity,
+      priority: calculateBehaviourPriority(behaviour),
+    });
+    coveredBehaviours.add(behaviour.behaviourId);
+    totalMinutes += questionTime;
+  }
+
+  return {
+    job,
+    questions: selectedQuestions,
+    expectedDurationMinutes: totalMinutes,
+    coverage: {
+      skills: [],
+      behaviours: Array.from(coveredBehaviours),
+      capabilities: [],
+    },
+  };
+}

package/{lib → src}/job-cache.js

@@ -11,13 +11,13 @@ import { deriveJob } from "./derivation.js";
 const cache = new Map();
 
 /**
- * Create a consistent cache key from job parameters
+ * Build a consistent cache key from job parameters
  * @param {string} disciplineId
  * @param {string} gradeId
  * @param {string} [trackId] - Optional track ID
  * @returns {string}
  */
-export function makeJobKey(disciplineId, gradeId, trackId = null) {
+export function buildJobKey(disciplineId, gradeId, trackId = null) {
   if (trackId) {
     return `${disciplineId}_${gradeId}_${trackId}`;
   }
@@ -43,7 +43,7 @@ export function getOrCreateJob({
   behaviours,
   capabilities,
 }) {
-  const key = makeJobKey(discipline.id, grade.id, track?.id);
+  const key = buildJobKey(discipline.id, grade.id, track?.id);
 
   if (!cache.has(key)) {
     const job = deriveJob({
@@ -66,7 +66,7 @@ export function getOrCreateJob({
 /**
  * Clear all cached jobs
  */
-export function clearJobCache() {
+export function clearCache() {
   cache.clear();
 }
 
@@ -76,14 +76,14 @@ export function clearJobCache() {
  * @param {string} gradeId
  * @param {string} [trackId] - Optional track ID
  */
-export function invalidateJob(disciplineId, gradeId, trackId = null) {
-  cache.delete(makeJobKey(disciplineId, gradeId, trackId));
+export function invalidateCachedJob(disciplineId, gradeId, trackId = null) {
+  cache.delete(buildJobKey(disciplineId, gradeId, trackId));
 }
 
 /**
  * Get the number of cached jobs (for testing/debugging)
  * @returns {number}
  */
-export function getCacheSize() {
+export function getCachedJobCount() {
   return cache.size;
 }