Follow-up engine investigation — 2026-09-20

Superseded (2026-10-08): the follow-ups design and roadmap now live in the one long-term vision page — Clara platform vision, Pillar 4. This page is kept as background evidence only.

Investigation only — nothing is being built. Hand-off to a future session.

Proposed — pending review (2026-10-08): the first section is now the vision and roadmap for context-aware follow-ups: one check before every automatic message, what it would have caught, honest test results, and the build order. Section 7 is the longer write-up of the same fix. Sections 1–6 are the earlier investigation.

What the follow-up (nudge) engine does today, what it ignores that we already know, and the shape of the work a future session would build — with the decisions that need Fede first.

Investigation only · 2026-09-20 · code read at ~/.claude/propflowai-gc-replay3 (main @ 43002444db, read-only) · numbers from live reads of DynamoDB propflow-prod (us-east-1) · every behaviour claim cites file:line

Context-aware follow-ups: vision and roadmap — Decided for the tour check-in (2026-10-14); prospect follow-ups still proposed · 2026-10-08

Decided 2026-10-14 (Fede): a scheduled touch never sends blind from a timer. The timer wakes Clara's loop for that conversation with no text; the loop reads the thread and decides whether to send, skip, or close. First instance: the staff tour check-in (origin: Kat gave Natalie Haynes's tour notes at 12:48 PM and the 2:00 PM "how was the tour?" check-in fired anyway). Prospect follow-ups move to the same pattern next. PR: pending.

1. The problem

Greg was handed to Kat on a call, toured, and was applying. Clara still texted him “Would love to have you come by.” Six different senders each decide on their own, and none sees the whole picture.

2. Vision: one check before every automatic message

Every sender joins the same check: no-reply follow-ups, follow-ups after a reply, first replies to listing inquiries, tour messages, texts after a call, escalation callbacks.

No new lists or timers: a staff promise like “I’ll resend the application” is context the check reads, never a reminder.

Shares one reader with the platform vision; the shared reader and staff-alert model live there. Any text written from tour or staff notes goes through the same staff-only filter.

3. What would have caught the real bad texts

So AppFolio notes matter; we just haven’t labeled with them yet.

4. Test results, honest

The 19 is not trustworthy yet. The test cut long messages at 500 characters (7 cases), and the “should send” labels were set without AppFolio notes, so some “wrong skips” may be right. Fixing the test comes first.

Weak spot: JP&Co tricky leads (7–8 of 16 wrongly skipped).

5. Roadmap, most impactful first

6. Bugs found along the way

Separate, small, and each needs Fede’s go.

• Follow-up emails skip the “a human took over” check that texts get.
• A tour text that gets blocked is still recorded as sent, so the reminders after it start anyway.
• Not ours: Greg’s application on a separate record is identity matching (platform vision lane).

7. Decision

1. How the engine works today (10 lines)

