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