# Sprint Participation Rules

## Overview

Sprint Participation separates **project membership** from **sprint engagement**. Not all project members work on every sprint — participation must be explicitly selected.

## Key Distinction

| Concept | Definition |
|---------|------------|
| **Project Member** | User with access to the project |
| **Sprint Participant** | Project member actively contributing to a specific sprint |

## Rules

### Who Can Participate

1. **Must be a project member** — only project members (or the owner) can be added as sprint participants
2. **Active users only** — inactive users cannot participate
3. **No duplicates** — a user can only be a participant once per sprint

### What Participants Affect

Sprint participants are the **only** users who contribute to:

| Metric | Participants Only? |
|--------|-------------------|
| Sprint Capacity | ✓ Yes |
| Velocity Calculations | ✓ Yes |
| Sprint Planning | ✓ Yes |
| Sprint Health Score | ✓ Yes |
| Workload Distribution | ✓ Yes |
| Burndown Chart | ✓ Yes |

### Capacity Allocation

Each participant can have an optional **capacity** (in Man-Days):

- `capacity_md = NULL` — No explicit capacity set
- `capacity_md = 0` — Available but no planned work
- `capacity_md > 0` — Planned working days for this sprint

Example:
```
Sprint 12 — 2-week sprint

Participants:
├── Alice   → 10 MD (full time)
├── Bob     → 5 MD (half time)
├── Charlie → 3 MD (part time)
└── Diana   → NULL (no allocation)

Total Sprint Capacity: 18 MD
```

## API Operations

### List Participants

```http
GET /api/v1/projects/{project}/sprints/{sprint}/participants
```

Response:
```json
{
  "data": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "capacity_md": 10,
      "user": { "id": "uuid", "name": "Alice", "email": "alice@example.com" }
    }
  ]
}
```

### Add Participant

```http
POST /api/v1/projects/{project}/sprints/{sprint}/participants

{
  "user_id": "uuid",
  "capacity_md": 10
}
```

### Update Capacity

```http
PATCH /api/v1/projects/{project}/sprints/{sprint}/participants/{user}

{
  "capacity_md": 8
}
```

### Sync All Participants

Replace the entire participant list:

```http
PUT /api/v1/projects/{project}/sprints/{sprint}/participants/sync

{
  "participants": [
    { "user_id": "uuid1", "capacity_md": 10 },
    { "user_id": "uuid2", "capacity_md": 5 }
  ]
}
```

## Migration from Capacity Allocations

Previously, capacity was tracked via `project_sprint_capacity_allocations` for **all project members**.

The new model uses `project_sprint_participants`:

| Old Model | New Model |
|-----------|-----------|
| All project members appear | Only selected participants appear |
| Capacity stored separately | Capacity included in participant record |
| No explicit participation | Explicit opt-in per sprint |

### Backward Compatibility

During migration:
1. Existing capacity allocations are copied to participants
2. `SprintTeamCapacityService` checks for participants first
3. Falls back to old behavior if no participants exist

## Best Practices

### Sprint Planning

1. **Before sprint starts**: Select participants from project members
2. **Allocate capacity**: Set realistic MD values per person
3. **Monitor utilization**: Track assigned vs available capacity

### Common Scenarios

#### Full-Time Team

All members participate in every sprint:
- Add all project members as participants
- Set capacity based on working days (e.g., 10 MD for 2-week sprint)

#### Rotating Specialists

Some members only join specific sprints:
- Add core team members to every sprint
- Add specialists only when their skills are needed

#### Part-Time Contributors

Members split across multiple projects:
- Set reduced capacity (e.g., 5 MD instead of 10)
- Adjust based on actual availability

## Health Indicators

| Utilization | Status | Color |
|-------------|--------|-------|
| < 80% | Available | 🟢 Green |
| 80-100% | Near Capacity | 🟡 Yellow |
| > 100% | Overloaded | 🔴 Red |

## Events & Notifications

When participants change:

| Event | Recipients |
|-------|------------|
| Participant added | The user being added |
| Participant removed | The user being removed |
| Capacity changed | The affected participant |