hermes-skills/skills/legal/contract-portfolio-analysis/references/uwf-workflow-pitfalls.md

UWF Workflow Pitfalls for nantong-lease-audit

Last updated: 2026-06-30

Pitfall 1: File Name Collision — Multiple Contracts per Campus

The nantong-lease-audit workflow writes output to:

/tmp/nantong-lease-audit/{{ campus }}-row-data.json

When a campus has multiple contracts (e.g., 租赁 + 物业), running both contracts through the workflow causes the second to overwrite the first's JSON file.

Discovered: 通州金鹰 — 租赁合同 wrote 通州金鹰-row-data.json, then 物业合同 overwrote it.

Fix: When running multiple contracts for the same campus:

1. Run them sequentially (not in parallel) — OR —
2. After each workflow completes, rename/copy the output before starting the next:

   # After lease contract workflow completes:
   cp /tmp/nantong-lease-audit/通州金鹰-row-data.json \
      /tmp/nantong-lease-audit/通州金鹰-租赁-row-data.json
   # Then run property contract workflow (will overwrite 通州金鹰-row-data.json)
   

3. When building the xlsx, read both JSON files separately

Current workaround used: Read the lease contract data from CAS step output (uwf step show <hash>) if the JSON was overwritten, then manually reconstruct the property contract data.

Pitfall 2: Workflow Prompt Variable Not Passed

The classifier role's moderator instruction shows empty values:

分类合同。OCR文本路径：，校区：，原始文件名：

This happens when the ocr_path, campus, and filename variables are not properly interpolated from the thread start prompt. The classifier still works because the OCR path is in the task context, but the moderator prompt looks incomplete.

Root cause: The thread start prompt uses Chinese colons ： which may not match the YAML template variable syntax. Current workaround: the classifier reads the OCR path from the task context anyway.

Pitfall 3: Workflow v1 → v2 Hash Change

When the workflow YAML is updated and re-registered:

• Old hash: 7KZ5BWT12R5RJ (v1, no format templates)
• New hash: C77579MQ9QPKE (v2, with H/K/L format templates + reference loading)

Threads started before the update continue using the old hash. Always verify which hash is active:

uwf workflow show nantong-lease-audit  # Shows current hash

Pitfall 4: Background Exec Returns "Step 1 running"

When using uwf thread exec <id> --count 20 --background, the foreground output may show only:

Step 1  classifier → running

This does NOT mean only step 1 ran. The background worker continues processing all steps. Check actual progress with:

uwf step list <thread-id>
uwf thread show <thread-id>

Expected progression: classifier → template-diff → rule-analyzer → data-extractor → end. Total time: ~15-20 minutes for all 4 steps.