Speed up check-errors workflow: status/verify-retry/list-preprocessors/wire-preprocessor scripts, richer inspect-error

ipasechnikov · claude · ipasechnikov · commit 730088b7914c · 2026-04-24T23:31:01.000+09:00
New scripts under scripts/errors/:
- status.sh: concise {id,status,type,error,sender} for a message.
- verify-retry.sh: chains check-message-support -&gt; mark-for-retry -&gt; reprocess -&gt; status; aborts when verdict is not "supported".
- list-preprocessors.sh: lists registered preprocessor IDs with their JSDoc summary.
- wire-preprocessor.ts: idempotent scaffold that ensures the MessageTypeConfig.preprocess slot in src/v2-to-fhir/config.ts and appends the entry to config/hl7v2-to-fhir.json.

inspect-error.sh:
- For HTTP 422 conversion errors, also prints the current HL7v2 value of every candidate field so the fix is obvious without another --values call.
- For code_mapping_error with any observation-code-loinc task, dumps peer OBX rows (code, value, unit, reference range) to help pick the right LOINC from neighbors.

check-errors SKILL.md: points at the new scripts, collapses the post-fix step to a single command, and adds a script-reference table.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.claude/skills/check-errors/SKILL.md b/.claude/skills/check-errors/SKILL.md
@@ -27,6 +27,8 @@ 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.
+
 Pick the playbook below by the `Status` line from Step 2.
 
 ## Step 3: Diagnose by status
@@ -70,11 +72,21 @@ Do **not** run `hl7v2-inspect --values` unless the mapping is ambiguous. Diagnos
 
 #### Adding a preprocessor (recipe)
 
-Three files, in order:
+If the preprocessor **already exists** (check `scripts/errors/list-preprocessors.sh`), wire it in with one command — edits both config files atomically:
+
+```sh
+bun scripts/errors/wire-preprocessor.ts <msgType> <SEG> <FIELD> <preprocessorId> [paramsJson]
+
+# Example:
+bun scripts/errors/wire-preprocessor.ts ADT-A01 IN1 12 swap-if-reversed '{"a":12,"b":13}'
+```
+
+Idempotent — re-running with the same args is a no-op. The script adds the missing slot to `MessageTypeConfig.preprocess.<SEG>` in `src/v2-to-fhir/config.ts` and the JSON entry under the matching message type.
+
+If a **new** preprocessor function is needed, write it manually first:
 
 1. **`src/v2-to-fhir/preprocessor-registry.ts`** — add key + function to `SEGMENT_PREPROCESSORS`. Function receives the whole segment; the field key in config is only a trigger guard (preprocessor runs when that field is present, except `fallback-rxa3-from-msh7` which runs even when absent).
-2. **`src/v2-to-fhir/config.ts`** — add the field slot to `MessageTypeConfig.preprocess.<SEG>` (e.g. `IN1?: { "12"?: SegmentPreprocessorId[] }`).
-3. **`config/hl7v2-to-fhir.json`** — add the entry under the relevant message type. Use the `Read` tool for this file — `bun -e` and `python3` fail on JSONC comments.
+2. Then run `wire-preprocessor.ts` to wire it in.
 
 ### `code_mapping_error` — local code has no FHIR mapping
 
