# 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**

```bash
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**

```bash
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**

```bash
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**

```bash
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**

```bash
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"
```