Skill: crew-scheduler

# Skill: crew-scheduler

## Purpose

Analyze crew workload, identify overloaded or underloaded crew members, suggest task reassignments, and report on crew performance over time. Understand how tasks are distributed and where gaps exist.

## Crew Workload Analysis

### Fetch workload data

```
GET /api/analytics/crew-workload?period=week
```

Response shape:

```json
{
  "period": "week",
  "start_date": "2025-07-14",
  "end_date": "2025-07-20",
  "crew": [
    {
      "id": "uuid",
      "name": "Carlos Rodriguez",
      "role": "Field Worker",
      "tasks_assigned": 14,
      "tasks_completed": 11,
      "tasks_overdue": 2,
      "estimated_hours": 22.5,
      "actual_hours": 18.5,
      "completion_rate": 0.786
    }
  ],
  "unassigned_tasks": 5,
  "total_unassigned_hours": 8.5
}
```

### Identify overloaded crew members

A crew member is considered overloaded when their `estimated_hours` for the current period exceeds the farm's standard work week (typically 40h). Check via:

```
GET /api/crew/:id   -> stats.estimated_hours_this_week
```

If `estimated_hours_this_week > 40`, the member is overloaded. Consider reassigning lower-priority tasks to crew members below 30h.

### Find underutilized crew members

```
GET /api/analytics/crew-workload?period=week
```

Members with `estimated_hours < 20` and `completion_rate > 0.8` are candidates to receive additional tasks.

## Reassignment Workflow

To reassign a task from one crew member to another:

```json
PUT /api/tasks/:id
{
  "assigned_to": ["<new-crew-member-id>"]
}
```

To add a second assignee without removing the existing one, first GET the task to read current `assigned_to` IDs, then PUT with both IDs:

```json
PUT /api/tasks/:id
{
  "assigned_to": ["<existing-id>", "<new-id>"]
}
```

## Performance Metrics

### Completion rate by crew member

Formula: `completed / assigned` for the given period.

- 0.9+ = high performer
- 0.7-0.9 = normal
- below 0.7 = may need support or has too many tasks

### Hours accuracy

Formula: `actual_hours / estimated_hours`

- 0.9-1.1 = accurate estimation
- above 1.1 = tasks consistently take longer than planned (revise template estimates)
- below 0.9 = tasks completed faster than planned

### Identify crew members with high overdue rates

```
GET /api/analytics/overdue-report
```

Group results by `assigned_to`. Crew members with more than 2 overdue tasks this week may be overloaded or may need priority coaching.

## Weekly Crew Summary Pattern

To produce a weekly summary for a specific crew member:

1. `GET /api/crew/:id` to get the member's task counts and hours
2. `GET /api/tasks?assigned_to=:id&due_date_from=:week_start&due_date_to=:week_end` to list all tasks
3. Group tasks by status: done, in-progress, todo, overdue
4. Group by category to see where time is spent
5. Compare `estimated_hours` vs `actual_hours` across completed tasks

Example summary output:

```
Carlos Rodriguez - Week of Jul 14-20
Tasks assigned: 14
  Done: 11 (79%)
  In progress: 1
  Overdue: 2
Estimated hours: 22.5
Actual hours: 18.5 (82% of estimate)
Top category: Harvesting (8 tasks, 12.0h)
```

## Unassigned Task Triage

Find all unassigned tasks:

```
GET /api/tasks?assigned_to=unassigned&status=todo,in-progress,overdue
```

Prioritize triage by:
1. Overdue tasks first (sort by `due_date` ascending)
2. Urgent priority next
3. High priority
4. Match task category to crew member's role or strongest category

To assign:

```json
PUT /api/tasks/:id
{
  "assigned_to": ["<crew-member-id>"]
}
```

## Recurring Template Assignment

When a template's `assigned_to_id` is set, every generated task instance automatically gets that crew member. To change who receives recurring task instances going forward:

```json
PUT /api/recurring/:id
{
  "assigned_to_id": "<new-crew-member-id>"
}
```

This does not retroactively reassign already-generated task instances.

## Category-to-Crew Matching Guidelines

Default category assignments for Riverside Farm:

| Category | Primary crew | Notes |
|----------|-------------|-------|
| Animal Care | Miguel S., Maria G. | Daily feeding templates |
| Irrigation | Ana L. | Irrigation specialist |
| Harvesting | Carlos R., Ana L. | Peak season all crew |
| Equipment | Miguel S. | Equipment lead |
| Field Work | Carlos R. | Field worker |
| Administration | Maria G. | Record keeping |

When assigning unassigned tasks, prefer these category-crew pairings. If the primary crew member is overloaded, assign to the next available member.

## Schedule Conflict Detection

To check whether a crew member already has tasks on a given day:

```
GET /api/tasks?assigned_to=:id&due_date=:date&status=todo,in-progress
```

Sum `estimated_hours` from the results. If the sum exceeds 8 hours, adding more tasks risks overload.

## Bulk Operations Pattern

The API does not have a bulk endpoint. To reassign multiple tasks at once, send sequential PUT requests per task. When building an agentic workflow:

1. List tasks to reassign: `GET /api/tasks?...`
2. For each task ID, `PUT /api/tasks/:id { "assigned_to": [...] }`
3. Confirm with `GET /api/analytics/crew-workload?period=week` after all updates