Coach AI

Instructions

Implementation Reference

• src/coach_ai/server.py:819-955 (handler)

  Handler function for the 'start_my_week' tool, which performs weekly planning by analyzing last week's completions and categorizing current todos by timeframe.

  async def start_my_week(week_start_date_str: Optional[str] = None) -> str:
      """Weekly planning ritual: review last week, plan this week.
  
      Provides a structured weekly planning session with:
      - Last week's completion summary
      - Strategic vs sprint work breakdown
      - This week's suggested focus items
      - Tasks needing timeframe assignment
      - Suggested theme for each day of the week
  
      Perfect for: "Plan my week" or "Weekly review"
  
      Args:
          week_start_date_str: Optional Monday date in YYYY-MM-DD format (defaults to next Monday)
  
      Returns:
          Comprehensive weekly planning summary
      """
      db = await storage.get_db()
  
      # Determine week boundaries
      if week_start_date_str:
          week_start = datetime.fromisoformat(week_start_date_str).date()
      else:
          week_start = get_next_monday(datetime.now()).date()
  
      from datetime import timedelta
  
      last_week_start = week_start - timedelta(days=7)
      last_week_end = week_start - timedelta(days=1)
  
      # 1. Review last week's completions
      cursor = await db.execute(
          """
          SELECT title, theme_tag FROM todos
          WHERE status = 'completed'
          AND date(completed_at) >= date(?)
          AND date(completed_at) <= date(?)
          """,
          (last_week_start, last_week_end),
      )
      last_week_completed = await cursor.fetchall()
  
      # Categorize by theme
      strategic_work = [t for t in last_week_completed if t['theme_tag'] == 'strategic']
      sprint_work = [t for t in last_week_completed if t['theme_tag'] == 'sprint_work']
  
      # 2. Get active todos by timeframe
      cursor = await db.execute(
          """
          SELECT id, title, priority, timeframe, theme_tag
          FROM todos
          WHERE status = 'active'
          """
      )
      active_todos = await cursor.fetchall()
  
      # Group by timeframe
      by_timeframe = {
          'this_week': [],
          'next_sprint': [],
          'this_month': [],
          'this_quarter': [],
          'someday': [],
          'unassigned': [],
      }
  
      for todo in active_todos:
          tf = todo['timeframe'] or 'unassigned'
          by_timeframe[tf].append(todo)
  
      # 3. Suggest strategic focus for this week
      # Pick 1-2 strategic items from this_month/this_quarter that are high priority
      strategic_candidates = by_timeframe['this_month'] + by_timeframe['this_quarter']
      strategic_high_priority = [
          t for t in strategic_candidates
          if t['priority'] == 'high' and t['theme_tag'] == 'strategic'
      ][:2]
  
      # 4. Build response
      response = f"**📅 Weekly Planning: Week of {week_start.strftime('%B %d, %Y')}**\n\n"
  
      # Last week summary
      response += f"**Last Week Summary:**\n"
      response += f"  ✓ Completed: {len(last_week_completed)} tasks\n"
      if strategic_work:
          response += f"  🎯 Strategic: {len(strategic_work)} tasks\n"
          for task in strategic_work[:3]:
              response += f"      • {task['title']}\n"
      if sprint_work:
          response += f"  ⚡ Sprint: {len(sprint_work)} tasks\n"
          for task in sprint_work[:3]:
              response += f"      • {task['title']}\n"
  
      # This week's focus
      response += f"\n**This Week's Focus:**\n"
      response += f"  Sprint work: {len(by_timeframe['this_week'])} tasks\n"
      if strategic_high_priority:
          response += f"  Strategic focus:\n"
          for task in strategic_high_priority:
              response += f"      • #{task['id']}: {task['title']}\n"
  
      # Task breakdown by timeframe
      response += f"\n**Task Breakdown:**\n"
      response += f"  This week: {len(by_timeframe['this_week'])}\n"
      response += f"  Next sprint: {len(by_timeframe['next_sprint'])}\n"
      response += f"  This month: {len(by_timeframe['this_month'])}\n"
      response += f"  This quarter: {len(by_timeframe['this_quarter'])}\n"
      response += f"  Someday: {len(by_timeframe['someday'])}\n"
      response += f"  ⚠️ Unassigned: {len(by_timeframe['unassigned'])}\n"
  
      # Unassigned tasks needing timeframe
      if by_timeframe['unassigned']:
          response += f"\n**Tasks Needing Timeframe:**\n"
          from coach_ai.temporal import suggest_timeframe_from_keywords
  
          for task in by_timeframe['unassigned'][:5]:  # Show first 5
              combined_text = f"{task['title']}"
              suggested = suggest_timeframe_from_keywords(combined_text, task['priority'])
              response += f"  • #{task['id']}: {task['title']}\n"
              response += f"      Suggested: {suggested}\n"
  
      # Suggested weekly theme
      response += f"\n**Suggested Weekly Theme:**\n"
      # Simple heuristic: more sprint work = sprint-focused week
      sprint_count = len(by_timeframe['this_week'])
      if sprint_count > 5:
          response += "  Mon-Thu: Sprint work\n"
          response += "  Fri: Strategic work / admin\n"
      else:
          response += "  Mon-Wed: Sprint work\n"
          response += "  Thu-Fri: Strategic work\n"
  
      response += f"\n💡 Use 'set_week_theme' to configure daily themes"
      response += f"\n💡 Use 'batch_assign_timeframes' to assign timeframes to unassigned tasks"
  
      return response