# Feature Specification: Set Initiative **Feature Branch**: `005-set-initiative` **Created**: 2026-03-04 **Status**: Draft **Input**: User description: "Allow setting an initiative value for combatants; when initiative is set or changed, the encounter automatically orders combatants so the highest initiative acts first." ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Set Initiative for a Combatant (Priority: P1) As a game master running an encounter, I want to assign an initiative value to a combatant so that the encounter's turn order reflects each combatant's rolled initiative. **Why this priority**: Initiative values are the core of this feature — without them, automatic ordering cannot happen. **Independent Test**: Can be fully tested by setting an initiative value on a combatant and verifying the value is stored and the combatant list is reordered accordingly. **Acceptance Scenarios**: 1. **Given** an encounter with combatant "Goblin" (no initiative set), **When** the user sets initiative to 15 for "Goblin", **Then** "Goblin" has initiative value 15. 2. **Given** an encounter with combatant "Goblin" (initiative 15), **When** the user changes initiative to 8, **Then** "Goblin" has initiative value 8. 3. **Given** an encounter with combatant "Goblin" (no initiative set), **When** the user attempts to set a non-integer initiative value, **Then** the system rejects the input and the combatant's initiative remains unset. 4. **Given** an encounter with combatant "Goblin" (initiative 15), **When** the user clears "Goblin"'s initiative, **Then** "Goblin"'s initiative is unset and "Goblin" moves to the end of the turn order. --- ### User Story 2 - Automatic Ordering by Initiative (Priority: P1) As a game master, I want the encounter to automatically sort combatants from highest to lowest initiative so I don't have to manually reorder them. **Why this priority**: Automatic ordering is the primary value of initiative — it directly determines turn order. **Independent Test**: Can be fully tested by setting initiative values on multiple combatants and verifying the combatant list is sorted highest-first. **Acceptance Scenarios**: 1. **Given** combatants A (initiative 20), B (initiative 5), C (initiative 15), **When** all initiatives are set, **Then** the combatant order is A (20), C (15), B (5). 2. **Given** combatants in order A (20), C (15), B (5), **When** B's initiative is changed to 25, **Then** the order becomes B (25), A (20), C (15). 3. **Given** combatants A (initiative 10) and B (initiative 10) with the same value, **Then** their relative order is preserved (stable sort — the combatant who was added or set first stays ahead). --- ### User Story 3 - Combatants Without Initiative (Priority: P2) As a game master, I want combatants who haven't had their initiative set yet to appear at the end of the turn order so that the encounter remains usable while I'm still entering initiative values. **Why this priority**: This supports the practical workflow of entering initiatives one at a time as players roll. **Independent Test**: Can be fully tested by having a mix of combatants with and without initiative values and verifying ordering. **Acceptance Scenarios**: 1. **Given** combatants A (initiative 15), B (no initiative), C (initiative 10), **Then** the order is A (15), C (10), B (no initiative). 2. **Given** combatants A (no initiative) and B (no initiative), **Then** their relative order is preserved from when they were added. 3. **Given** combatant A (no initiative), **When** initiative is set to 12, **Then** A moves to its correct sorted position among combatants that have initiative values. --- ### User Story 4 - Active Turn Preservation During Reorder (Priority: P2) As a game master mid-encounter, I want the active combatant's turn to be preserved when initiative changes cause a reorder so that I don't lose track of whose turn it is. **Why this priority**: Changing initiative mid-encounter (e.g., due to a delayed action or correction) must not disrupt the current turn. **Independent Test**: Can be fully tested by setting the active combatant, changing another combatant's initiative, and verifying the active turn still points to the same combatant. **Acceptance Scenarios**: 1. **Given** it is combatant B's turn (activeIndex points to B), **When** combatant A's initiative is changed causing a reorder, **Then** the active turn still points to combatant B. 2. **Given** it is combatant A's turn, **When** combatant A's own initiative is changed causing a reorder, **Then** the active turn still points to combatant A. --- ### Edge Cases - What happens when a combatant is added without initiative during an ongoing encounter? They appear at the end of the order. - What happens when all combatants have the same initiative value? Their relative order is preserved (insertion order). - What happens when initiative is set to zero? Zero is a valid initiative value and is treated normally in sorting. - What happens when initiative is set to a negative number? Negative values are valid initiative values (some game systems use them). - What happens when initiative is removed/cleared from a combatant? The combatant moves to the end of the order (treated as unset). ## Requirements *(mandatory)* ### Functional Requirements - **FR-001**: System MUST allow setting an integer initiative value for any combatant in an encounter. - **FR-002**: System MUST allow changing an existing initiative value for a combatant. - **FR-003**: System MUST allow clearing a combatant's initiative value (returning it to unset). - **FR-004**: System MUST automatically reorder combatants from highest to lowest initiative whenever an initiative value is set, changed, or cleared. - **FR-005**: System MUST place combatants without an initiative value after all combatants that have initiative values. - **FR-006**: System MUST use a stable sort so that combatants with equal initiative (or multiple combatants without initiative) retain their relative order. - **FR-007**: System MUST preserve the active combatant's turn when reordering occurs — the active turn tracks the combatant identity, not the position. - **FR-008**: System MUST reject non-integer initiative values and return an error. - **FR-009**: System MUST accept zero and negative integers as valid initiative values. - **FR-010**: System MUST emit a domain event when a combatant's initiative is set or changed. ### Key Entities - **Combatant**: Gains an optional initiative property (integer or unset). When set, determines the combatant's position in the encounter's turn order. - **Encounter**: Combatant ordering becomes initiative-driven. The `activeIndex` must track the active combatant's identity through reorders. ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: Users can set initiative for any combatant in a single action. - **SC-002**: After setting or changing any initiative value, the encounter's combatant order immediately reflects the correct descending initiative sort. - **SC-003**: The active combatant's turn is never lost or shifted to a different combatant due to an initiative-driven reorder. - **SC-004**: Combatants without initiative are always displayed after combatants with initiative values. ## Assumptions - Initiative values are integers (no decimals). This matches common tabletop RPG conventions. - There is no initiative "roll" or randomization in the domain — the user provides the final initiative value. Dice rolling is outside scope. - Tiebreaking for equal initiative values uses stable sort (preserves existing relative order). MVP baseline does not include secondary tiebreakers (e.g., Dexterity modifier). - Clearing initiative is supported to allow corrections (e.g., a combatant hasn't rolled yet).