@@ -115,25 +127,22 @@ Inspect output lists each unmapped code with `localCode`, `localDisplay`, `local
 
 ## Step 4: After a fix
 
-1. Verify locally:
-   ```sh
-   bun scripts/check-message-support.ts /tmp/hl7v2-<id>.hl7
-   ```
-   Only proceed when verdict is `supported` or `supported with caveats`.
-2. Mark for retry (app endpoint, not Aidbox):
-   ```sh
-   curl -sf -X POST 'http://localhost:3000/mark-for-retry/<id>'
-   ```
-3. Trigger reprocessing:
-   ```sh
-   curl -sf -X POST 'http://localhost:3000/process-incoming-messages'
-   ```
-4. Re-check status:
-   ```sh
-   SECRET=$(awk -F': ' '/^[[:space:]]*BOX_ROOT_CLIENT_SECRET:/ {print $2}' docker-compose.yaml)
-   curl -sf -u "root:$SECRET" 'http://localhost:8080/fhir/IncomingHL7v2Message/<id>?_elements=id,status,error' | jq
-   ```
-5. Report result.
+One command chains verify → mark-for-retry → reprocess → status:
+
+```sh
+scripts/errors/verify-retry.sh <id>
+```
+
+Aborts if `check-message-support.ts` verdict is not `supported`. Status is printed via `scripts/errors/status.sh` (id/status/type/error/sender).
+
+Use the individual commands below only when you need a partial step (e.g. verify without retrying):
+
+```sh
+bun scripts/check-message-support.ts /tmp/hl7v2-<id>.hl7
+curl -sf -X POST 'http://localhost:3000/mark-for-retry/<id>'
+curl -sf -X POST 'http://localhost:3000/process-incoming-messages'
+scripts/errors/status.sh <id>
+```
 
 ## Rules
 
@@ -142,3 +151,14 @@ Inspect output lists each unmapped code with `localCode`, `localDisplay`, `local
 - Skip `deferred` rows in the summary unless the user asks about them.
 - Don't hand-count pipes — the inspect script already ran `hl7v2-inspect.sh`. For deeper field lookup use `scripts/hl7v2-inspect.sh --field SEG.N`.
 - Use the `hl7v2-info` skill to verify HL7v2 spec compliance when needed.
+
+## Script reference
+
+| 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/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/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. |
diff --git a/scripts/errors/inspect-error.sh b/scripts/errors/inspect-error.sh
@@ -168,6 +168,23 @@ if [ "$STATUS" = "conversion_error" ] && printf '%s' "$ERROR_TEXT" | grep -q 'HT
               if [ -n "$CANDIDATES" ]; then
                 echo "  HL7v2 source candidates:"
                 printf '%s\n' "$CANDIDATES" | sed 's/^/    - /'
+                # Print current values for each candidate field so the fix is obvious
+                # without another hl7v2-inspect call.
+                FIELDS_TO_SHOW=$(printf '%s\n' "$CANDIDATES" | awk '{print $1}' | sort -u)
+                if [ -n "$FIELDS_TO_SHOW" ]; then
+                  echo "  Current values:"
+                  printf '%s\n' "$FIELDS_TO_SHOW" | while IFS= read -r FLD; do
+                    [ -z "$FLD" ] && continue
+                    DOTTED=$(printf '%s' "$FLD" | tr '-' '.')
+                    VAL_LINE=$("$PROJECT_DIR/scripts/hl7v2-inspect.sh" "$TMP" --field "$DOTTED" --values 2>/dev/null \
+                      | grep -E "^\s+$FLD:" | head -1 | sed 's/^[[:space:]]*//')
+                    if [ -n "$VAL_LINE" ]; then
+                      echo "    - $VAL_LINE"
+                    else
+                      echo "    - $FLD: (empty)"
+                    fi
+                  done
+                fi
               else
                 echo "  (no matching row in IG segment CSVs for path \`$PATH_TAIL\`)"
               fi
@@ -178,3 +195,25 @@ if [ "$STATUS" = "conversion_error" ] && printf '%s' "$ERROR_TEXT" | grep -q 'HT
     fi
   fi
 fi
