diff --git a/.claude/skills/remediation-tool/scripts/onboard-tenant.sh b/.claude/skills/remediation-tool/scripts/onboard-tenant.sh
index f0ed052..74e827d 100755
--- a/.claude/skills/remediation-tool/scripts/onboard-tenant.sh
+++ b/.claude/skills/remediation-tool/scripts/onboard-tenant.sh
@@ -323,6 +323,11 @@ consent_app() {
 }
 
 # ── Helper: check if directory role already assigned ─────────────────────────
+# TODO(howard): This only checks roleAssignments (direct/permanent). PIM-managed
+# assignments live in roleAssignmentSchedules and won't be found here, causing
+# noisy-but-harmless "MISSING -> ASSIGNING" output that hits the Conflict fallback.
+# Fix: also query /roleManagement/directory/roleAssignmentSchedules?$filter=principalId eq '...'
+# and return true if either query finds the role. Reference: Howard's note 2026-04-29.
 role_assigned() {
   local token="$1"
   local sp_oid="$2"