# NFL Picks V1: Break-Glass Manual Override Guide

This guide explains how manual injury overrides fit into the Week 1 provider-readiness workflow. Manual CSV input is not the normal V1 injury authority. It is a break-glass path for documented source outages, stale public imports, or unresolved mapping issues.

## 1. V1 Injury Authority

Normal V1 injury and inactive flow:

1. NFL.com public injury report import is the weekly injury authority.
2. NFL.com public inactives import is the game-day 90-minute inactive authority.
3. Official team injury pages are fallback evidence when NFL.com data is missing or stale.
4. Sleeper/public fantasy status is a soft cross-check only.
5. Manual CSV override is break-glass only and must be audited.

Manual overrides cannot silently replace automated public imports, cannot create A/B candidates by themselves, and cannot bypass staleness, projection-latency, or inactive-state gates.

## 2. When Manual Override Is Allowed

Use manual override only when one of these is true:

- NFL.com injury or inactives import is unavailable during the required review window.
- Public imports are malformed or stale and no official source has resolved the player state.
- Player/team/provider mapping is unclear and needs documented reviewer intervention.
- A role change is confirmed by official reporting but not yet reflected in normalized samples.

If the override lacks owner, timestamp, source note, reason, player/team identity, status, and role impact fields, validation must fail closed.

## 3. Override Source File

Default sample path:

```text
data/injuries/manual_overrides_sample.csv
```

Generated audit artifact:

```text
docs/mock/manual_injury_overrides.json
```

The quality gate validates that manual override rows are explicitly marked break-glass only and include required audit metadata.

## 4. Required CSV Fields

Each row must include the core injury/inactive fields plus audit metadata:

| Header | Purpose |
| --- | --- |
| `game_id` | Game identifier, such as `2026_01_BUF_MIA`. |
| `player_id` | Provider/player identifier when available. |
| `player_name` | Human-readable player name. |
| `team` | Team abbreviation. |
| `inactive_state` | `PRE_INACTIVES`, `POST_INACTIVES_CONFIRMED`, or `POST_INACTIVES_INVALIDATED`. |
| `injury_news_timestamp` | ISO 8601 timestamp for the underlying injury news. |
| `projection_includes_injury_news` | Whether the projection already reflects the news. |
| `status` | Normalized status such as `active`, `questionable`, `doubtful`, `out`, or `inactive`. |
| `designation` | Practice/game designation when available. |
| `teammate_absence_boost` | Optional opportunity boost created by another player being out. |
| `next_man_up_role` | Role description for injury-driven opportunity. |
| `role_uncertainty` | Whether the workload is still unclear. |
| `override_owner` | Reviewer or operator who entered the override. |
| `override_timestamp` | ISO 8601 timestamp when the override was entered. |
| `override_source_note` | Official source or evidence summary. |
| `override_reason` | Why the automated public import was insufficient. |
| `break_glass_only` | Must be `true`. |

## 5. Validation Commands

Compile the manual override audit directly:

```powershell
python run_manual_injury_overrides.py --input-csv data/injuries/manual_overrides_sample.csv --output-json docs/mock/manual_injury_overrides.json
```

Run the full repository gate:

```powershell
python run_quality_gate.py
```

Expected safety posture:

- Provider calls remain disabled unless staged provider-call approval is explicit.
- Publish remains disabled until separate publish approval.
- Missing or stale core injury data moves affected candidates to Review or No Play.
- Manual override usage appears in audit/report risk surfaces.

## 6. Reviewer Checklist

Before accepting a manual override:

1. Confirm NFL.com injury/inactives import is missing, stale, malformed, or conflicting.
2. Capture the official source URL or source note.
3. Confirm the override owner and timestamp are present.
4. Confirm the projection includes the injury news, or downgrade affected candidates.
5. Confirm any next-man-up or opponent injury boost is explained.
6. Run `python run_quality_gate.py`.

If any checklist item fails, keep affected plays in Review or Abstain / No Play.