docs(01): capture phase context

Phase 01: Semantic Position Model
- Implementation decisions documented
- Phase boundary established
This commit is contained in:
Trey t
2026-01-18 13:35:11 -06:00
parent 36544b86d0
commit 6426c0cacd

View File

@@ -0,0 +1,68 @@
# Phase 1: Semantic Position Model - Context
**Gathered:** 2026-01-18
**Status:** Ready for planning
<domain>
## Phase Boundary
All movable items have a persistent semantic position `(day: Int, sortOrder: Double)` that survives data reloads. Games are immovable anchors ordered by game time. Travel segments and custom items can be repositioned. This phase establishes the data model only — constraint validation, flattening, and drag interaction are separate phases.
</domain>
<decisions>
## Implementation Decisions
### sortOrder assignment
- Use integer spacing (1, 2, 3...) for initial sortOrder values
- Midpoint insertion (1.5, 1.25, etc.) when placing between items
- Claude's discretion on threshold/rebalancing strategy when gaps get very small
- Claude's discretion on negative vs positive sortOrder for "before games" items
- Claude's discretion on Double vs Decimal storage type
### Day boundaries
- Day = trip day backed by calendar date (Day 1 = trip.startDate, Day 2 = startDate + 1, etc.)
- Day number derived as: `calendar_days_since(trip.startDate) + 1`
- Games belong to their start date, even if they run past midnight
- Show all days including empty ones (no skipping gaps in the trip)
### Travel segment identity
- Each travel segment has a unique UUID (not keyed by route)
- Same route (e.g., Chicago→Boston) can appear multiple times in a trip
- Travel carries: from city, to city, estimated distance, estimated duration
- Moving travel to different day just updates the day property (no recalculation)
### Position initialization
- Games get sortOrder assigned by Claude based on game time
- Auto-generated travel appears after the origin city's games
- Custom items added via "+" button on day headers, inserted at top of that day
- Claude's discretion on handling position updates when trip is edited
### Claude's Discretion
- Exact sortOrder rebalancing threshold and strategy
- Whether to use negative sortOrder or offset games to higher values for "before" positioning
- Double vs Decimal for sortOrder storage
- Initial sortOrder derivation for games (time-based or sequential)
- Position preservation vs recomputation on trip edits
</decisions>
<specifics>
## Specific Ideas
- Day headers should have a "+" button for adding custom items
- When user taps "+", item is added to top of that day (lowest sortOrder)
</specifics>
<deferred>
## Deferred Ideas
None — discussion stayed within phase scope
</deferred>
---
*Phase: 01-semantic-position-model*
*Context gathered: 2026-01-18*