sdac-compare-multiple-quarters

Purpose

Compares a current report against a selected comparison quarter (prior quarter, same quarter prior year, or custom) and highlights changes at the position and total level.

Tool type

Deterministic (rule-based)

Tool ID

sdac-compare-multiple-quarters

Inputs

• current_report_id (string)
• comparison_type (SAME_QUARTER_PRIOR_YEAR | PRIOR_QUARTER | CUSTOM)
• include_position_details (boolean): Include per-position change details
• comparison_report_id (string, optional): Required when comparison_type= CUSTOM
• comparison_quarter (string, optional): Used to resolve custom report
• comparison_year (number, optional): Used to resolve custom report

Outputs

• success, comparison_report_id
• totals (salary/fringe totals and differentials)
• added_positions, removed_positions
• position_changes (optional when include_position_details=true)
• flagged_issues, recommendations

Example output

{
  "success": true,
  "comparison_report_id": "cmp-2024-q2-q1-q2prior",
  "totals": {
    "current": {
      "salary": 1250000,
      "fringe": 312000,
      "position_count": 84
    },
    "comparisons": [
      {
        "report_id": "SDAC-2023-Q2-001",
        "salary_delta_percent": 8.4,
        "fringe_delta_percent": 10.1
      },
      {
        "report_id": "SDAC-2024-Q1-001",
        "salary_delta_percent": 2.2,
        "fringe_delta_percent": 1.4
      }
    ]
  },
  "added_positions": [
    {
      "job_title": "Occupational Therapist",
      "row_number": 44
    }
  ],
  "removed_positions": [
    {
      "job_title": "Speech Assistant",
      "prior_row_number": 31
    }
  ],
  "flagged_issues": [
    {
      "severity": "WARNING",
      "message": "Fringe increased more than salary compared with prior-year same quarter."
    }
  ],
  "recommendations": [
    "Review district justification for the fringe increase."
  ]
}

Functional details

• Resolves the comparison report based on the chosen strategy.
• Computes salary/fringe deltas and percent changes.
• Matches personnel by unique identifier and/or name/title key.
• Flags large deltas and missing positions for reviewer follow-up.

Usage notes

• Use this tool when you need a specific quarter comparison beyond the default same-quarter prior year.
• Enable include_position_details for deep review workflows.

Implementation details

• Loads personnel records for both reports and builds UID/name-based lookup maps.
• Calculates totals using loadReportTotals() for consistent aggregation.
• Emits structured change objects for downstream tooling.

Code Location: packages/domain-sdac/src/tools/compare-multiple-quarters.tool.ts