initiative/specs/005-set-initiative/spec.md

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).