# Feature Specification: Display Initiative **Feature Branch**: `025-display-initiative` **Created**: 2026-03-10 **Status**: Draft **Input**: User description: "Display a creature's initiative modifier and passive initiative in the stat block panel. Calculate initiative as: DEX modifier + (proficiency multiplier × proficiency bonus), where the proficiency multiplier comes from the bestiary data's initiative.proficiency field (0 if absent, 1 for single, 2 for expertise). Show it in the stat block header area as Initiative +X (Y) matching the Monster Manual 2024 format, where Y = 10 + X. This is a display-only feature — no rolling or auto-applying initiative to encounter order yet. That will be a future feature. The initiative value should be derived purely from bestiary data in the domain layer." ## User Scenarios & Testing *(mandatory)* ### User Story 1 - View Initiative in Stat Block (Priority: P1) As a DM viewing a creature's stat block, I want to see the creature's initiative modifier and passive initiative displayed prominently so I can quickly reference it when rolling initiative or setting encounter order. **Why this priority**: This is the core and only feature — displaying the calculated initiative value in the stat block is the entire scope. **Independent Test**: Can be fully tested by selecting any creature from the bestiary and verifying the initiative line appears in the stat block header area with the correct calculated value. **Acceptance Scenarios**: 1. **Given** a creature with bestiary data that includes an initiative proficiency multiplier (e.g., Aboleth with DEX 9, CR 10, initiative proficiency multiplier of 2), **When** the stat block is displayed, **Then** the initiative line shows "Initiative +7 (17)" calculated as DEX mod (−1) + (2 × proficiency bonus 4) = +7, passive = 10 + 7 = 17. 2. **Given** a creature with bestiary data that includes a single proficiency multiplier for initiative (proficiency = 1), **When** the stat block is displayed, **Then** the initiative modifier includes 1× the creature's proficiency bonus. 3. **Given** a creature whose bestiary data has no initiative field, **When** the stat block is displayed, **Then** the initiative line shows only the DEX modifier (e.g., a creature with DEX 14 shows "Initiative +2 (12)"). 4. **Given** a creature with a negative initiative modifier (e.g., DEX 8 and no initiative proficiency), **When** the stat block is displayed, **Then** the initiative line shows the negative value (e.g., "Initiative −1 (9)") using a minus sign, not a plus sign. --- ### User Story 2 - Initiative Position Matches Monster Manual Layout (Priority: P2) As a DM, I want the initiative display to appear in the same location as the 2024 Monster Manual stat block (next to AC in the header area) so the layout feels familiar. **Why this priority**: Consistent placement with the official source material improves scanability and trust in the displayed values. **Independent Test**: Can be verified by comparing the stat block layout to a Monster Manual 2024 stat block and confirming initiative appears on the same line or area as AC. **Acceptance Scenarios**: 1. **Given** any creature stat block is displayed, **When** the user looks at the header area, **Then** the initiative value appears adjacent to or on the same line as the AC value, before HP. ### Edge Cases - What happens when a creature has a DEX score that produces a modifier of exactly 0 and no initiative proficiency? Display "Initiative +0 (10)". - What happens when the proficiency multiplier combined with a negative DEX modifier still results in a negative total? Display with a minus sign (e.g., DEX 3 with proficiency 1 and CR 0 = −4 + 2 = −2 → "Initiative −2 (8)"). - What happens for creatures without any bestiary data (manually added combatants)? No initiative line is shown — initiative display requires bestiary-sourced creature data. ## Requirements *(mandatory)* ### Functional Requirements - **FR-001**: System MUST parse the initiative proficiency multiplier from the bestiary data's `initiative.proficiency` field for each creature (0 if absent, 1 for single proficiency, 2 for expertise). - **FR-002**: System MUST calculate the initiative modifier as: DEX modifier + (proficiency multiplier × proficiency bonus), where DEX modifier = floor((DEX score − 10) / 2) and proficiency bonus is derived from the creature's challenge rating. - **FR-003**: System MUST calculate the passive initiative as: 10 + initiative modifier. - **FR-004**: System MUST display initiative in the stat block header area in the format "Initiative +X (Y)" where X is the initiative modifier (with + or − sign) and Y is the passive initiative. - **FR-005**: System MUST position the initiative display adjacent to the AC value in the stat block header, matching the Monster Manual 2024 layout. - **FR-006**: System MUST NOT display an initiative line for combatants that lack bestiary creature data. - **FR-007**: This feature is display-only. The system MUST NOT modify encounter turn order or roll initiative based on displayed values. MVP baseline does not include automatic initiative rolling or encounter order integration. ### Key Entities - **Initiative**: A derived value computed from a creature's DEX score, challenge rating, and initiative proficiency multiplier. Not persisted — calculated on demand from bestiary data. - **Initiative Proficiency Multiplier**: A value (0, 1, or 2) from the bestiary source data indicating how many times the creature's proficiency bonus is added to initiative. 0 = no proficiency, 1 = proficiency, 2 = expertise. ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: Every creature from the bestiary displays an initiative value in its stat block that matches the value shown on D&D Beyond / Monster Manual 2024 for that creature. - **SC-002**: The initiative line is visible without scrolling when the stat block first opens (positioned in the header area alongside AC). - **SC-003**: Creatures added manually (without bestiary data) do not show a broken or placeholder initiative line. - **SC-004**: The initiative calculation is implemented as a pure domain function with no UI or I/O dependencies, verified by the existing layer boundary checks. ## Clarifications ### Session 2026-03-10 - Q: When there is no initiative value present for a creature, the DEX modifier is used? → A: Yes. The proficiency multiplier defaults to 0 when the `initiative` field is absent, so the formula reduces to the raw DEX modifier. Already reflected in FR-001 (default 0) and Acceptance Scenario 3 (DEX-only fallback). ## Assumptions - The initiative proficiency multiplier values in the bestiary data are limited to 0 (absent), 1, and 2. No higher multipliers exist in the current dataset. - The "Initiative +X (Y)" format with explicit sign and parenthesized passive value is the standard display across all 2024 Monster Manual stat blocks. - A minus sign (−) is used for negative modifiers rather than a hyphen (-), consistent with typographic conventions in official D&D materials.