Skip to content

SMART_JOBS_EXPLAINED.md

Latest commit

 

History

History
274 lines (199 loc) · 7.89 KB

SMART_JOBS_EXPLAINED.md

File metadata and controls

274 lines (199 loc) · 7.89 KB

Smart Job Execution - How It Works

Overview

The Mesh Financial Coach uses intelligent job execution that adapts to each user's actual progress. Jobs don't blindly send reminders—they check the user's current state and send contextually appropriate messages.

The Problem We Solved

Without Smart Execution ❌

Day 0: User completes Module 1
Day 7: Job fires → "Have you completed Module 1?"
User thinks: "I already did this a week ago! Is the system broken?"

With Smart Execution ✅

Day 0: User completes Module 1
Day 7: Job fires → Checks progress → "✅ Well done! You've already completed this module."
User thinks: "The system knows my progress and is encouraging me!"

How It Works

Step 1: Job Fires (Scheduled Time Reached)

// Job was created 7 days ago
// Now it's time to execute
execute: async (job) => {
  // Job has metadata about what it was supposed to remind about
  const targetLevel = job.metadata.userLevel;      // e.g., 1
  const targetModule = job.metadata.targetModule;  // e.g., 1

Step 2: Check User's Actual State

  // Get the user's CURRENT state
  const user = await job.user();
  const currentLevel = user.current_level || 1;
  const habitTracking = user.habit_tracking || {};
  
  // Check if the target module is complete
  const moduleKey = `level${targetLevel}_mod${targetModule}_complete`;
  const isModuleComplete = habitTracking[moduleKey] === true;
  
  // Check if user has leveled up past this
  const hasLeveledUp = currentLevel > targetLevel;

Step 3: Adaptive Message Selection

  if (hasLeveledUp) {
    // User advanced past this level entirely
    message = "🎉 Great progress! You've advanced to Level ${currentLevel}...";
    
  } else if (isModuleComplete) {
    // Module is done, send encouragement
    message = "✅ Well done! You've already completed this module...";
    
  } else {
    // Module still incomplete, send reminder
    message = "💡 Level 1, Module 1 Reminder: Have you opened your business account?";
  }

Step 4: Send Appropriate Message

  await user.send([{ type: "text", text: message }]);
  await user.update({ last_ping_date: new Date().toISOString() });
  
  return { success: true };
}

Three Types of Job Responses

1. Reminder (Module Incomplete)

When: User hasn't completed the target module yet

Message: Original reminder specific to that module

Example:

"💡 Level 1, Module 1 Reminder

The Separation Rule is the foundation of financial clarity. 
Have you opened and begun using your separate business bank account?"

Why: User needs a gentle nudge to complete the work

2. Encouragement (Module Complete)

When: User already completed the target module

Message: Acknowledgment and encouragement

Example:

"✅ Well done! You've already completed this module. 
You're making steady progress on Level 1!"

Why: Acknowledges their progress and keeps them motivated

3. Congratulations (Leveled Up)

When: User has advanced past the target level entirely

Message: Celebration of their overall progress

Example:

"🎉 Great progress! You've advanced to Level 2. 
Keep up the excellent work on your financial journey!"

Why: Recognizes major achievement and maintains momentum

Advanced: Next Steps Detection

For progress check jobs (after module completion), there's even more intelligence:

if (isComplete) {
  // Find what's ACTUALLY next for them
  const nextIncomplete = [1, 2, 3].find(mod => {
    const key = `level${targetLevel}_mod${mod}_complete`;
    return habitTracking[key] !== true;
  });
  
  if (nextIncomplete) {
    // Tell them about the next module
    message = `✅ Great work completing Module ${targetModule}! 
               Ready to tackle Module ${nextIncomplete}?`;
  } else {
    // All modules complete - suggest level up
    message = `🎉 You've completed all modules at Level ${targetLevel}! 
               Ready to level up? Let's chat about your next steps.`;
  }
}

