Speed up error-resolution flow: triage, defer/loinc/resolve wrappers, auto LOINC candidates, ready-to-run swap suggestion

- triage.sh: batch-classify active errors into suggested actions (auto-swap / fhir-422 / sender-missing / loinc-lookup / parsing-defer / aidbox-reject).
- defer.sh / loinc-search.sh / resolve-mapping.sh: wrap the curl + jq boilerplate previously inlined in the skill docs.
- inspect-error.sh: for per-1 constraint, emit ready-to-run wire-preprocessor.ts command; for observation-code-loinc tasks, auto-run ValueSet/\$expand on each localDisplay so the picker has LOINC candidates without another call.
- Skill docs updated to point at the new scripts.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ipasechnikov

.claude/skills/check-errors/SKILL.md

@@ -17,6 +17,14 @@ Emits a markdown table of active errors plus a deferred-count reminder. If outpu
 
 If the user asked specifically about deferred messages, use `scripts/errors/list-errors.sh --deferred`.
 
+For a classified action plan across all active errors (recommended when there are ≥3):
+
+```sh
+scripts/errors/triage.sh
+```
+
+Prints each error with a suggested class (auto-swap / fhir-422 / sender-missing / loinc-lookup / parsing-defer / aidbox-reject / other) and next command. Read-only — user still approves each fix.
+
 Ask: **"Which error would you like me to investigate?"** Skip `deferred` rows unless the user explicitly asks.
 
 ## Step 2: Inspect one
@@ -27,7 +35,7 @@ scripts/errors/inspect-error.sh <id>
 
 Emits: status, type, sender, full error, unmapped codes (if present), raw HL7v2 saved to `/tmp/hl7v2-<id>.hl7`, and an `hl7v2-inspect` overview for `parsing_error`/`conversion_error`. **You do not need to curl the resource yourself.**
 
-For `HTTP 422` conversion errors the script also prints the **current values** of each candidate HL7v2 field, so you typically don't need an additional `hl7v2-inspect --field` call. For `code_mapping_error` with any `observation-code-loinc` task, peer OBX rows are dumped automatically — use them (code, unit, ref range) to pick the right LOINC.
+For `HTTP 422` conversion errors the script also prints the **current values** of each candidate HL7v2 field, so you typically don't need an additional `hl7v2-inspect --field` call. For `per-1` (reversed period) it also emits a **ready-to-run** `wire-preprocessor.ts` command — just copy/run it. For `code_mapping_error` with any `observation-code-loinc` task, peer OBX rows are dumped automatically AND LOINC candidates are fetched via ValueSet/$expand on each localDisplay — you usually have everything needed to pick the right LOINC without another call.
 
 Pick the playbook below by the `Status` line from Step 2.
 
@@ -38,7 +46,7 @@ Pick the playbook below by the `Status` line from Step 2.
 1. From the inspect overview, identify what's wrong: missing MSH, invalid encoding chars (MSH-1/2), truncated segments, wrong line endings, embedded binary.
 2. **No code/config fix.** Sender must correct the message format. Defer = resolved on our side — do it:
    ```sh
-   curl -sf -X POST 'http://localhost:3000/defer/<id>'
+   scripts/errors/defer.sh <id>
    ```
 3. Only mark for retry if the sender has already fixed and will resend with the same ID.
 
@@ -63,7 +71,7 @@ Do **not** run `hl7v2-inspect --values` unless the mapping is ambiguous. Diagnos
 2. Suggest fixes in this order:
    - Best: sender populates the missing field — explain what's needed; defer = park it out of active queue pending sender action:
      ```sh
-     curl -sf -X POST 'http://localhost:3000/defer/<id>'
+     scripts/errors/defer.sh <id>
      ```
    - Workaround: add a preprocessor in `src/v2-to-fhir/preprocessor-registry.ts` + `config/hl7v2-to-fhir.json`
    - Last resort: relax config (make a segment optional) — warn about the tradeoff
