docs(01): capture phase context
Phase 01: Semantic Position Model - Implementation decisions documented - Phase boundary established
This commit is contained in:
68
.planning/phases/01-semantic-position-model/01-CONTEXT.md
Normal file
68
.planning/phases/01-semantic-position-model/01-CONTEXT.md
Normal 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*
|
||||||
Reference in New Issue
Block a user