sdac-link-replacement-comments

Purpose

Parses replacement roster comments to link replacement entries back to main roster personnel, identifying missing or ambiguous references.

Tool type

Hybrid (deterministic with optional AI assistance)

Tool ID

sdac-link-replacement-comments

Inputs

• report_id (string)
• use_ai_assist (boolean, optional, default: false)
• max_ai_candidates (number, optional, default: 10)

Outputs

• success
• summary (counts for valid links, orphaned replacements, unmatched references)
• valid_links, unmatched_references, orphaned_replacements
• ai_assistance (optional; AI suggestions when enabled)
• recommendations

Example output

{
  "success": true,
  "report_id": "SDAC-2024-Q2-001",
  "summary": {
    "valid_links": 3,
    "unmatched_references": 1,
    "orphaned_replacements": 1
  },
  "valid_links": [
    {
      "replacement_row_number": 72,
      "main_roster_row_number": 18,
      "confidence": 0.96
    }
  ],
  "unmatched_references": [
    {
      "replacement_row_number": 73,
      "referenced_row_number": 999,
      "reason": "Referenced row not found in main roster."
    }
  ],
  "orphaned_replacements": [
    {
      "replacement_row_number": 74,
      "reason": "No row reference found in comment."
    }
  ],
  "recommendations": [
    "Ask the district to correct row references for rows 73 and 74."
  ]
}

Functional details

• Scans comments for phrases like “replacing”, “covering for”, or name references.
• Attempts to match referenced names/titles to main roster entries.
• Flags replacement rows missing a clear main-roster reference.

How it works (step-by-step)

1. Loads all personnel rows for the report.
2. Splits the dataset into main roster (non-replacement) and replacement rows.
3. For each replacement row, parses the Comments field using deterministic patterns:
   • Row references: row 12, row#12, #12
   • Replacement phrases: replacing, covering for, replaces
   • Name mentions (first/last name tokens)
4. Builds candidate matches from the main roster using:
   • Row number references (highest confidence)
   • Normalized name/title keys (fallback)
5. Produces three buckets:
   • valid_links: replacement → main roster matches
   • unmatched_references: ambiguous or conflicting references
   • orphaned_replacements: no usable reference found

Deterministic vs AI

By default this tool is deterministic (fixed regex/string rules + DB lookups). When use_ai_assist=true, it runs an AI pass on ambiguous cases and returns confidence-scored suggestions in ai_assistance.

Common patterns detected

• “Replacing John Doe”
• “Covering for Jane Smith (Row 45)”
• “Row 12” or “#12”

Edge cases

• Multiple names in one comment → flagged as unmatched_references.
• Conflicting row number vs. name reference → flagged for review.
• Missing Comments → flagged as orphaned_replacements.

Example

Input

{
	"report_id": "Q1-2024-District123"
}

Output (excerpt)

{
	"success": true,
	"summary": {
		"valid_links": 2,
		"orphaned_replacements": 1,
		"unmatched_references": 1,
		"main_roster_with_replacement_comments": 0,
		"replacements_with_main_references": 3,
		"issues_found": 2
	},
	"valid_links": [
		{
			"replacement_row": 118,
			"main_roster_row": 45,
			"match_method": "ROW_REFERENCE",
			"reference_text": "Row 45"
		}
	],
	"unmatched_references": [
		{
			"replacement_row": 122,
			"reference_text": "Replacing John and Jane",
			"reason": "Multiple name references"
		}
	],
	"orphaned_replacements": [
		{
			"replacement_row": 130,
			"reason": "Missing comment"
		}
	]
}

Usage notes

• Run after sdac-validate-replacements to resolve any linkage gaps.
• Use outputs to follow up with the district for clarification.

Implementation details

• Loads main roster and replacement rows via loadPersonnelRecords().
• Applies regex patterns to extract potential name references.
• Produces a normalized link list for downstream reporting.

Code Location: packages/domain-sdac/src/tools/link-replacement-comments.tool.ts