stef-openclaw-skills/docs/plans/2026-03-28-property-assessor-whatsapp-safe-runtime.md

Property Assessor WhatsApp-Safe Runtime Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Keep WhatsApp property-assessor runs moving by failing fast on silent discovery/photo hangs, avoiding helper subprocesses during core analysis, and reserving subprocess use to the final PDF render attempt only.

Architecture: Add small timeout guards around the existing in-process listing discovery and photo extraction calls so one quiet browser-backed task cannot stall the entire assessment. Tighten the live skill and published docs so messaging runs treat chat-native source collection as the default path and helper commands as non-chat or final-render-only tools.

Tech Stack: TypeScript, Node test runner, existing OpenClaw property-assessor skill, existing OpenClaw web-automation modules, Markdown docs.

---

Task 1: Add failing timeout tests for discovery and photo extraction

Files:

• Modify: skills/property-assessor/tests/assessment.test.ts

Step 1: Write the failing test

Add tests that stub discovery/photo functions with never-resolving promises and assert that:

• listing discovery returns null URLs and records timeout attempts
• photo extraction returns not completed instead of hanging forever

Step 2: Run test to verify it fails

Run: npm test -- --test-name-pattern "times out" Expected: FAIL because current code never times out or records timeout attempts.

Step 3: Write minimal implementation

Implement the smallest timeout wrapper needed for the tests to pass.

Step 4: Run test to verify it passes

Run: npm test -- --test-name-pattern "times out" Expected: PASS

Step 5: Commit

git add skills/property-assessor/tests/assessment.test.ts
git commit -m "test: cover stalled discovery and photo extraction"

Task 2: Implement hard timeout guards in the live assessment path

Files:

• Create: skills/property-assessor/src/async-timeout.ts
• Modify: skills/property-assessor/src/listing-discovery.ts
• Modify: skills/property-assessor/src/photo-review.ts

Step 1: Write the failing test

Use the tests from Task 1 as the red phase.

Step 2: Run test to verify it fails

Run: npm test -- --test-name-pattern "times out" Expected: FAIL

Step 3: Write minimal implementation

Add:

• a shared timeout helper for async operations
• timeout-wrapped Zillow/HAR discovery in listing-discovery.ts
• timeout-wrapped Zillow/HAR photo extraction in photo-review.ts
• clear timeout attempt messages so the assessment can continue honestly

Step 4: Run test to verify it passes

Run: npm test -- --test-name-pattern "times out" Expected: PASS

Step 5: Commit

git add skills/property-assessor/src/async-timeout.ts skills/property-assessor/src/listing-discovery.ts skills/property-assessor/src/photo-review.ts skills/property-assessor/tests/assessment.test.ts
git commit -m "fix: fail fast on stalled property-assessor extraction steps"

Task 3: Tighten live skill instructions for WhatsApp-safe execution

Files:

• Modify: ../skills/property-assessor/SKILL.md

Step 1: Write the failing test

No automated test. Use the documented runtime rule as the spec:

• WhatsApp/messaging runs must avoid helper subprocesses for core analysis
• only the final PDF render attempt may use the helper subprocess path
• update? must remain status-only

Step 2: Run verification to confirm current docs are wrong

Run: rg -n "scripts/property-assessor assess|node zillow-photos|node har-photos|Good:" ../skills/property-assessor/SKILL.md Expected: current doc still presents helper commands as normal chat-safe core workflow.

Step 3: Write minimal implementation

Update the live skill doc to:

• prefer web_search, web_fetch, and bounded web-automation for core assessment
• forbid scripts/property-assessor assess, node zillow-photos.js, node har-photos.js, and ad hoc curl as the default WhatsApp core path
• allow a single final PDF render attempt only after a decision-grade verdict exists

Step 4: Run verification

Run: sed -n '1,220p' ../skills/property-assessor/SKILL.md Expected: the WhatsApp-safe runtime rules are explicit and unambiguous.

Step 5: Commit

git add ../skills/property-assessor/SKILL.md
git commit -m "docs: clarify whatsapp-safe property-assessor execution"

Task 4: Mirror the runtime guidance into the published repo docs

Files:

• Modify: docs/property-assessor.md
• Modify: docs/web-automation.md

Step 1: Write the failing test

No automated test. The spec is consistency with the live skill instructions.

Step 2: Run verification to confirm current docs drift

Run: rg -n "node zillow-photos|node har-photos|assess --address" docs/property-assessor.md docs/web-automation.md Expected: current docs still imply subprocess-heavy commands are the standard chat path.

Step 3: Write minimal implementation

Document:

• chat-native assessment first
• timeout-protected discovery/photo extraction behavior
• final-render-only subprocess attempt from messaging runs

Step 4: Run verification

Run: sed -n '1,220p' docs/property-assessor.md && sed -n '1,220p' docs/web-automation.md Expected: published docs match the live skill behavior.

Step 5: Commit

git add docs/property-assessor.md docs/web-automation.md
git commit -m "docs: document whatsapp-safe property assessment flow"

Task 5: Verify the focused runtime behavior

Files:

• Modify: skills/property-assessor/tests/assessment.test.ts
• Verify: skills/property-assessor/src/*.ts
• Verify: ../skills/property-assessor/SKILL.md
• Verify: docs/property-assessor.md
• Verify: docs/web-automation.md

Step 1: Run focused tests

Run: npm test Expected: all property-assessor tests pass, including timeout coverage.

Step 2: Run targeted source verification

Run: rg -n "withTimeout|timed out|final PDF render" skills/property-assessor/src ../skills/property-assessor/SKILL.md docs/property-assessor.md docs/web-automation.md Expected: timeout guards and the final-render-only messaging rule are present.

Step 3: Inspect git status

Run: git status --short Expected: only intended files are modified.

Step 4: Commit

git add skills/property-assessor/src/async-timeout.ts skills/property-assessor/src/listing-discovery.ts skills/property-assessor/src/photo-review.ts skills/property-assessor/tests/assessment.test.ts ../skills/property-assessor/SKILL.md docs/property-assessor.md docs/web-automation.md docs/plans/2026-03-28-property-assessor-whatsapp-safe-runtime.md
git commit -m "fix: make property-assessor safer for whatsapp runs"