+
+# For code_mapping_error: when any unmapped code is observation-code-loinc,
+# dump peer OBX rows (code + value + unit + ref range) so the reviewer can
+# pick the right LOINC from neighbors without another hl7v2-inspect call.
+if [ "$STATUS" = "code_mapping_error" ] && [ "$UNMAPPED" != "[]" ]; then
+  HAS_LOINC=$(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 |
+      ($t.code.coding[0].code // "")
+    ] | any(. == "observation-code-loinc")
+  ' 2>/dev/null || echo "false")
+  if [ "$HAS_LOINC" = "true" ]; then
+    echo
+    echo "### Peer OBX context (pick LOINC from neighbors + units)"
+    echo '```'
+    "$PROJECT_DIR/scripts/hl7v2-inspect.sh" "$TMP" --segment OBX --values 2>&1 || true
+    echo '```'
+  fi
+fi
diff --git a/scripts/errors/list-preprocessors.sh b/scripts/errors/list-preprocessors.sh
@@ -0,0 +1,55 @@
+#!/bin/bash
+# List available HL7v2 segment preprocessors (by ID) with the first line
+# of the JSDoc above each implementation, so the check-errors skill can
+# pick the right preprocessor without grepping the registry.
+#
+# Usage: scripts/errors/list-preprocessors.sh
+set -e
+
+PROJECT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+REG="$PROJECT_DIR/src/v2-to-fhir/preprocessor-registry.ts"
+
+if [ ! -f "$REG" ]; then
+  echo "ERROR: $REG not found" >&2
+  exit 1
+fi
+
+awk '
+  # Phase 1: collect id → function-name mapping from SEGMENT_PREPROCESSORS literal.
+  /^export const SEGMENT_PREPROCESSORS/ { in_map = 1; next }
+  in_map && /^\};/ { in_map = 0; next }
+  in_map {
+    if (match($0, /"([a-z0-9-]+)":[[:space:]]+([a-zA-Z0-9_]+)/, m)) {
+      fn2id[m[2]] = m[1]
+      order[++n] = m[1]
+    }
+  }
+
+  # Phase 2: capture JSDoc + function-name pairs anywhere in the file.
+  /^\/\*\*/ { doc = ""; in_doc = 1; next }
+  in_doc && /\*\// { in_doc = 0; next }
+  in_doc {
+    line = $0
+    sub(/^[[:space:]]*\*[[:space:]]?/, "", line)
+    if (line != "" && doc == "") doc = line
+    next
+  }
+  /^function [a-zA-Z0-9_]+\(/ {
+    if (match($0, /^function ([a-zA-Z0-9_]+)\(/, m)) {
+      if (m[1] in fn2id) {
+        id = fn2id[m[1]]
+        desc[id] = doc
+      }
+      doc = ""
+    }
+  }
+
+  END {
+    for (i = 1; i <= n; i++) {
+      id = order[i]
+      d = (id in desc) ? desc[id] : ""
+      if (d == "") printf "- %s\n", id
+      else printf "- %s — %s\n", id, d
+    }
+  }
+' "$REG"
diff --git a/scripts/errors/status.sh b/scripts/errors/status.sh
@@ -0,0 +1,24 @@
+#!/bin/bash
+# Print status, error, and meta for one IncomingHL7v2Message.
+# Centralizes the docker-compose secret parsing + curl + jq boilerplate
+# that appears in every check-errors follow-up.
+#
+# Usage: scripts/errors/status.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)"
+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
+
+curl -sf -u "root:$SECRET" \
+  "http://localhost:8080/fhir/IncomingHL7v2Message/$ID" \
+  | jq '{id, status, type, error, sender: ((.sendingApplication // "") + "/" + (.sendingFacility // ""))}'
diff --git a/scripts/errors/verify-retry.sh b/scripts/errors/verify-retry.sh
@@ -0,0 +1,42 @@
+#!/bin/bash
+# After a fix, verify the message converts cleanly, then mark for retry,
+# trigger reprocessing, and poll status. Chains the typical 3-4 commands
+# into one call so a fix → verify → retry cycle is a single step.
+#
+# Requires: scripts/errors/inspect-error.sh <id> has been run first so the
+# raw HL7v2 lives at /tmp/hl7v2-<id>.hl7.
+#
+# Usage: scripts/errors/verify-retry.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)"
+FIXTURE="/tmp/hl7v2-$ID.hl7"
+if [ ! -f "$FIXTURE" ]; then
+  echo "ERROR: $FIXTURE missing. Run scripts/errors/inspect-error.sh $ID first." >&2
+  exit 1
+fi
+
+echo "### Verify"
+VERIFY_OUT=$(bun "$PROJECT_DIR/scripts/check-message-support.ts" "$FIXTURE")
+echo "$VERIFY_OUT"
+if ! printf '%s\n' "$VERIFY_OUT" | grep -qiE '^Verdict: +supported'; then
+  echo
+  echo "### Aborted — verdict is not 'supported'. Fix before retrying." >&2
+  exit 1
+fi
+
+echo
+echo "### Retry"
+curl -sf -X POST "http://localhost:3000/mark-for-retry/$ID"
+curl -sf -X POST 'http://localhost:3000/process-incoming-messages'
+echo "retry triggered"
+echo
+
+echo "### Status"
+"$PROJECT_DIR/scripts/errors/status.sh" "$ID"
diff --git a/scripts/errors/wire-preprocessor.ts b/scripts/errors/wire-preprocessor.ts
