# Cuely Cycle-Aware Re-Engagement Engine Specification Updated: April 29, 2026 This document defines Cuely's core re-engagement engine for six creative segments. It includes the segment timing model, reset and escalation behavior, onboarding flow, response tracking rules, and 18 ready-to-send email templates. ## Part 1. Segment Data Model ### 1.1 Shared Objects ```ts type SegmentConfig = { segmentId: | "wedding_photographer" | "motion_designer" | "podcaster_audio_producer" | "graphic_designer" | "video_editor" | "animator" displayName: string triggerEventDefinition: string timerStartLogic: string windowStartDays: number windowEndDays: number initialSendDay: number followUpOffsetsDays: [7, 14] doubleWindowDay: number resetConditions: string[] } type ClientCycleState = { clientId: string segmentId: SegmentConfig["segmentId"] lastProjectId: string timerStartedAt: string initialSendAt: string followUpOneAt: string followUpTwoAt: string beenAWhileAt: string cycleStatus: | "scheduled" | "sent_initial" | "sent_follow_up_one" | "sent_follow_up_two" | "engaged" | "booked_again" | "paused" | "opted_out" | "manual_review" highValueSilent: boolean } ``` ### 1.2 Global Timing Rules - `timer_started_at` is the project completion date for the most recent finished project with that client. - `initial_send_at = timer_started_at + windowStartDays` - `follow_up_one_at = initial_send_at + 7 days` - `follow_up_two_at = initial_send_at + 14 days` - `been_a_while_at = timer_started_at + (windowEndDays * 2)` - A new project completion always replaces the currently active timer for that client. - A new booking or in-progress job suppresses queued re-engagement emails until that job is completed or canceled. - A positive reply stops the active outreach sequence immediately and marks the client as engaged. ### 1.3 Segment Definitions #### Wedding Photographers - `segment_id`: `wedding_photographer` - Re-engage window: 10-11 months after completion - Trigger event definition: Project is considered complete when the wedding gallery has been delivered and any promised album or final exports are complete, or when the photographer manually marks the job as closed. - Timer start logic: Start the timer from the latest confirmed completion artifact for that wedding, in this priority order: `album_delivered_at`, `gallery_delivered_at`, `project_completed_at`. - Default send cadence: Initial email on day 304, follow-ups on day 311 and day 318. - Escalation if silent: If there is no reply after the second follow-up, keep the client in a silent state until day 670, then send the "been a while" email and raise a manual review flag if the client is high value. - Reset conditions: New family session, anniversary shoot, maternity session, referral shoot, or any newly booked project for the same client pauses the current cycle; the next timer starts only when that new project is completed. #### Motion Designers - `segment_id`: `motion_designer` - Re-engage window: 60-90 days after delivery - Trigger event definition: Project is complete when final motion files, source files, and approved exports have been delivered, or when the client has accepted the last revision round. - Timer start logic: Start the timer from the later of `final_delivery_at` and `final_approval_at`. If only one is known, use the known value. - Default send cadence: Initial email on day 60, follow-ups on day 67 and day 74. - Escalation if silent: If no reply arrives, keep monitoring until day 180, then send the "been a while" email and flag high-value clients for manual outreach. - Reset conditions: Any new motion brief, add-on asset request, versioning request, or new campaign booking pauses the current cycle and restarts timing when that new work is marked complete. #### Podcasters and Audio Producers - `segment_id`: `podcaster_audio_producer` - Re-engage window: 30-45 days after session - Trigger event definition: Session is complete when the final edited audio, mastered files, or published episode package has been delivered for that batch. - Timer start logic: Start the timer from the latest of `session_completed_at`, `final_audio_delivered_at`, or `episode_batch_delivered_at`. - Default send cadence: Initial email on day 30, follow-ups on day 37 and day 44. - Escalation if silent: If no reply arrives, queue the "been a while" email on day 90 and flag repeat clients with no reply as high-priority silent accounts. - Reset conditions: A new recording session, batch booking, retainer renewal, or recurring production schedule pauses the current cycle; a fresh timer begins after the newest batch is completed. #### Graphic Designers - `segment_id`: `graphic_designer` - Re-engage window: 60 days after delivery - Trigger event definition: Project is complete when the final approved design package has been delivered and the revision cycle is closed. - Timer start logic: Start the timer from `final_delivery_at`; if unavailable, use `project_completed_at`. - Default send cadence: Initial email on day 60, follow-ups on day 67 and day 74. - Escalation if silent: If no reply arrives, send the "been a while" email on day 120 and surface high-value silent clients for manual check-in. - Reset conditions: Any new collateral request, brand extension, packaging round, launch support request, or retainer restart pauses the current cycle and starts a new timer when the follow-on work is completed. #### Video Editors - `segment_id`: `video_editor` - Re-engage window: 45-60 days after delivery - Trigger event definition: Project is complete when the final approved cut, exports, and delivery assets have been handed off and there are no active revision requests. - Timer start logic: Start the timer from the later of `final_cut_delivered_at` and `final_approval_at`. - Default send cadence: Initial email on day 45, follow-ups on day 52 and day 59. - Escalation if silent: If no reply arrives, send the "been a while" email on day 120 and flag high-value silent clients for manual outreach. - Reset conditions: A new edit booking, trailer cut, social cutdown request, or ongoing content package pauses the current cycle and restarts the timer when the newest edit is completed. #### Animators - `segment_id`: `animator` - Re-engage window: 90 days after delivery - Trigger event definition: Project is complete when the final animation package, source project, and approved renders have been delivered. - Timer start logic: Start the timer from the later of `final_render_delivered_at` and `client_approval_at`. - Default send cadence: Initial email on day 90, follow-ups on day 97 and day 104. - Escalation if silent: If no reply arrives, send the "been a while" email on day 180 and create a manual review task for high-value silent clients. - Reset conditions: A new storyboard, revision round that becomes a new scope, sequel piece, product launch animation, or retainer booking pauses the current cycle and starts a new timer after the new work is completed. ## Part 2. Email Templates ### 2.1 Template Rules - Voice: personal, warm, and plainly written by the freelancer - Length: 60-110 words - Positioning: genuine check-in, never a hard sell - Reference style: lightly allude to the last job without sounding templated - Signature: use freelancer name or studio name only - Placeholders: - `[Name]` - `[Freelancer Name]` - `[Studio Name]` - `[project type]` - `[month/season]` - `[campaign / episode / brand / film / product]` ### 2.2 Wedding Photographers #### Initial Re-Engagement Subject: Heading into wedding season? Hey [Name], Hope you've both been well. I was just thinking about the wedding we worked on last [season], and it hit me that booking season has a way of showing up fast. If friends or family are planning something this year and need a photographer, I'd love to be top of mind. No pressure at all. Just wanted to say hi and send good thoughts your way. - [Photographer Name] #### Follow-Up If No Response Subject: One quick note before the season gets busy Hey [Name], Just bumping this once in case my last note got buried. This time of year usually turns into a rush for couples and planners, so if anyone around you is starting to put dates on the calendar, I'm happy to help if you want to point them my way. Either way, hope married life is treating you well. - [Photographer Name] #### Been A While Subject: Had your name come to mind Hey [Name], It's been a while, but I still think about your wedding whenever spring rolls around. I wanted to say hello and mention that I still keep a little room each year for past clients and the people they send my way. If anything comes up, I'd love to hear from you. Hope life has been full of good things since then. - [Photographer Name] ### 2.3 Motion Designers #### Initial Re-Engagement Subject: Still getting mileage out of those motion assets? Hey [Name], Hope things are going well on your end. I was thinking about the [campaign] package we wrapped a couple months back and got curious how it's been performing in the wild. If another launch, refresh, or cutdown is coming up, feel free to reach out. Happy to jump back in whenever it makes sense. - [Freelancer Name] #### Follow-Up If No Response Subject: Happy to extend that last set anytime Hey [Name], Sending one quick follow-up here. A lot of teams end up needing extra sizes, short social loops, or an updated version a few weeks after launch, so I wanted to keep the door open if that's where things are heading. No rush. Just wanted you to know I'm around. - [Freelancer Name] #### Been A While Subject: If another campaign is on deck Hey [Name], Been a minute since we worked on the last motion set together, so I wanted to check in. If you've got another campaign, product push, or internal rollout coming up, I'd be glad to help again. And if not, no worries at all. Just keeping in touch. - [Freelancer Name] ### 2.4 Podcasters and Audio Producers #### Initial Re-Engagement Subject: Are you batching again soon? Hey [Name], Hope the show has been rolling along well. I was thinking about the last batch we finished together and figured you might be getting close to planning the next run. If you're booking sessions again soon, I can make room. Happy to help keep things smooth on the production side. - [Freelancer Name] #### Follow-Up If No Response Subject: Kept a little room open Hey [Name], Just following up once in case the last note got lost in the mix. I know production calendars move fast once recording starts, so if you're about to batch another set of episodes, send me a note and I'll see what I can hold for you. - [Freelancer Name] #### Been A While Subject: If the show is picking back up Hey [Name], Wanted to reach out because it's been a while since our last session together. If the show is ramping back up, or if you need help getting a new batch cleaned up and out the door, I'd love to work together again. Either way, hope things are sounding good. - [Freelancer Name] ### 2.5 Graphic Designers #### Initial Re-Engagement Subject: How's the new brand settling in? Hey [Name], Hope you've been well. I checked in on the work we wrapped a little while ago and it was nice seeing it out in the world. Usually this is the point where new needs start popping up. Decks, social pieces, one-pagers, launch extras, that kind of thing. If anything's on your list, I'm happy to help. - [Freelancer Name] #### Follow-Up If No Response Subject: Easy add-ons if you need them Hey [Name], Just nudging this up once. After a rollout, teams often realize they need a few extra pieces that weren't obvious at the start. If that's happening on your end, feel free to send them over. Happy to keep the look consistent and make it easy. - [Freelancer Name] #### Been A While Subject: If something new is coming up Hey [Name], It's been a bit since the last round of design work, so I wanted to say hello. If you've got a launch, event, new offer, or refresh coming up, I'd be glad to jump back in. No pressure. Just making sure I'm easy to reach when the timing is right. - [Freelancer Name] ### 2.6 Video Editors #### Initial Re-Engagement Subject: Cutting anything new soon? Hey [Name], Hope things are going well. I was thinking about the last piece we wrapped and figured this might be around the time new footage is starting to pile up again. If another edit, round of cutdowns, or fresh campaign is on the way, feel free to send it over. I'd love to help again. - [Freelancer Name] #### Follow-Up If No Response Subject: Wanted to bump this up Hey [Name], Just giving this one bump. I know post gets hectic fast once assets start moving around, so if anything new is heading into edit, I'm around and happy to slot something in if the timing works. - [Freelancer Name] #### Been A While Subject: If another round of edits is coming Hey [Name], Been a little while since the last project, so I wanted to check in. If you've got something new in the pipeline, or even just need a hand finishing off a few pieces that have been sitting, I'd be glad to take a look. Hope all's been good on your side. - [Freelancer Name] ### 2.7 Animators #### Initial Re-Engagement Subject: How's that piece performing? Hey [Name], Hope things have been good. I was thinking about the animation we wrapped a few months back and got curious how it's been landing for you. If another product, update, or story could use motion, I'm around. Happy to build on what we already started whenever the timing makes sense. - [Freelancer Name] #### Follow-Up If No Response Subject: Happy to build on the last one Hey [Name], Just following up once here. Sometimes one animation turns into a second version, a shorter cut, or a whole new piece once the first one has had time to do its job. If that's happening on your end, I'd be glad to help. - [Freelancer Name] #### Been A While Subject: If another story needs motion Hey [Name], Wanted to say hello since it's been a while after the last animation project. If another launch, explainer, or campaign could use motion, feel free to reach out anytime. I'd love to work together again when the right thing comes along. - [Freelancer Name] ## Part 3. Onboarding Flow Specification ### Step 1. Segment Selection - Screen goal: Identify the user's creative segment so Cuely can attach the correct timing rules and email defaults. - User inputs: Primary segment, optional secondary segment for future unlocks, business name, sending name. - System behavior: Load the correct `SegmentConfig`, preview the default timing window, and show two example subject lines for that segment. - Success state: User confirms "This matches how my projects usually cycle." ### Step 2. Inbox Connection Or Manual Client Import - Screen goal: Get historical client data into Cuely. - Options: Gmail OAuth, Outlook OAuth, CSV import, or manual entry. - Minimum data required per client: Client name, email address, most recent project completion date, and project type. - System behavior: Normalize imported contacts, deduplicate by email, and attach a `source_confidence` flag. - Success state: User sees import results with counts for `imported`, `needs review`, and `skipped duplicate`. ### Step 3. First Client Entry And Timer Assignment - Screen goal: Teach the user the timer model on a single real client before bulk automation begins. - User inputs: Client name, last project name, completion date, optional project value, and optional notes. - System behavior: Calculate `timer_started_at`, `initial_send_at`, follow-up dates, and `been_a_while_at` from the chosen segment. - Success state: User sees a clear timer card with the exact dates Cuely will act. ### Step 4. Preview First Re-Engagement Email - Screen goal: Let the user confirm tone before anything sends. - User inputs: Preferred sign-off, minor template edits, optional personalization tokens, optional exclude phrases. - System behavior: Pre-fill the segment's initial template, inject client name and project context, and show a plain-text email preview. - Success state: User approves the draft or saves edits as their segment default. ### Step 5. Confirmation And Go-Live - Screen goal: Make the first automation feel explicit and reversible. - User inputs: Send mode (`automatic` or `approve before send`), quiet hours, unsubscribe footer preference. - System behavior: Activate timers, queue eligible emails, and show the first scheduled send date on the confirmation screen. - Success state: User lands on a dashboard that shows `next send`, `silent high-value clients`, and `clients awaiting review`. ## Part 4. Logic Specification ### 4.1 Cycle Detection - Cuely treats `project completion date` as the canonical timer anchor for every segment. - Completion date can come from one of four places: 1. Manual user entry 2. Inbox-derived delivery signal 3. CSV import field 4. CRM or job import in later versions - If multiple completion candidates exist, Cuely uses the most reliable segment-specific completion field and stores the raw source. - If the exact date is uncertain, Cuely still creates the timer but marks the record `needs_review` and shows the user the guessed date before sending. ### 4.2 Multiple Projects Per Client - Each client can have many projects, but only one active re-engagement timer per segment at a time. - When a new project is completed: - Archive the previous active timer - Mark the old cycle as `superseded_by_new_completion` - Create a new cycle using the new completion date - If a client books new work before the scheduled re-engagement email sends: - Stop the queued email - Mark the cycle `booked_again` - Wait for the new project to complete before starting another timer - If two projects complete close together, Cuely uses the most recent completion date and does not send two overlapping sequences. ### 4.3 Response Tracking - Positive response counts as any of the following: - Direct reply expressing interest - Ask for pricing, timing, or availability - Referral introduction to someone else - Calendar booking or discovery call booked from the thread - New project or invoice created within 30 days of the email - User manually marks the thread as positive - Neutral response counts as: - Friendly acknowledgement with no immediate need - "Maybe later" with no timeline - Negative response counts as: - Explicit no - Opt-out or unsubscribe - Bounce or invalid inbox - Positive and neutral replies stop the follow-up sequence. Negative replies also suppress future automation unless the user overrides it. ### 4.4 High-Value Silent Clients - A client should be flagged `high_value_silent` when they meet at least one value rule and have not replied after the second follow-up. - Recommended value rules: - Top 25 percent of lifetime revenue for that freelancer - Two or more completed projects - Manually starred as VIP - When a client becomes `high_value_silent`, Cuely should: - Pin them to the dashboard - Recommend a manual nudge or phone/text outreach - Delay further automation until the "been a while" send ### 4.5 Escalation At 2x Window - At `been_a_while_at`, Cuely sends the segment's final low-pressure check-in email. - The client is simultaneously moved into `manual_review`. - If there is still no reply 14 days after the "been a while" email: - Stop automated sends for that cycle - Keep the client visible in a dormant list - Restart only when a new project is booked or completed, or when the user manually starts a fresh outreach cycle ### 4.6 Sending Safeguards - Never send if the client has replied in the last 21 days. - Never send if there is an open active project. - Never send outside user-defined quiet hours. - Always include a plain-text off-ramp such as "If the timing's off, no need to reply." - If a user edits a completion date after the timer has started, Cuely recalculates all future send dates immediately. ## Recommended MVP Acceptance Criteria - All six segments have fixed timing rules and default templates. - User can import a client, assign a completion date, and see exact send dates. - Every client cycle can move through `scheduled`, `sent`, `engaged`, `booked_again`, `manual_review`, and `opted_out`. - High-value silent clients are visible without extra filtering. - Every template can be edited before go-live.