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

Implementation Plan: Clear Encounter

Branch: 023-clear-encounter | Date: 2026-03-09 | Spec: spec.md Input: Feature specification from /specs/023-clear-encounter/spec.md

Summary

Add a "Clear Encounter" action that removes all combatants and resets round/turn counters with a single confirmed click. Implementation follows the existing domain → application → adapter pattern with a new clearEncounter pure function, a use case orchestrator, and a clear button in the TurnNavigation component gated by window.confirm().

Technical Context

Language/Version: TypeScript 5.8 (strict mode, verbatimModuleSyntax) Primary Dependencies: React 19, Tailwind CSS v4, Lucide React (icons) Storage: Browser localStorage (existing adapter, updated to handle empty encounters) Testing: Vitest Target Platform: Web browser (single-page app) Project Type: Web application (monorepo: domain/application/web) Performance Goals: N/A (single synchronous state reset) Constraints: Local-first, single-user MVP Scale/Scope: Single encounter tracker screen

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Principle	Status	Notes
I. Deterministic Domain Core	PASS	clearEncounter is a pure function — same input always produces same output. No I/O, randomness, or clocks.
II. Layered Architecture	PASS	Domain function → Application use case → React adapter. No layer violations.
III. Agent Boundary	N/A	No agent layer involvement.
IV. Clarification-First	PASS	No non-trivial assumptions — feature is straightforward. Confirmation UI (browser confirm) is a reasonable default documented in research.
V. Escalation Gates	PASS	All work is within spec scope.
VI. MVP Baseline Language	PASS	Spec uses "MVP baseline does not include" for undo and encounter history.
VII. No Gameplay Rules	PASS	No gameplay mechanics in the plan.

Post-Phase 1 re-check: All gates still pass. The empty encounter bypass of createEncounter() is consistent with existing behavior (remove-combatant already produces empty combatant lists). No new layer violations introduced.

Project Structure

Documentation (this feature)

specs/023-clear-encounter/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
└── tasks.md             # Phase 2 output (/speckit.tasks command)

Source Code (repository root)

packages/domain/src/
├── clear-encounter.ts           # New: pure clearEncounter function
├── events.ts                    # Modified: add EncounterCleared event
├── index.ts                     # Modified: export clearEncounter + event
└── __tests__/
    └── clear-encounter.test.ts  # New: domain function tests

packages/application/src/
├── clear-encounter-use-case.ts  # New: use case orchestrator
└── index.ts                     # Modified: export use case

apps/web/src/
├── hooks/
│   └── use-encounter.ts         # Modified: add clearEncounter callback
├── persistence/
│   └── encounter-storage.ts     # Modified: handle empty encounter in load
├── components/
│   └── turn-navigation.tsx      # Modified: add clear button
└── App.tsx                      # Modified: wire clearEncounter prop

Structure Decision: Follows existing monorepo layout with strict domain → application → web layering. No new packages or directories needed. Three new files, six modified files.