1. Trigger. One entrypoint, onProspectEngaged() — src/lib/domain/leasing/outreach-trigger.ts:319. Fired after Clara's first reply on a text/email turn (agents/clara/lib/agent/conversation-manager.ts:13587), after a leasing call ends (src/app/api/voice/call-ended/route.ts:2460), and by a nightly self-healing reconciler (outreach-reconcile.ts:609,740,825).
2. Steps. Four SMS touches at +24h, +48h, +7d, +14d from the anchor — src/lib/domain/leasing/outreach-cadence-schedule.ts:101-106. Step 1 of the "5-step" story is Clara's first reply, sent outside the cadence.
3. Channel. Every step is prefer_sms; falls back to email only if no texting consent, and is dropped entirely if neither exists — resolve-outreach-channel.ts:75-110.
4. Timing guards. 20h minimum real gap between sends (outreach-cadence-schedule.ts:53), quiet hours 8am–9pm property-local (prospect-outreach-workflow.ts:349,418), 12h cooldown if anything else already texted that person (autonomous-outreach-cooldown.ts:26,125).
5. Per-property gating: none. Removed 2026-07-27 (outreach-trigger.ts:12-17). The only operator lever is an org-level cadence editor that sets step delays/channels — FOLLOWUP#<orgId> / CADENCE#<scenarioId> (followup-cadence-overrides.ts:24), states default | custom | disabled.
6. Stop conditions — exactly three reasons. outreach-stop-conditions.ts:47: 'applied' | 'tour_booked' | 'closed'. Applied = appliedAt, householdAppliedAt, or stage applied/approved/lease_signed (:67-71). Tour booked = stage tour_pending/tour_confirmed, or any tourId that isn't cancelled (:82-84). Closed = stage rejected or not_interested (:90). A cancelled tour deliberately restarts the cadence (:94).
7. Plus operational skips (don't stop the cadence): no consent, no phone, no mailbox, suppression list, cooldown, merged/deleted prospect — full union at src/lib/temporal/activities/prospect-outreach.ts:156.
8. Copy is LLM-written, not hardcoded. Haiku, 120 tokens for SMS, temp 0.7, no tools — generate-followup-message.ts:447-549, called from prospect-outreach.ts:786,936. The hardcoded strings (src/lib/i18n/templates.ts:965-1001) are safety fallbacks only.
9. But it is told it knows nothing. The prompt explicitly states it has no inventory (generate-followup-message.ts:408-411), and anti-fabrication guards force the generic fallback if the copy names a price, a unit type, a policy (vouchers/income/evictions), or a tour time (:123-125, :214-215, :225-241, :259-264).
10. What it actually sees per touch — prospect-outreach.ts:656-662: first name, property name, touch index, desiredBedrooms, desiredMoveIn, days since inquiry, Clara's own summary notes (aiNotes), language, and an optional grounded price drop. That's the whole context.

2. What it ignores that we already know

The guest card carries these and the follow-up never reads any of them:

Two structural gaps behind this:

• "We told them the home is gone" has no durable record. It is a prompt mandate to say the exact phrase (agents/clara/lib/prompts/clara-email-core.ts:393-405) plus message text. No attribute, no reason code. Answering it later means re-running resolveListingCardForReply or grepping the message body.
• Tour completed / no-showed is not an event. src/lib/domain/insights/signals/tour-no-show.ts:7-13 says so outright; only a 14-day non-conversion proxy exists. So "toured and went quiet" and "booked and never came" look identical.

3. Camellia numbers (prod, propflow-prod, property 1773625953462 / org_jpco)

Population, last 60 days (inquiries with inquiryDate >= 2026-07-22, query: GSI phone-index, GSI1PK=PROPERTY#1773625953462, begins_with(GSI1SK,'INQUIRY#')):

• 171 inquiry rows all-time; 73 in the last 60 days.
• 63 of the 73 were enrolled in a cadence (outreachCadenceAnchorIso present); 66 have claraEngagedAt.
• Cadence outcome: replied 46, completed 13, applied 1, none 13. So ~63% of enrolled leads answered before the cadence ran out.
• 24 of the 73 actually received a touch. 60-day touch ledger: 67 touch rows, 62 sent, 5 skipped — all 5 cooldown, zero other skip reasons.
• Sent by step: step 1 20, step 2 15, step 3 12, step 4 12; plus 3 stage-2 re-engagement touches.
• Re-engagement lane (the "replied then went dark" cadence): 35 of 73 enrolled; outcomes tour_booked 15, replied 7, suppressed 8, applied 2, exhausted 1.

To reach a ≥30 sample I widened to every touched prospect in the table (34, inquiries 2026-06-01 → 2026-09-18). Classification of the state each prospect was in at their first touch, from the conversation transcript (PK=CONV#<id>, SK prefix MSG#) plus the inquiry row:

Touches that went to a plainly-dead lead or one we had already said no to: 0 of 62. The three stop conditions that exist are working. Camellia does not exercise the failure mode Fede is worried about — and that is the finding: Camellia is one building with fungible studios and 1-beds, so "the home they asked about" never goes away. Western Slope, scattered single-family homes, has no equivalent safety.

Five concrete examples (record ids are ProspectInquiry.id; key PK=PERSON#<personId>, SK=INQUIRY#<id>):

1. c247fb86-edc5-4afd-a773-62e086ffb49e (Erling, Apartments.com, 2026-08-30). His lead said "(Unit 524/Model 1BR/1.0BA) … particularly on the 5th floor." The +24h touch said: "Thanks for reaching out about a 1-bed with us." Unit 524 and the 5th floor vanish. He booked a tour off the second touch. The cadence worked — it just threw away the one thing he told us.
2. d2123015-fcfd-5e7e-8247-4728ccd41f35 (Crystal, Zillow, 2026-09-14). Two generic touches; she replied to the second and booked. Touch 2 said "check in and see if you had any questions about us" — no reference to the studio/1BR pricing Clara had quoted her by email a day earlier.
3. da49aa9e-18b2-43a8-9c38-c32cb5affdac (Sumanth, 2026-08-01). Asked "how much time from Union Station". The follow-up: "we'd love to show you around in person." The distinctive thing he cared about is not referenced.
4. aa4f20e9-2e37-4e8c-a0f8-d6b07bcc7ba6 (Daniel Brehm, 2026-08-25). The one voucher case. He was told at his tour that we don't take vouchers; Clara corrected it the same evening ("Camellia absolutely accepts housing choice vouchers"), then walked it back, then confirmed. No touches followed — the tour had already stopped the cadence. Not harm; it is the case that shows voucher status is never a stored fact (guest-card-note-classifier.ts:191 forces it internal-only as a protected class).
5. fe11da47-dfd7-411d-8a21-b363a198d7e0 (Summer, 2026-08-31). Clara told her parking is full with a waitlist, then sent all four generic touches. The follow-ups never acknowledge the one friction point in the thread.

The real repetition defect is in the post-tour chase, not the cadence. 16 of 77 Camellia tours received ≥2 post-tour "did you apply?" chases and 13 received exactly 3 (Tour.postTourChasesSent, types.ts:11910). Those three messages are byte-identical. Two proven cases, from PK=CONV#<conversationId> / SK prefix MSG#:

• prospect da49aa9e-18b2-43a8-9c38-c32cb5affdac (Sumanth), tour TOUR# on person pers_…, date 2026-08-03 — identical text at 2026-08-04T23:30Z, 2026-08-06T23:30Z, 2026-08-10T23:30Z: "Hi Sumanth, it's Clara from Camellia Apartments! Did you get a chance to apply? You can start here whenever you're ready: https://www.camelliadenver.com/#floor-plans Happy to answer any questions."
• prospect c247fb86-edc5-4afd-a773-62e086ffb49e (Erling), tour 2026-09-04 — same sentence at 2026-09-05T18:00Z, 2026-09-07T18:00Z, 2026-09-11T18:00Z.

No coworker sends the same sentence three times.

Scope note: cadence state exists in four prod orgs — org_jpco 87 inquiries, org_53047a06-…9149a 46, org_c42d9150-…acf38 15, org_sandbox 290 (full-table scan, 1.6M rows, filter entityType=ProspectInquiry). Western Slope's real org has no cadence traffic yet; only org_ws_mirror_test (2). So today's engine has been proven on exactly one building.

4. Do-not-re-engage scenarios, and how to detect each from data we already have

Ordered by how often they will bite Western Slope. "Buildable today" means every input already exists in prod.

4b. Lead fit — the thing Camellia never needed

Camellia never needed this because "everyone can just apply to the community". Western Slope is different asset types and you have to match a person to a home, so "there has to be some basic logic of: are they even eligible, do we match them to something they want, are they a good fit… if we're not what they're looking for, we shouldn't be just following up blindly."

Fede, 2026-09-20

Ruling (Fede, 20 Sep 2026, 5 PM, after the team sample below): a short-term lease ask is answered with one sentence that it is something they can check with the leasing team, plus the usual tour invite and one note on the card. Clara does not state that 12 months is standard and does not say no; the lead is followed up normally. The broader 'a policy no filters the funnel' idea below stays provisional for other criteria (income, pets, credit). When the client's knowledge base answers a lead's ask—for example, a six-month lease at Western Slope, whose policy is 12 months standard with 14–18 month promotional terms at Ember Estates—Clara answers flat in one sentence with no deferral, leaves one plain note on the guest card ("Asked for a six-month lease; told them we don't offer it, 12 months standard"), nothing routed, no task, no alert, and the follow-up cadence does not chase that lead. Humans see the note only if they open the card. The same rule covers every objective policy or screening criterion the client gave us (income at about twice the rent, pets, credit or rental history): when a lead's message shows they don't meet it, Clara says so plainly so they don't waste time applying and getting declined. The one exception is fair housing: Clara never pre-screens on protected characteristics or source of income; a voucher or any lawful income counts as income, and on a judgment call she states the criterion and lets the lead decide. "we're helping filter the funnel to connect people only that match our policies to our open homes." (Fede, 2026-09-20) Sequenced after home matching (Lane B3).

What the team actually does today (full count, 20 Sep 2026)

Coverage: Western Slope — 1,226 guest cards read (~96% of all of 2026); 49 cards from Sep 9–19, 2026 could not be pulled (login/2FA gap, open follow-up). Situs Group — all 1,641 known cards captured, 1,096 of them in the 12-month window.

The earlier sample undercounted because it only looked for a short-lease ask written in the prospect's prose and ignored the lease length the renter picks on the Zillow / Apartments.com / Rent.com inquiry form itself — that field is the renter's own choice, not a system default, and this recount treats every value under 12 months as a real ask.

Reasons volunteered for wanting a short lease (Western Slope only — Situs Group had no genuine short-lease asks to attach a reason to):

• K.: just sold their home and need a place to call home base until they buy their next property.
• C.: self-employed, building a house, sold their current home unexpectedly fast.
• M.: expecting a baby, wants a safety-net month-to-month.
• R.: wanted a furnished unit — the short term was a byproduct of needing furnished, not relocation.

• When the Western Slope team actually engages the term (8 of 14 cases), it almost always says yes — usually month-to-month at +$150/month or a reduced move-in concession — it never gives a hard no.
• Situs Group shows zero genuine short-term asks in a full year of cards.

(a) Three levels, and where each input lives today

Two blockers worth naming: targetHomeAddress lands on effectively zero live cards because resolveGuestCardHome answers no_roster for every currently-live property (guest-card-home.ts:94-109), and there is no store today that can answer "what is the cheapest open WS home" — the corpus carries no rents and the org listings ledger isn't populated for WS.

(b) Counts on the real Western Slope corpus

Source: ~/.claude/guest-card-corpus/option-d/western-slope/guest-cards.json — 908 AppFolio guest cards, org_western_slope, pulled 2026-09-20 (the "50" is propflowMirrorRows, the PropFlow-side mirror subset). 290 carry free text (message, notes or inquiry message). Plus the 51-card 2026 prod replay set in raw/western-slope-dataset.json.

What the WS knowledge base actually says about lease terms

Do not assume 12-month-only. The client's own approved answer (western-slope-knowledge-gold-set.json, rawAnswers rank 10007, factKey: knowledge.lease-length), verdict "Wrong" with the client's correction:

"12 months is the standard lease term. Shorter terms, like 6 or 10 months, are actively offered as an alternative depending on the applicant's situation, usually with a smaller move-in incentive than a full 12-month lease gets. Going month-to-month after your lease ends adds $150 a month on top of rent."

client correction: "this is mostly correct however at ember estates for our promotional offering we are doing longer term leases of 14 18 months."

The short approved company entry says only "Lease length :: 12 months standard.", and the one property override is Ember Estates :: "Longer leases of 14 to 18 months currently offered as a promotion."

So a six-month ask at Western Slope is not a rule violation — it is an "ask the team" case, and the condensed company entry is what would make us wrongly say no. That is an argument about the shape of the knowledge entry as much as about the engine.

(c) How fit should drive the first reply and the follow-up

• Not eligible under a hard rule (a real one — smoking indoors, pets at 632 Hill, occupancy over the limit): answer honestly in the first reply, name the rule, offer the alternative if one exists, do not enrol in a cadence at all. Record the refusal as a signal (Lane A1) so nothing else re-engages them.
• Matched — there is an open home fitting beds / budget / move-in / area: enrol as today, but every touch names the matched home, and the cadence stops the moment that home is gone (Lane B1) rather than nudging about it.
• Eligible but unmatched — right person, nothing open: the honest first reply already exists (the Ethan reply above is close to right). The follow-up should be event-driven, not calendar-driven: no +24h/+48h nudge, one "I'll watch for you" close, then a touch when a matching home opens. This is a different trigger shape from the Temporal timer cadence and is the largest piece of the hand-off.
• Ambiguous / needs the client (six-month lease, unusual occupancy, a pet the policy doesn't cover): keep the lead open, answer with what we do know, escalate once, and never chase on a day timer while an unanswered question is outstanding — reengagementSuppressedSignal = 'we_owe_reply' (types.ts:18917) already models exactly this, in the wrong lane.

5. The dynamic-follow-up opportunity

The copy generator already has slots for most of this; the outreach activity simply doesn't fill them. Five things a touch could say, and where the data is:

One constraint to design around: the anti-fabrication guards will reject any of this unless it is passed as grounded system data. Naming a unit type falls back today (:225-241); naming a price falls back unless it matches a grounded priceDrop (:164-182). So "make the copy dynamic" is really "widen the grounded-context contract", not "loosen the prompt".

6. Rough shape of the work (for the hand-off, NOT underway)

Fede, 2026-09-20: this is investigation only; no PR from this list exists or is authorized.

Contract-first, each ≤~300 lines, one concern, each dark and mergeable alone.

Lane A — signals (write the facts down)

• A1 · ProspectOutcomeSignal on the inquiry row: { kind, atIso, detail } for told_home_gone, said_no_pets, said_no_budget, said_no_bedrooms, said_no_move_in. Type + writer + no readers. ~150 lines.
• A2 · Stamp told_home_gone where Clara is already forced to say the phrase (the resolveListingCardForReply → kind:'none' path). ~120 lines.
• A3 · Lift the stage-2 reply classifier (reengagement-intent.ts) into the stage-1 lane so not_interested / we_owe_reply are detected on any reply, not just post-engagement. ~200 lines.
• A4 · A homeStillAvailable(inquiry) helper that works for building properties too (today listing-card-for-reply.ts:124 short-circuits). ~180 lines.

Lane B — decision (stop the wrong touches)

• B1 · Widen OutreachStopReason from 3 to N and add the signal-driven reasons. Fixes to live behavior ship with no switch and go live everywhere once proven (Fede, 2026-09-30); see section 7. ~200 lines.
• B2 · Move-in date elapsed → stop. ~80 lines.
• B3 · "Nothing in the portfolio matches" → hold rather than stop, with the stale-roster refusal (null) never read as "nothing". ~200 lines.

Lane C — copy (make it worth reading)

• C1 · Fill the slots the prompt already has: petsMentioned, source, inquiryDate. ~100 lines.
• C2 · Pass the named home + its current state as grounded context, and widen the anti-fab whitelist for exactly that address. ~250 lines.
• C3 · Pass conversationTail in the stage-1 lane (the field exists). ~120 lines.
• C4 · "A new home that matches" touch: matched-home context from the offerable roster. ~250 lines.
• C5 · Kill the identical 3× post-tour chase — route it through the generator with per-touch angles. ~150 lines.

Proof for every PR: replay through the existing guest-card corpus + judge (/guest-card-regression), each check shipping with a planted-violation control.

Decisions for Fede (multiple choice, recommendation in bold)

D1 — When the home they asked about is gone and they never answered, what happens?

• (a) Stop the cadence entirely.
• (b) Keep going, but the next touch leads with similar homes instead of "still interested?" — and if there is nothing similar, stop.
• (c) Stop only if we already told them it was gone; otherwise tell them now.

→ Recommend (b). A scattered-site lead who wanted one house usually wants a house. Stopping loses a real lead; nudging about a dead house is the embarrassment. (b) avoids both, and (c) folds into it.

D2 — When we said no to a hard requirement (pets, bedrooms, budget, date), what happens?

• (a) Stop permanently.
• (b) Stop, but re-open automatically if a home that clears the requirement comes up.
• (c) Keep nudging.

→ Recommend (b). It is the only one a human would do, and the inventory read it needs is the same one D1(b) needs.

D3 — Where do these rules live?

• (a) Hardcoded engine behaviour, same everywhere.
• (b) A per-company setting on the company page, default on.
• (c) A per-property setting.

→ Recommend (a), shipped dark then defaulted on. These are not preferences, they are correctness — no customer wants a text about a house that's gone. Per the no-engineering-flags rule, ship it merged and dark as a company setting, turn it on per customer, then retire the setting once it's proven.

D4 — How dynamic should the copy get before we trust it?

• (a) Bedrooms/move-in/pets only — facts they typed, zero inventory claims.
• (b) (a) plus the named home and its current state.
• (c) (b) plus proactively pitching new matching homes.

→ Recommend (b) first, (c) right behind it, both graded on the guest-card corpus before anything is turned on. (c) is where the value is, but it is the first time a follow-up asserts inventory, so it needs the corpus judge at the same bar we used for the guest-card replies (0 do-not-send, ≥90% send-as-is).

D5 — The six-month-lease class (a card asks for something the condensed rule says we don't do).

• (a) Hard no per the client's rule — "our leases are 12 months."
• (b) Say the standard is 12 months and ask if that works; keep the lead open; do not chase on a day timer.
• (c) Escalate the question to the client once, answer the lead with what we do know, and store their answer as a knowledge-base fact so it is answered automatically next time.

→ Recommend (c), with (b) as the wording we use while we wait. The prod data settles it: Western Slope's own approved answer says shorter terms "like 6 or 10 months, are actively offered as an alternative depending on the applicant's situation" — so (a) would have given a wrong hard no to card 2943, a lead who could prove six months of funds. Two cards in 908 asked this, which is too few to justify a rule engine and exactly the right volume for ask-once-and-remember. It also fixes the class, not the case: every "does the client allow X?" gap lands in the same place, visible and explicit the way Fede asked ("keep it very on"), instead of Clara guessing in either direction.

Two things the hand-off session must not assume

• Camellia proves nothing about this. Zero of 62 touches hit a dead lead there. The whole design is for scattered single-family homes, so the acceptance test has to be a Western Slope / Situs replay, not a Camellia regression.
• Lead fit needs an inventory read that does not exist yet. No store we can query holds Western Slope's open-home rents, so "matched" is unbuildable until the org listings ledger is populated for WS. Lane B3 and D1(b) both depend on it.
• targetHomeAddress is effectively empty today (guest-card-home.ts:94-109 answers no_roster for every live property). Lane C2/C4 are blocked on that landing first — worth confirming before sequencing.

7. Context-aware follow-ups — Proposed, pending review · 2026-10-07

Clara sometimes texts “come see the home” to people staff already talked to, toured, or who already applied. This section proposes making follow-ups aware of that.

The story: Greg, Western Slope, Oct 6–8

Smallest version to start

How follow-ups work today

Signals: what we have, what follow-ups use

How often (last 30 days)

• Follow-up texts sent: Western Slope 70, JP&Co 34, our own test properties 83 (not customers). Situs and ConAm: none in the window.
• At Western Slope, at least 11 went out after a human call or a completed tour (estimate; the tour part is inferred).
• 1 went to someone who had already applied (Greg; found by name match, so it is a floor).

Measured: the texts and their timing. Estimated: “completed tour” and “same person.” Not covered: leads with no saved thread.

Options (pick one)

Proof plan

A test harness (being built now) replays Greg, Tessa and the other Western Slope cases with the expected outcome for each (skip, or send with the right content), and compares today’s behavior to the proposed one. Every check gets a planted-violation control.

Harness results (2026-10-07)

• Today sends to every lead staff already handled — it can’t see staff calls, tours or applications.
• The conversation text alone carries the signal: an AI-only version of the proposal also scored 18/18.
• Caveat: 18 cases, and the skip cases come from the same incidents that prompted the design; the AI grader wavered on one send case. More cases before shipping.

Two related bugs

• Dropped reply: when Clara writes a good reply and then calls a tool, a short closer like “let me know if there’s anything else” can ship instead; the safety check only restores replies that contain a link or a dollar amount.
• Application on a separate record: an applicant with a new phone and email becomes a new person; we correctly do not merge on name alone, so something else must connect them.