initiative/specs/023-clear-encounter/quickstart.md

Quickstart: 023-clear-encounter

Overview

Add a "Clear Encounter" feature that resets the entire encounter state (removes all combatants, resets round to 1, resets turn to 0) with a single confirmed action.

Key Files to Create

File	Layer	Purpose
packages/domain/src/clear-encounter.ts	Domain	Pure function: clear encounter state
packages/application/src/clear-encounter-use-case.ts	Application	Orchestrates domain call via store
packages/domain/src/__tests__/clear-encounter.test.ts	Test	Domain function tests

Key Files to Modify

File	Change
packages/domain/src/events.ts	Add EncounterCleared event type
packages/domain/src/index.ts	Export clearEncounter + event type
packages/application/src/index.ts	Export clearEncounterUseCase
apps/web/src/hooks/use-encounter.ts	Add clearEncounter callback
apps/web/src/persistence/encounter-storage.ts	Handle empty encounter in loadEncounter
apps/web/src/components/turn-navigation.tsx	Add clear button
apps/web/src/App.tsx	Wire clearEncounter to TurnNavigation

Architecture Pattern

Follow the existing remove-combatant pattern:

1. Domain (clearEncounter): Pure function, takes Encounter, returns { encounter, events } or DomainError
2. Application (clearEncounterUseCase): Gets encounter from store, calls domain function, saves result
3. Web hook (useEncounter): Adds clearEncounter callback with window.confirm() gate
4. UI (TurnNavigation): Renders clear button, calls onClearEncounter prop

Dev Commands

pnpm vitest run packages/domain/src/__tests__/clear-encounter.test.ts  # Run domain tests
pnpm check                                                              # Full merge gate
pnpm --filter web dev                                                   # Dev server