engagement-cadence

name: engagement-cadence description: Engagement-respecting message cadence — anti-nag protocol, response tracking, escalating back-off, fatigue detection, and per-recipient adaptation. Use when agent says "check engagement", "skip cycle", "unanswered messages", "cadence check", "should I message", "engagement fatigue", "back-off", "nudge frequency", "message spacing", or any periodic messaging decision.

Engagement-Respecting Cadence Skill

Canonical protocol for any agent that sends periodic messages to family members. Prevents over-messaging, respects engagement signals, and adapts cadence based on response patterns.

Complements the telegram-communication skill (formatting, quiet hours, speak param). This skill governs when and whether to send — telegram-communication governs how to send.

Core Principle

Every unanswered message is a signal. Respect it. Back off progressively. Never guilt-trip. Welcome them back naturally when they re-engage.

1. Response Tracking (Required State)

Every agent using this skill MUST track in working.md:

## Engagement State — [Recipient Name]
- last_message_sent: [ISO timestamp]
- last_message_topic: [brief description]
- last_response_received: [ISO timestamp or "none"]
- consecutive_unanswered: [0-N]
- cycles_skipped: [0-N]  
- daily_message_count: [0-N]
- daily_message_date: [YYYY-MM-DD]

Reset consecutive_unanswered to 0 whenever the recipient responds. Reset daily_message_count when daily_message_date ≠ today.

2. Escalating Back-Off Rules

Before sending ANY periodic message, evaluate the engagement state:

Skip Tracking

When skipping, increment cycles_skipped in working memory. When cycles_skipped reaches the required count (1 for 2-unanswered, 2 for 3+-unanswered), reset it to 0 and allow the next send — but ONLY with a high-value message.

Re-Engagement After Silence

When the recipient responds after a gap:

• Welcome naturally: "there she is 💛" or "hey! good to hear from you" — match the agent's voice
• NEVER: "where have you been?", "I was worried", "did you see my message?"
• NEVER guilt-trip about not responding
• Reset consecutive_unanswered to 0 immediately

3. Daily Message Caps

Prevent notification fatigue with per-recipient daily limits:

Agents should check daily_message_count before sending. If at cap → skip and note in memory.

Cross-agent awareness: If multiple agents message the same recipient, each agent should check recent Telegram history (last few hours) before adding more messages. If 2+ other agent messages are visible and unanswered, treat as consecutive_unanswered: 2 (skip cycle).

4. Time-of-Day Windows

Align message energy with recipient's likely state:

Note: The 9 PM cutoff is stricter than the platform-wide 10 PM quiet hours. Agents using this skill prioritize recipient rest over the wider window. Emergency/urgent messages still follow emergency-protocol and bypass all cadence rules.

5. Cycle Spacing

Minimum time between messages to the same recipient from the same agent:

If the agent's cron fires more frequently than its spacing profile, it should check last_message_sent and skip if too soon.

6. Engagement Fatigue Detection

Signs that messaging cadence needs to reduce:

7. Message Batching

When an agent has multiple things to communicate:

1. Combine into ONE message — never send 3 messages in a row
2. Prioritize: Lead with the most important/time-sensitive item
3. Cut ruthlessly: If you have 5 things, pick the top 2. Save the rest for next cycle.
4. For {{PARENT_2}} specifically: ONE topic per message, max 2-3 lines. If you have multiple topics, pick the single most important one.

8. Implementation Checklist

When adopting this skill, an agent should:

• Add engagement state tracking to working.md template
• Check engagement state BEFORE composing any message
• Implement skip logic with memory updates ("skipped — respecting space")
• Track daily message count per recipient
• Implement re-engagement welcome pattern
• Reference this skill in agent definition: > **Skill reference:** Follow the \engagement-cadence` skill at `.github/skills/engagement-cadence/SKILL.md` for message frequency, back-off rules, and engagement fatigue detection.`

9. Emergency Override

All cadence rules are suspended for:

• Medical emergencies (red flag symptoms)
• Child safety concerns
• Time-critical actions (payment about to fail, appointment in 30 min)

Follow emergency-protocol skill for these cases. After the emergency, resume normal cadence tracking.

10. Decision Flowchart

Cron fires → Compute CT time
  → After 9 PM or before agent's start hour? → EXIT (save "skipped — outside hours")
  → Check engagement state for recipient
    → consecutive_unanswered >= 3 AND cycles_skipped < 2? → EXIT (increment cycles_skipped)
    → consecutive_unanswered == 2 AND cycles_skipped < 1? → EXIT (increment cycles_skipped)
    → daily_message_count >= cap? → EXIT (save "skipped — daily cap reached")
    → Last message sent < min_spacing ago? → EXIT (save "skipped — too soon")
    → All clear → Compose message
      → consecutive_unanswered == 1? → Use softer/lighter tone
      → consecutive_unanswered == 0? → Normal tone
      → Send message → Update engagement state