Example Scenarios

Scenario 1: Fast Learner

Timeline:

  • Day 0: Assessment → Level 1 assigned → Job created for Day 7
  • Day 2: Completes Module 1
  • Day 3: Completes Module 2
  • Day 4: Completes Module 3 → Levels up to Level 2!
  • Day 7: Job fires
    • Checks: Target was Level 1, user is now Level 2
    • Sends: "🎉 Great progress! You've advanced to Level 2..."

Result: No redundant reminder, just celebration!

Scenario 2: Steady Pace

Timeline:

  • Day 0: Assessment → Level 1 assigned → Job created for Day 7
  • Day 3: Completes Module 1 → Job created for Day 10
  • Day 7: First job fires
    • Checks: Module 1 complete
    • Sends: "✅ Well done! You've already completed this module..."
  • Day 10: Second job fires
    • Checks: Module 2 incomplete (target was Module 2)
    • Sends: "📸 Level 1, Module 2 Reminder: Have you set up digital capture?"

Result: One encouragement, one actual reminder!

Scenario 3: Took a Break

Timeline:

  • Day 0: Assessment → Level 1 assigned → Job created for Day 7
  • Days 1-6: No activity
  • Day 7: Job fires
    • Checks: Module 1 incomplete
    • Sends: "💡 Level 1, Module 1 Reminder: Have you opened your business account?"

Result: Gentle reminder after a week of inactivity

Scenario 4: Already Ahead

Timeline:

  • Day 0: Assessment → Level 1 assigned → Job created for Day 7 (Module 1)
  • Day 2: Completes Module 1 → Job created for Day 9 (Module 2)
  • Day 4: Completes Module 2
  • Day 7: First job fires (was for Module 1)
    • Checks: Module 1 complete
    • Sends: "✅ Well done!..."
  • Day 9: Second job fires (was for Module 2)
    • Checks: Module 2 complete, Module 3 incomplete
    • Sends: "✅ Great work completing Module 2! Ready to tackle Module 3?"

Result: Both jobs detect completion and provide relevant next steps!

Why This Matters

Better User Experience

  • ❌ Without: "Why is it asking me about something I already did?"
  • ✅ With: "It recognizes my progress and encourages me!"

Respect User's Pace

  • Fast learners aren't annoyed by outdated reminders
  • Slow learners get gentle nudges without judgment
  • All users feel the system "understands" them

Maintains Engagement

  • Acknowledgment keeps users motivated
  • No feeling of "falling behind" on old tasks
  • Messages always feel relevant and timely

Reduces Confusion

  • No conflicting messages about completed work
  • Clear sense of current status
  • Smooth progression through levels

Technical Benefits

No Manual Cleanup Required

  • Jobs automatically adapt, no need to cancel old jobs
  • System self-corrects based on actual state
  • Scales without manual intervention

Resilient to Edge Cases

  • User completes modules out of order? Handled.
  • User skips ahead somehow? Detected and acknowledged.
  • Multiple jobs fire at once? Each checks independently.

Easy to Debug

  • Job execution returns clear status
  • Logs show what path was taken (reminder/encouragement/congratulations)
  • User state always takes precedence over job metadata

Implementation Details

All three types of jobs (initial assessment, level-up, progress check) include this logic:

  1. Fetch current user state
  2. Compare to job target
  3. Choose appropriate message
  4. Update last_ping_date
  5. Return success with context

The pattern is consistent across all job types, making it maintainable and predictable.

Summary

Smart job execution means:

  • ✅ Context-aware - Checks actual progress before sending
  • ✅ Adaptive - Changes message based on state
  • ✅ Respectful - Never sends redundant reminders
  • ✅ Encouraging - Always acknowledges progress
  • ✅ Intelligent - Suggests appropriate next steps

This creates a coaching experience that feels personalized, attentive, and intelligent—exactly what users need for long-term engagement and success!