@@ -92,28 +100,21 @@ If a **new** preprocessor function is needed, write it manually first:
 
 Inspect output lists each unmapped code with `localCode`, `localDisplay`, `localSystem`, `mappingType`, and `taskId`. Use the printed `taskId` for the resolve call.
 
-1. For `observation-code-loinc`, search LOINC via Aidbox's ValueSet/$expand (the `/api/terminology/*` path does not exist):
+1. For `observation-code-loinc`, `inspect-error.sh` already dumps LOINC candidates via ValueSet/$expand. For an ad-hoc search:
    ```sh
-   SECRET=$(awk -F': ' '/^[[:space:]]*BOX_ROOT_CLIENT_SECRET:/ {print $2}' docker-compose.yaml)
-   TERM=$(printf '%s' '<term>' | jq -sRr @uri)
-   curl -sf -u "root:$SECRET" "http://localhost:8080/fhir/ValueSet/\$expand?url=http://loinc.org/vs&filter=${TERM}&count=10" \
-     | jq '.expansion.contains[] | {code, display}'
+   scripts/errors/loinc-search.sh '<term>' [--count N]
    ```
-   If the LOINC package is not loaded locally, `.expansion.contains` will be empty — fall back to domain knowledge and cite the LOINC concept by name (e.g. peer OBX codes in the same message, unit of measure, and specimen type).
+   If no matches, the LOINC package isn't loaded — fall back to domain knowledge and cite the LOINC concept by name (e.g. peer OBX codes in the same message, unit of measure, and specimen type).
 2. For `patient-class`, `obr-status`, `obx-status`, etc.: look up valid target values in `src/code-mapping/mapping-types.ts`.
 3. Present suggestions with confidence: "High: `2823-3` → LOINC `2823-3` (Potassium)" vs "Needs review: `GLU` → `2345-7` (Glucose) — verify with lab".
 4. If ambiguous / needs domain expertise → defer = park it out of active queue pending sender action:
    ```sh
-   curl -sf -X POST 'http://localhost:3000/defer/<id>'
+   scripts/errors/defer.sh <id>
    ```
-5. After approval, resolve via the app API. Endpoint expects **form-urlencoded** body with `resolvedCode` and `resolvedDisplay` (not JSON). A `302` redirect to `/unmapped-codes?saved=...&replayed=N` signals success:
+5. After approval, resolve via the app API. Message is auto-requeued.
    ```sh
-   curl -s -X POST 'http://localhost:3000/api/mapping/tasks/<taskId>/resolve' \
-     --data-urlencode 'resolvedCode=<target>' \
-     --data-urlencode 'resolvedDisplay=<target display>' \
-     -D - -o /dev/null
+   scripts/errors/resolve-mapping.sh <taskId> <resolvedCode> <resolvedDisplay>
    ```
-   Message is auto-requeued.
 
 ### `sending_error` — Aidbox rejected the FHIR bundle
 
@@ -157,8 +158,12 @@ scripts/errors/status.sh <id>
 | Script | Purpose |
 |---|---|
 | `scripts/errors/list-errors.sh` | Active errors + deferred reminder (markdown table). |
-| `scripts/errors/inspect-error.sh <id>` | Full diagnosis: resource fields, saved raw file, hl7v2-inspect overview, 422 candidates w/ values, peer OBX for LOINC tasks. |
+| `scripts/errors/triage.sh` | Batch-classify all active errors → suggested action per row. Read-only. |
+| `scripts/errors/inspect-error.sh <id>` | Full diagnosis: resource fields, saved raw file, hl7v2-inspect overview, 422 candidates w/ values + ready-to-run wire command for per-1, peer OBX + auto LOINC candidates for LOINC tasks. |
 | `scripts/errors/status.sh <id>` | Concise `{id,status,type,error,sender}` for a single message. |
 | `scripts/errors/verify-retry.sh <id>` | After a fix: verify → mark-for-retry → reprocess → status. Aborts if not supported. |
