sdac-validate-justifications

Purpose

Checks that salary/fringe deltas above a threshold have meaningful justifications in comments.

Tool type

Deterministic (rule-based)

Tool ID

sdac-validate-justifications

Inputs

• report_id (string)
• threshold_pct (number, optional, default: 5)
• analyze_justification_quality (boolean, optional, default: true)
• cross_reference_changes (boolean, optional, default: true)

Outputs

• errors and warnings for missing or weak justifications
• executed_rules
• justification_quality (optional)
• personnel_change_correlation (optional)
• recommendations

Example output

{
  "success": true,
  "report_id": "SDAC-2024-Q2-001",
  "passed": false,
  "errors": [
    {
      "rule_id": "JUSTIFICATION_MISSING_FOR_VARIANCE",
      "message": "Salary variance is above 5% but no justification was supplied.",
      "severity": "ERROR"
    }
  ],
  "warnings": [
    {
      "rule_id": "JUSTIFICATION_WEAK",
      "message": "Fringe justification does not explain why fringe increased more than salary.",
      "severity": "WARNING"
    }
  ],
  "executed_rules": [
    "JUSTIFICATION_REQUIRED_FOR_VARIANCE",
    "JUSTIFICATION_QUALITY"
  ],
  "justification_quality": {
    "score": 0.42,
    "missing_elements": [
      "specific staffing change",
      "fringe-rate explanation"
    ]
  },
  "personnel_change_correlation": {
    "position_count_delta": 5,
    "supports_salary_variance": true
  },
  "recommendations": [
    "Request a more specific fringe justification from the district."
  ]
}

Functional details

• Scores comment quality (HIGH/MEDIUM/LOW) and tracks common patterns.
• Correlates justifications with detected personnel changes.
• Suggests expected justification types for flagged changes.

Implementation details

• Matches current vs prior-year records by UniqueIdentifier, then by normalized name+title.
• Requires comments with length ≥ 8 and not equal to placeholders (e.g., N/A, TBD).
• Emits JUSTIFICATION_SALARY_DIFFERENTIAL / JUSTIFICATION_FRINGE_DIFFERENTIAL when deltas exceed threshold.
• Warns with JUSTIFICATION_NO_PRIOR_REPORT when no prior report exists.
• Uses percent change formula with a previous === 0 guard.

Code Location: packages/domain-sdac/src/tools/validate-justifications.tool.ts