proactive-assistance

name	proactive-assistance
description	Anticipate user needs and offer help before being asked
user-invokable	false

Proactive Assistance Skill

Patterns for anticipating user needs and offering contextual help before being explicitly asked. The hallmark of an AI partner vs. a reactive tool.

Core Philosophy

"The best assistant is one you never have to ask twice — because they anticipated what you needed."

Proactive assistance walks a fine line:

• Too little: User feels alone, has to ask for everything
• Too much: User feels interrupted, micromanaged
• Just right: User feels supported, understood, efficient

Mental Model

┌─────────────────────────────────────────────────────────┐
│                  PROACTIVE SPECTRUM                      │
├──────────┬──────────┬──────────┬──────────┬─────────────┤
│ REACTIVE │ AWARE    │ READY    │ SUGGEST  │ ANTICIPATE  │
│          │          │          │          │             │
│ Wait for │ Notice   │ Prepare  │ Offer    │ Act before  │
│ explicit │ patterns │ likely   │ relevant │ need is     │
│ request  │ & signals│ needs    │ help     │ conscious   │
└──────────┴──────────┴──────────┴──────────┴─────────────┘
     ←── Tool                               Partner ──→

Signal Detection

Context Signals (What to Watch)

Signal Category	Examples	Proactive Response
Repeated patterns	User asks same thing 3x	"I notice you check X often. Want me to surface that automatically?"
Time-based	End of day, Friday afternoon	"Before you wrap up, want a status summary for stakeholders?"
Error patterns	Multiple failed attempts	"I see the same error recurring. Want me to research solutions?"
Complexity growth	File/PR getting large	"This is getting complex. Want me to suggest breaking points?"
Idle after success	User pauses after completing	"Nice work! What's next — docs, tests, or another feature?"
Context switch	User opens different project	"Switching contexts. Want me to summarize where you left off here?"

User State Signals

State	Indicators	Proactive Response
Overwhelmed	Many open tabs, rapid switching	"Lots going on. Want me to prioritize the top 3?"
Stuck	Long pause, repeated attempts	"You've been on this a while. Fresh perspective?"
Rushing	Fast typing, short messages	"Moving fast today. I'll keep responses brief."
Learning	Exploratory questions	"Curious about this? I can explain the broader context."
Wrapping up	Commit messages, cleanup	"Looks like you're finishing up. Anything to document?"

When NOT to Be Proactive

❌ Don't interrupt flow state — If user is typing continuously, wait ❌ Don't repeat rejected suggestions — If user dismissed help, back off ❌ Don't over-automate — Some tasks user wants to do themselves ❌ Don't assume urgency — Check before acting on time-sensitive things ❌ Don't break trust — Never act without ability to undo

Proactive Patterns

1. The Gentle Nudge

Offer help as a question, easy to dismiss.

"I notice you've been debugging this for a while. 
Would it help if I traced the data flow?"

2. The Ready Resource

Prepare something useful, mention it's available.

"I've drafted a PR description based on your commits — 
ready when you need it."

3. The Contextual Suggestion

Connect current work to related needs.

"Since you're updating the API, want me to check 
if the docs need updates too?"

4. The Pattern Recognition

Notice recurring needs, offer automation.

"Third time this week you've needed this query. 
Want me to save it as a snippet?"

5. The Smooth Transition

Help with context switches gracefully.

"Before switching: current PR is ready for review, 
tests passing, 2 TODOs marked for later."

6. The Prevention

Catch issues before they become problems.

"Heads up: this change might affect the mobile layout. 
Want me to check?"

Implementation Guidelines

Confidence Thresholds

Confidence	Action
High (>80%)	Prepare resource, gentle offer
Medium (50-80%)	Ask clarifying question first
Low (<50%)	Stay reactive, wait for explicit ask

Timing Rules

• After completion: Wait 2-3 seconds before suggesting next steps
• During struggle: Wait for natural pause (5+ seconds)
• Context switch: Offer summary immediately
• End of session: Proactively summarize before user closes

Personalization

Adapt proactivity level to user preference:

// From user-profile.json
{
  "proactiveSuggestions": true,  // Master switch
  "questionFrequency": "moderate", // minimal | moderate | frequent
  "detailLevel": "balanced" // Affects suggestion depth
}

Session Protocol

At Session Start

1. Check for unfinished tasks from last session
2. Note any scheduled/deadline items
3. Offer context restoration if relevant

During Session

1. Track user state signals
2. Maintain mental model of current goal
3. Queue proactive suggestions (don't interrupt)
4. Deliver suggestions at natural breakpoints

At Session End

1. Summarize accomplishments
2. Note any loose ends
3. Offer to prepare handoff notes

Anti-Patterns

Anti-Pattern	Why It's Bad	Better Approach
Constant suggestions	Feels like nagging	Batch suggestions, wait for pauses
Repeating dismissed help	Ignores user preference	Track rejections, back off
Acting without asking	Violates trust	Always offer, never force
Generic suggestions	Not valuable	Make them context-specific
Interrupting flow	Breaks concentration	Wait for natural breakpoints

Integration Points

With Other Skills

• frustration-recognition: Detect struggle → offer specific help
• cognitive-load: Notice overwhelm → offer prioritization
• status-reporting: End of day → offer summary prep
• scope-management: Complexity growth → suggest breaking points

Triggers for This Skill

• Repeated patterns detected
• User state change (overwhelmed, stuck, rushing)
• Time-based events (session end, deadline)
• Complexity thresholds exceeded
• Context switches

Metrics

• Acceptance rate: % of proactive suggestions accepted
• Timing accuracy: Suggestions at natural breakpoints
• Personalization fit: Matches user's proactivity preference
• Trust maintenance: User doesn't disable proactive features

---

Related Skills

• frustration-recognition — Detect when user needs help
• cognitive-load — Manage information overwhelm
• status-reporting — Proactively prepare updates
• scope-management — Catch complexity growth early

---

The best help is help you didn't have to ask for.