+| `scripts/errors/defer.sh <id>` | Defer a message (park out of active queue) + print status. |
+| `scripts/errors/loinc-search.sh <term>` | LOINC ValueSet/$expand wrapper. Prints `code — display` lines. |
+| `scripts/errors/resolve-mapping.sh <taskId> <code> <display>` | Resolve a mapping task (form-urlencoded POST) + auto-requeue. |
 | `scripts/errors/list-preprocessors.sh` | Available preprocessors w/ JSDoc summary. |
 | `scripts/errors/wire-preprocessor.ts` | Wire a preprocessor into `config.ts` + `hl7v2-to-fhir.json` atomically. Idempotent. |

scripts/errors/defer.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Defer an IncomingHL7v2Message — parks it out of active queue pending sender action.
+#
+# Usage: scripts/errors/defer.sh <message-id>
+set -e
+
+if [ -z "$1" ]; then
+  echo "Usage: $0 <message-id>" >&2
+  exit 2
+fi
+ID="$1"
+
+PROJECT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+curl -sf -X POST "http://localhost:3000/defer/$ID" >/dev/null
+"$PROJECT_DIR/scripts/errors/status.sh" "$ID"

scripts/errors/inspect-error.sh

@@ -101,6 +101,7 @@ if [ "$STATUS" = "conversion_error" ] && printf '%s' "$ERROR_TEXT" | grep -q 'HT
         case "$CONSTRAINT_ID" in
           per-1)
             echo "- Constraint \`per-1\`: period start must be <= end. Likely: sender reversed start/end fields. Candidate fix: \`swap-if-reversed\` preprocessor with params \`{ a, b }\` pointing at the two date fields."
+            SUGGEST_SWAP=1
             ;;
           ref-1)
             echo "- Constraint \`ref-1\`: SHALL have a contained resource or a reference (not both / need one). Likely: empty or dangling reference target."
@@ -185,6 +186,24 @@ if [ "$STATUS" = "conversion_error" ] && printf '%s' "$ERROR_TEXT" | grep -q 'HT
                     fi
                   done
                 fi
+                # Suggest a ready-to-run wire-preprocessor command when the fix is obvious
+                # (per-1 reversed dates: exactly 2 fields in the same segment).
+                if [ "${SUGGEST_SWAP:-0}" = "1" ]; then
+                  PAIR=$(printf '%s\n' "$FIELDS_TO_SHOW" | sort -u)
+                  PAIR_CNT=$(printf '%s\n' "$PAIR" | grep -c .)
+                  if [ "$PAIR_CNT" = "2" ]; then
+                    SEG=$(printf '%s\n' "$PAIR" | head -1 | cut -d- -f1)
+                    SEG2=$(printf '%s\n' "$PAIR" | tail -1 | cut -d- -f1)
+                    if [ "$SEG" = "$SEG2" ]; then
+                      A=$(printf '%s\n' "$PAIR" | head -1 | cut -d- -f2)
+                      B=$(printf '%s\n' "$PAIR" | tail -1 | cut -d- -f2)
+                      # Normalize msg type "ADT_A01^ADT_A01" -> "ADT-A01" for config key
+                      MSGKEY=$(printf '%s' "$TYPE" | cut -d'^' -f1 | tr '_' '-')
+                      echo "  Ready-to-run fix:"
+                      echo "    bun scripts/errors/wire-preprocessor.ts $MSGKEY $SEG $A swap-if-reversed '{\"a\":$A,\"b\":$B}'"
+                    fi
+                  fi
+                fi
               else
                 echo "  (no matching row in IG segment CSVs for path \`$PATH_TAIL\`)"
               fi
@@ -215,5 +234,24 @@ if [ "$STATUS" = "code_mapping_error" ] && [ "$UNMAPPED" != "[]" ]; then
     echo '```'
     "$PROJECT_DIR/scripts/hl7v2-inspect.sh" "$TMP" --segment OBX --values 2>&1 || true
     echo '```'
+
+    # Auto-run LOINC search on each observation-code-loinc task's localDisplay
+    # so common cases (Creatinine, Sodium, ...) are answered without another call.
+    echo
+    echo "### LOINC candidates (from ValueSet/\$expand)"
+    printf '%s' "$JSON" | jq -r '
+      . as $root |
+      .unmappedCodes[]? |
+      . as $u |
+      (($u.mappingTask.reference // "") | sub("^Task/"; "")) as $tid |
+      ([$root.entries[]? | select(.resourceType=="Task" and .id==$tid)] | first) as $t |
+      select($t.code.coding[0].code == "observation-code-loinc") |
+      "\($u.localCode // "")\t\($u.localDisplay // "")\t\($tid)"
+    ' | while IFS=$'\t' read -r LCODE LDISPLAY LTID; do
+      [ -z "$LDISPLAY" ] && continue
+      echo "- \`$LCODE\` ($LDISPLAY) — task \`$LTID\`:"
+      "$PROJECT_DIR/scripts/errors/loinc-search.sh" "$LDISPLAY" --count 5 2>/dev/null \
+        | sed 's/^/    /' || echo "    (lookup failed)"
+    done
   fi
 fi

scripts/errors/loinc-search.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# Search LOINC via Aidbox ValueSet/$expand. Prints top matches as "code — display".
+# Wraps the auth + URI encode + jq boilerplate.
+#
+# Usage: scripts/errors/loinc-search.sh <term> [--count N]
+set -e
+
+if [ -z "$1" ]; then
+  echo "Usage: $0 <term> [--count N]" >&2
+  exit 2
+fi
+
+TERM="$1"; shift
+COUNT=10
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --count) COUNT="$2"; shift ;;
+    *) echo "Unknown arg: $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+PROJECT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+SECRET=$(awk -F': ' '/^[[:space:]]*BOX_ROOT_CLIENT_SECRET:/ {print $2}' "$PROJECT_DIR/docker-compose.yaml")
+if [ -z "$SECRET" ]; then
+  echo "ERROR: BOX_ROOT_CLIENT_SECRET missing from docker-compose.yaml" >&2
+  exit 1
+fi
+
+ENC=$(printf '%s' "$TERM" | jq -sRr @uri)
+RESP=$(curl -sf -u "root:$SECRET" \
+  "http://localhost:8080/fhir/ValueSet/\$expand?url=http://loinc.org/vs&filter=${ENC}&count=${COUNT}")
+
+N=$(printf '%s' "$RESP" | jq -r '.expansion.contains | length // 0')
+if [ "$N" = "0" ]; then
+  echo "(no matches — LOINC package may not be loaded; fall back to domain knowledge)"
+  exit 0
+fi
+
+printf '%s' "$RESP" | jq -r '.expansion.contains[] | "\(.code) — \(.display)"'

scripts/errors/resolve-mapping.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Resolve an unmapped code mapping task. Auto-requeues the message.
+# Wraps the form-urlencoded POST + 302 parsing.
+#
+# Usage: scripts/errors/resolve-mapping.sh <taskId> <resolvedCode> <resolvedDisplay>
+set -e
+
+if [ $# -lt 3 ]; then
+  echo "Usage: $0 <taskId> <resolvedCode> <resolvedDisplay>" >&2
+  exit 2
+fi
+
+TASK_ID="$1"
+CODE="$2"
+DISPLAY="$3"
+
+RESP=$(curl -s -X POST "http://localhost:3000/api/mapping/tasks/$TASK_ID/resolve" \
+  --data-urlencode "resolvedCode=$CODE" \
+  --data-urlencode "resolvedDisplay=$DISPLAY" \
+  -D - -o /dev/null)
+
+STATUS=$(printf '%s' "$RESP" | awk 'NR==1 {print $2}')
+LOCATION=$(printf '%s' "$RESP" | awk -F': ' 'tolower($1)=="location" {print $2}' | tr -d '\r')
+
+if [ "$STATUS" = "302" ]; then
+  echo "resolved: $CODE ($DISPLAY)"
+  echo "redirect: $LOCATION"
+else
+  echo "ERROR: expected 302, got $STATUS" >&2
+  printf '%s\n' "$RESP" >&2
+  exit 1
+fi

scripts/errors/triage.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# Batch-classify all active errors into suggested actions.
+# Read-only — prints a plan. User still confirms each fix.
+#
+# Classifications:
+#   auto-swap       conversion_error w/ HTTP 422 per-1 (reversed dates)
+#   fhir-422        conversion_error w/ HTTP 422 (other constraint — needs preprocessor)
+#   sender-missing  conversion_error w/ "required but missing" (defer-candidate)
+#   loinc-lookup    code_mapping_error w/ observation-code-loinc
+#   code-mapping    code_mapping_error other (check src/code-mapping/mapping-types.ts)
+#   parsing-defer   parsing_error (sender fix → defer)
+#   aidbox-reject   sending_error (check Aidbox health)
+#   other           unrecognized — inspect manually
+#
+# Usage: scripts/errors/triage.sh
+set -e
+
+PROJECT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+SECRET=$(awk -F': ' '/^[[:space:]]*BOX_ROOT_CLIENT_SECRET:/ {print $2}' "$PROJECT_DIR/docker-compose.yaml")
+if [ -z "$SECRET" ]; then
+  echo "ERROR: BOX_ROOT_CLIENT_SECRET missing from docker-compose.yaml" >&2
+  exit 1
+fi
+
+ERROR_STATUSES="parsing_error,conversion_error,code_mapping_error,sending_error"
+ELEMENTS="id,status,type,error,sendingApplication,sendingFacility"
+
+JSON=$(curl -sf -u "root:$SECRET" \
+  "http://localhost:8080/fhir/IncomingHL7v2Message?status=$ERROR_STATUSES&_sort=-_lastUpdated&_count=50&_elements=$ELEMENTS")
+N=$(printf '%s' "$JSON" | jq -r '(.entry // []) | length')
+
+if [ "$N" = "0" ]; then
+  echo "No active errors."
+  exit 0
+fi
+
+echo "**Triage plan ($N active errors):**"
+echo
+echo "| # | Class | Type | ID | Suggested action |"
+echo "|---|-------|------|----|------------------|"
+
+printf '%s' "$JSON" | jq -r '
+  .entry | to_entries[] |
+  .key as $i | .value.resource as $r |
+  "\($i + 1)\t\($r.status // "")\t\($r.type // "")\t\($r.id)\t\($r.error // "" | gsub("[\r\n]+"; " "))"
+' | while IFS=$'\t' read -r IDX STATUS TYPE ID ERR; do
+  case "$STATUS" in
+    conversion_error)
+      if printf '%s' "$ERR" | grep -q "HTTP 422"; then
+        if printf '%s' "$ERR" | grep -q "per-1"; then
+          CLASS="auto-swap"
+          ACTION="\`inspect-error.sh $ID\` → run emitted \`wire-preprocessor.ts\` line → \`verify-retry.sh\`"
+        else
+          CLASS="fhir-422"
+          ACTION="\`inspect-error.sh $ID\` → pick preprocessor from candidates"
+        fi
+      elif printf '%s' "$ERR" | grep -q "required but missing"; then
+        CLASS="sender-missing"
+        ACTION="likely \`defer.sh $ID\` (sender must populate field)"
+      else
+        CLASS="conv-other"
+        ACTION="\`inspect-error.sh $ID\`"
+      fi
+      ;;
+    code_mapping_error)
+      CLASS="loinc-lookup"
+      ACTION="\`inspect-error.sh $ID\` (auto LOINC candidates) → \`resolve-mapping.sh <taskId> <code> <display>\`"
+      ;;
+    parsing_error)
+      CLASS="parsing-defer"
+      ACTION="\`defer.sh $ID\` (sender must fix malformed message)"
+      ;;
+    sending_error)
+      CLASS="aidbox-reject"
+      ACTION="check \`curl http://localhost:8080/health\` → \`inspect-error.sh $ID\`"
+      ;;
+    *)
+      CLASS="other"
+      ACTION="\`inspect-error.sh $ID\`"
+      ;;
+  esac
+  echo "| $IDX | $CLASS | $TYPE | \`$ID\` | $ACTION |"
+done