claudes_game/docs/mission_planning.md.old

# Mission Planning Module - Implementation Plan

**Date:** January 16, 2026
**Status:** Phase 1-3 Complete ✅, Phase 4 Debugging Required 🔄
**Branch:** patched-conics
**Implementation Progress:** 70% complete (3/6 phases complete, 1 phase debugging)

## Implementation Progress

### ✅ Phase 1: Core Transfer Calculations - COMPLETE
**Status:** All tests passing (3/3)
**Date Completed:** January 16, 2026

**Implemented:**
- `calculate_hohmann_transfer()` - Computes transfer orbit parameters
- `calculate_angular_position()` - Calculates body angle in XY plane
- `calculate_required_phase_angle()` - Computes optimal launch phase angle

**Validation:**
- Earth→Mars transfer time: 258.8 days (±0.08% of expected)
- Required phase angle: 44.3° (±0.08° of expected)
- Delta-v injection: 2.94 km/s (±0.01% of expected)
- All NASA reference values validated within 5%

**Tests:** `tests/test_mission_planning.cpp` - 17 assertions, 6 test cases, all pass

---

### ✅ Phase 2: Launch Window Detection - COMPLETE
**Status:** All tests passing
**Date Completed:** January 16, 2026

**Implemented:**
- `check_launch_window()` - Tests if current phase angle allows optimal launch
- `wait_for_launch_window()` - Fast-forwards simulation to launch window

**Validation:**
- Launch window detection works correctly
- Fast-forward advances simulation to correct phase (within 1°)
- Wait time: ~94 days for Earth→Mars transfer window
- Phase angle wrapping handled correctly (0-360° range)

**Tests:** Integrated into mission planning test suite - all pass

---

### ✅ Phase 3: Spacecraft Spawning - COMPLETE
**Status:** All tests passing (9/9 assertions)
**Date Completed:** January 16, 2026

**Implemented:**
- `add_body_to_simulation()` - Dynamic body creation in simulation.cpp
- `spawn_spacecraft_on_transfer()` - Creates spacecraft with correct velocity

**Validation:**
- Spacecraft spawns at correct position (0m error from departure body)
- Spacecraft velocity = departure velocity + Δv (0% error)
- Spacecraft parent = Sun (index 0)
- Local/global coordinates initialized correctly
- SOI radius calculated correctly

**Tests:** `tests/test_hohmann_transfer.cpp::Spacecraft spawning` - 9 assertions, all pass

**Key Implementation Details:**
- Uses departure body's actual velocity direction (not computed from position)
- Spacecraft mass = 1.0 kg (test particle, mass cancels in physics)
- Position and velocity set before adding to simulation
- Coordinate transforms handle parent=0 (Sun) correctly

---

### ⏸️ Phase 4: Full Transfer Test - DEBUGGING REQUIRED
**Status:** Partially implemented, trajectory issue identified
**Date Started:** January 16, 2026
**Issue:** Spacecraft trajectory deviates from expected Hohmann transfer orbit

**Implemented:**
- Test framework for Earth→Mars transfer
- Launch window detection and waiting
- Spacecraft spawning with transfer parameters
- Energy drift tracking and validation

**Current Issue:**
- Spacecraft spawns with correct initial conditions (position, velocity, parent)
- Initial orbital energy: -3.52×10⁸ J (correct for transfer orbit)
- After first `update_simulation()` call, spacecraft trajectory diverges
- Final orbital energy: +3.51×10²³ J (huge energy error, wrong sign!)
- Spacecraft not following Hohmann transfer ellipse
- Energy drift: 9.98×10¹⁶% (unphysically large)

**Debugging Findings:**
1. Spacecraft spawns correctly:
   - Global position matches Earth: (-6.94×10⁹, -1.49×10¹¹, 0) m
   - Global velocity correct: (-32697.6, 1518.47, 0) m/s
   - Parent = Sun (index 0)
   - Local position initially correct relative to Sun

2. After first `update_simulation()`:
   - Local position jumps incorrectly to: (6.11×10⁷, -2.84×10⁶, 0) m
   - This suggests `compute_global_coordinates()` or local frame integration is wrong

3. Possible root causes:
   - Bug in `update_simulation()` coordinate transforms for newly added bodies
   - Issue with local frame integration when parent = 0 (Sun)
   - `compute_global_coordinates()` not called correctly after body addition
   - SOI transition logic interfering with spacecraft (only 1 SOI transition detected)

4. Investigation needed:
   - Add debug output to `update_simulation()` to track coordinate transforms
   - Check if `find_dominant_body()` incorrectly changing spacecraft's parent
   - Verify RK4 integration is using correct reference frame
   - Test with spacecraft starting at parent ≠ 0 (compare behavior)

**Tests:** `tests/test_hohmann_transfer.cpp::Earth → Mars Hohmann Transfer - Basic`
- Current: 4/5 assertions pass
- Failing: Energy drift validation (expect < 5%, actual 9.98×10¹⁶%)

**Next Steps for Debugging:**
1. Add detailed logging to `update_simulation()` to track coordinate transforms
2. Verify spacecraft's local position/velocity before/after each update
3. Check if parent index changes unexpectedly during simulation
4. Consider if `add_body_to_simulation()` needs to call `compute_global_coordinates()`
5. Test with simplified scenario (e.g., Earth → fake destination at 1.2 AU)

**Estimated Time to Resolve:** 2-3 hours of focused debugging

---

### ⏸️ Phase 5: Enhance Root Body Transition Tests - NOT STARTED
**Status:** Deferred until Phase 4 debugged
**Dependency:** Phase 4 (working transfer orbits required)

---

### ⏸️ Phase 6: Round-Trip Mission - NOT STARTED
**Status:** Deferred until Phase 4 debugged
**Dependency:** Phase 4 (single-leg transfer must work first)

---

## Overview
Add a mission planning module to calculate realistic interplanetary transfers with proper departure windows, replacing manual config positioning with computed trajectories. This enables proper testing of patched conics mechanics and provides a foundation for spacecraft simulation.

## Design Decisions

1. **Spacecraft Mass**: Use small but non-zero (1.0 kg) - works with existing physics (mass cancels out in acceleration)
2. **Capture Burns**: Skip for initial implementation - implement flyby missions only
3. **Inclination**: Planar first (z=0), defer 3D to future work
4. **Scope**: Full mission planner with departure window timing, launch window detection, and spacecraft spawning

## Key Technical Discovery

The physics engine already supports test particles correctly. The acceleration calculation is:
```
acceleration = (G × body_mass × parent_mass / r²) / body_mass = G × parent_mass / r²
```

Body mass cancels out, so any small mass works. We'll use 1.0 kg.

## Data Structures

### TransferParameters
```cpp
struct TransferParameters {
    double semi_major_axis;      // Transfer orbit semi-major axis (meters)
    double eccentricity;         // Transfer orbit eccentricity
    double periapsis;            // Closest approach (departure radius)
    double apoapsis;             // Furthest distance (arrival radius)
    double transfer_time;        // Time required for transfer (seconds)
    double departure_velocity;   // Required velocity at departure (m/s)
    double arrival_velocity;     // Velocity at arrival (relative to Sun, m/s)
    double phase_angle_deg;      // Required phase angle for launch (degrees)
    double delta_v_injection;    // Delta-V needed for transfer injection (m/s)
    double delta_v_capture;      // Delta-V needed for capture (optional, future)
};
```

## Implementation Phases

### Phase 1: Core Transfer Calculations (1 day)

**Goal:** Implement orbital mechanics calculations for Hohmann transfers

**Files:**
- `src/mission_planning.h` (new) - Function declarations
- `src/mission_planning.cpp` (new) - Core calculations
- `tests/test_mission_planning.cpp` (new) - Unit tests for formulas

**Functions to implement:**

#### 1.1 `calculate_hohmann_transfer()`
Calculates transfer orbit parameters given departure and arrival radii.

**Algorithm:**
```
a_transfer = (r_departure + r_arrival) / 2
e = (r_arrival - r_departure) / (r_arrival + r_departure)
T_transfer = π × sqrt(a³ / GM)

v_departure = sqrt(G × M × (2/r_departure - 1/a))
v_arrival = sqrt(G × M × (2/r_arrival - 1/a))
v_circular = sqrt(G × M / r_departure)

Δv_injection = v_departure - v_circular
```

**Validation:** Earth→Mars values:
- Transfer time: ~259 days
- Phase angle: ~44.3°
- Δv: ~2.94 km/s

#### 1.2 `calculate_angular_position()`
Calculates angular position of a body relative to its center (in XY plane).

**Algorithm:**
```
rel_pos = body_position - center_position
angle = atan2(y, x)
Normalize to [0, 2π)
```

#### 1.3 `calculate_required_phase_angle()`
Calculates optimal phase angle for launch.

**Algorithm:**
```
ω_departure = 2π / T_departure
α = ω_departure × T_transfer
phase_angle = π - α (in radians)
Convert to degrees
```

**Tests:**
- Validate transfer parameters against NASA reference values (±5%)
- Verify angular position calculations for circular orbits
- Test phase angle formula with known cases

**Expected outcome:**
- ✅ Accurate transfer orbit calculations
- ✅ Verified against known mission parameters

**Estimated complexity:** Low
**Risk:** Low (well-known orbital mechanics formulas)

---

### Phase 2: Launch Window Detection (1 day)

**Goal:** Detect when launch window is open and advance simulation to it

**Files:**
- `src/mission_planning.cpp` (extend)
- `tests/test_launch_window.cpp` (new)

**Functions to implement:**

#### 2.1 `check_launch_window()`
Tests if current positions allow optimal launch.

**Algorithm:**
```
θ_depart = calculate_angular_position(departure, sun)
θ_arrival = calculate_angular_position(arrival, sun)

current_phase = θ_arrival - θ_depart (normalize to [0, 2π))
current_phase_deg = current_phase × (180/π)

error = |current_phase_deg - required_phase_angle_deg|
Handle wrap-around: if error > 180°, use |error - 360°|

return error <= tolerance
```

#### 2.2 `wait_for_launch_window()`
Advances simulation until launch window opens.

**Algorithm:**
```
while !check_launch_window(...):
    Fast-forward by 1 day per iteration (for efficiency)
    for i in 0..(86400 / dt):
        update_simulation(sim)
```

**Tests:**
- Create Earth+Mars config at wrong phase angle
- Call `wait_for_launch_window()` - should advance simulation
- Verify phase angle is now within tolerance (1°)
- Measure time waited - should be reasonable (weeks to months)

**Expected outcome:**
- ✅ Can detect proper launch windows
- ✅ Can advance simulation to launch window
- ✅ Phase angle accuracy within 1°

**Estimated complexity:** Low-Medium
**Risk:** Low (simulation fast-forward is safe)

---

### Phase 3: Spacecraft Spawning (1.5 days)

**Goal:** Create spacecraft at departure with correct velocity

**Files:**
- `src/simulation.h` (+3 lines) - Add function declaration
- `src/simulation.cpp` (+30 lines) - Implement dynamic body addition
- `src/mission_planning.cpp` (+40 lines) - Spacecraft spawning logic

**Functions to implement:**

#### 3.1 `add_body_to_simulation()` (in simulation.cpp)
Adds a new body to the simulation at runtime.

**Algorithm:**
```
Check capacity (body_count < max_bodies)
Copy body to next available slot
Initialize local coordinates:
    if parent_index >= 0:
        local_pos = global_pos - parent_pos
        local_vel = global_vel - parent_vel
    else:
        local_pos = global_pos
        local_vel = global_vel
Calculate SOI radius (if has parent)
Increment body_count
Return new body index
```

#### 3.2 `spawn_spacecraft_on_transfer()` (in mission_planning.cpp)
Creates spacecraft on transfer trajectory at departure.

**Algorithm:**
```
Create spacecraft body:
    name = "Spacecraft"
    mass = 1.0 kg (negligible but non-zero)
    radius = 1.0 km (for visualization)
    color = magenta/pink
    eccentricity = transfer.eccentricity
    semi_major_axis = transfer.semi_major_axis

Position = departure.position

Velocity = departure.velocity + Δv_injection:
    departure_pos = departure.position - sun.position
    orbit_dir = normalize(cross(departure_pos, z_axis))
    delta_v = orbit_dir × transfer.delta_v_injection
    spacecraft.velocity = departure.velocity + delta_v

Parent = Sun (index 0)
Add to simulation via add_body_to_simulation()
Return spacecraft index
```

**Tests:**
- Spawn spacecraft at Earth
- Verify initial position matches Earth
- Verify velocity = Earth velocity + Δv
- Verify parent = Sun
- Verify local coordinates initialized correctly

**Expected outcome:**
- ✅ Spacecraft spawns correctly at departure
- ✅ Initial velocity matches transfer requirements
- ✅ Parent set to Sun for transfer orbit
- ✅ Local/global coordinates consistent

**Estimated complexity:** Medium
**Risk:** Medium (dynamic body addition affects simulation state)

---

### Phase 4: Full Transfer Test (1.5 days)

**Goal:** End-to-end test of Earth→Mars Hohmann transfer

**Files:**
- `tests/test_hohmann_transfer.cpp` (new) - Main integration test
- `tests/configs/earth_mars_simple.toml` (new) - Simple 3-body config

**Test scenario:**
```cpp
TEST_CASE("Earth → Mars Hohmann Transfer", "[mission][hohmann]") {
    // 1. Load Earth+Mars system
    // 2. Calculate transfer parameters
    // 3. Wait for launch window (within 1° tolerance)
    // 4. Record departure time
    // 5. Spawn spacecraft on transfer trajectory
    // 6. Simulate until arrival (transfer_time × 1.1)
    // 7. Track SOI transitions (Earth→Sun→Mars)
    // 8. Verify arrival at Mars (distance < 2×SOI)
    // 9. Verify transfer time accuracy (±10%)
}
```

**Success criteria:**
- Spacecraft enters Mars SOI
- Transfer time: 259 ± 26 days
- Final distance to Mars < 2 × Mars_SOI
- SOI transitions: Earth→Sun→Mars (tracked)
- Energy drift < 1% during transfer

**Expected outcome:**
- ✅ Complete end-to-end transfer validated
- ✅ Patched conics mechanics tested (3 SOI changes)
- ✅ Transfer trajectory matches prediction

**Estimated complexity:** Medium-High
**Risk:** Medium-High (integration test may reveal edge cases)

---

### Phase 5: Enhance Root Body Transition Tests (0.5 days)

**Goal:** Replace manual config positioning with calculated transfers

**Files:**
- `tests/test_root_body_transitions.cpp` (refactor)
- Remove `tests/configs/manual_root_transition.toml`

**Changes:**
1. Replace "Root body transition - Earth to Sun" test:
   - Use `spawn_spacecraft_on_transfer()` instead of manual config
   - Calculate transfer parameters
   - Wait for launch window
   - Verify Earth→Sun transition happens

2. Replace "Root body round-trip" test:
   - Calculate Earth→Mars transfer
   - Wait for window
   - Spawn spacecraft
   - Verify round-trip SOI transitions

3. Add better validation:
   - Verify transition order (Earth→Sun→Mars)
   - Verify arrival distance < threshold
   - Verify energy conservation
   - Verify spacecraft follows predicted trajectory

**Expected outcome:**
- ✅ Realistic mission-based testing
- ✅ Better validation than `sun_transitions >= 1`
- ✅ Eliminates manual config positioning
- ✅ Tests use actual orbital mechanics

**Estimated complexity:** Low
**Risk:** Low (refactoring existing tests)

---

### Phase 6: Round-Trip Mission (1 day) - Optional

**Goal:** Validate full mission lifecycle with return journey

**Files:**
- `tests/test_round_trip.cpp` (new)

**Test scenario:**
```cpp
TEST_CASE("Earth → Mars → Earth Round Trip", "[mission][round-trip]") {
    // 1. Earth→Mars transfer
    // 2. Verify arrival at Mars
    // 3. Wait for Mars→Earth return window
    // 4. Spawn new spacecraft at Mars for return
    // 5. Simulate Mars→Earth return
    // 6. Verify both transfers complete
    // 7. Verify return arrival at Earth
}
```

**Success criteria:**
- Both transfers complete successfully
- Return time: ~259 ± 26 days
- Final distance to Earth < 2 × Earth_SOI
- Energy conserved across entire round-trip

**Expected outcome:**
- ✅ Full mission lifecycle validated
- ✅ Multiple departure windows handled
- ✅ Patched conics round-trip confirmed

**Estimated complexity:** Medium
**Risk:** Medium (long simulation time)

---

## Integration with Existing Code

### Reuses Existing Components:

**Physics Module:**
- `rk4_step()` - RK4 integration works with any mass
- `evaluate_acceleration()` - Mass cancels out, test particles work

**Simulation Module:**
- `find_dominant_body()` - SOI transitions work with parent_index = 0 (Sun)
- `update_simulation()` - Handles root bodies correctly
- Coordinate frames - Local/global transformations already work

**Test Utilities:**
- `calculate_orbital_metrics()` - Can use for trajectory validation
- `OrbitTracker` - Can track orbital progress

### New Components:

**Mission Planning Module:**
- `mission_planning.h/cpp` - Mission calculations
- TransferParameters struct - Transfer orbit description
- Phase angle calculations - Launch window detection

**Simulation Extensions:**
- `add_body_to_simulation()` - Dynamic spacecraft creation
- Runtime body addition - No more config-only initialization

---

## Build System Changes

### Makefile Modifications

**Add to OBJECTS list:**
```makefile
OBJECTS = main.o physics.o simulation.o config_loader.o renderer.o \
          test_utilities.o mission_planning.o
```

**Add build rule:**
```makefile
mission_planning.o: src/mission_planning.cpp src/mission_planning.h
    $(CXX) $(CXXFLAGS) -c src/mission_planning.cpp -o mission_planning.o
```

**Add to test build:**
```makefile
# Test executable includes mission_planning.o
test: test_build
    ./orbit_test
```

---

## Test Configurations

### earth_mars_simple.toml
Simple 3-body system for transfer testing:
```toml
[[bodies]]
name = "Sun"
mass = 1.989e30
radius = 6.96e8
position = { x = 0.0, y = 0.0, z = 0.0 }
parent_index = -1
color = { r = 1.0, g = 1.0, b = 0.0 }
eccentricity = 0.0
semi_major_axis = 0.0

[[bodies]]
name = "Earth"
mass = 5.972e24
radius = 6.371e6
position = { x = 1.496e11, y = 0.0, z = 0.0 }
parent_index = 0
color = { r = 0.0, g = 0.5, b = 1.0 }
eccentricity = 0.0
semi_major_axis = 1.496e11

[[bodies]]
name = "Mars"
mass = 6.39e23
radius = 3.3895e6
position = { x = 2.279e11, y = 0.0, z = 0.0 }
parent_index = 0
color = { r = 0.8, g = 0.3, b = 0.1 }
eccentricity = 0.0
semi_major_axis = 2.279e11
```

---

## Success Criteria

### ✅ Phase 1-2 Success - COMPLETE
- [x] Transfer parameters match NASA reference (±5%)
- [x] Phase angle calculations accurate (±1°)
- [x] Launch window detection works
- [x] Fast-forward to launch window succeeds

### ✅ Phase 3 Success - COMPLETE
- [x] Spacecraft spawns at correct position
- [x] Initial velocity = Earth velocity + Δv
- [x] Parent = Sun for transfer orbit
- [x] Local/global coordinates consistent

### ⏸️ Phase 4 Success - IN PROGRESS (DEBUGGING)
- [ ] Earth→Mars transfer completes (time ±10%)
- [ ] Spacecraft reaches Mars SOI (distance < 2×SOI)
- [ ] SOI transitions: Earth→Sun→Mars tracked correctly
- [ ] Energy drift < 1% during transfer (currently 9.98×10¹⁶%)

### ⏸️ Phase 5 Success - NOT STARTED
- [ ] Root body transition tests use calculated trajectory
- [ ] Manual config positioning eliminated
- [ ] Better validation than `sun_transitions >= 1`

### ⏸️ Phase 6 Success - NOT STARTED
- [ ] Round-trip mission completes
- [ ] Both transfers validated
- [ ] Return journey matches expectations

---

## Timeline Estimate vs. Actual

### Planned:
- **Phase 1:** 1 day - Core transfer calculations ✅ COMPLETED (1 day)
- **Phase 2:** 1 day - Launch window detection ✅ COMPLETED (same day)
- **Phase 3:** 1.5 days - Spacecraft spawning ✅ COMPLETED (same day)
- **Phase 4:** 1.5 days - Full transfer integration test ⏸️ IN DEBUGGING
- **Phase 5:** 0.5 days - Enhanced transition tests ⏸️ NOT STARTED
- **Phase 6:** 1 day - Round-trip mission (optional) ⏸️ NOT STARTED

### Actual Progress (January 16, 2026):
- **Phase 1:** ✅ COMPLETE - All transfer calculations validated
- **Phase 2:** ✅ COMPLETE - Launch window detection working
- **Phase 3:** ✅ COMPLETE - Spacecraft spawning functional
- **Phase 4:** 🔄 PARTIAL - Test framework complete, trajectory bug identified
- **Phase 5:** ⏸️ BLOCKED - Waiting on Phase 4
- **Phase 6:** ⏸️ BLOCKED - Waiting on Phase 4

**Time Invested:** ~6 hours (Phases 1-3)
**Estimated Time to Complete Phase 4:** 2-3 hours debugging
**Total for Phases 1-5:** **~1 day** (excluding Phase 4 debug time)

---

## Files Summary

### New Files Created:
- `src/mission_planning.h` (+40 lines) ✅
- `src/mission_planning.cpp` (+150 lines) ✅
- `tests/test_mission_planning.cpp` (+95 lines) ✅
- `tests/test_hohmann_transfer.cpp` (+73 lines) ✅ (Phase 4 partial)
- `tests/configs/earth_mars_simple.toml` (+30 lines) ✅

### Modified Files:
- `src/simulation.h` (+3 lines) ✅
- `src/simulation.cpp` (+33 lines) ✅
- `Makefile` (+5 lines) ✅
- `tests/test_root_body_transitions.cpp` (refactor - PENDING Phase 5)

### Net Lines: ~+429 lines (Phases 1-3 complete, Phase 4 partial)

---

## Debugging Notes

### Phase 4 Trajectory Bug

**Symptom:** Spacecraft does not follow expected Hohmann transfer orbit

**Initial Conditions (Correct):**
```
Spacecraft global position: (-6.94×10⁹, -1.49×10¹¹, 0) m
Spacecraft global velocity: (-32697.6, 1518.47, 0) m/s
Spacecraft parent: 0 (Sun)
Initial orbital energy: -3.52×10⁸ J (correct for Hohmann transfer)
```

**After First update_simulation() (Incorrect):**
```
Spacecraft local position: (6.11×10⁷, -2.84×10⁶, 0) m
Energy: +3.51×10²³ J (wrong sign, unphysically large)
Energy drift: 9.98×10¹⁶% (should be < 5%)
```

**Expected Behavior:**
```
Spacecraft should follow ellipse:
- Periapsis: 1.496×10¹¹ m (Earth distance)
- Apoapsis: 2.279×10¹¹ m (Mars distance)
- Semi-major axis: 1.888×10¹¹ m
- Period: ~518 days (full orbit), ~259 days (half-orbit to Mars)
```

**Actual Behavior:**
- Spacecraft trajectory diverges immediately
- Not following Hohmann ellipse
- Energy becomes positive (hyperbolic, unbound)
- Position magnitude grows to ~10¹³ AU (wrong scale)

**Hypothesis:**
The issue is likely in `update_simulation()` coordinate transforms for newly added bodies. Specifically:

1. **Local frame integration error:** `rk4_step()` integrates local coordinates, but newly added spacecraft may have incorrect local coordinates after first update.

2. **compute_global_coordinates() not called:** After spawning spacecraft, we set both local and global coordinates manually. The first `update_simulation()` may recalculate local coordinates incorrectly.

3. **SOI transition interference:** Spacecraft parent = 0 (Sun), but `find_dominant_body()` might incorrectly switch parent during first few updates.

4. **Order of operations issue:** In `update_simulation()`:
   - Check SOI transition
   - If transition: convert local→global, switch parent, convert global→local
   - Integrate: `rk4_step()` on local coordinates
   - Compute global: `compute_global_coordinates()`

   The problem: Newly added spacecraft already has correct global coordinates, but `compute_global_coordinates()` may recalculate them incorrectly from possibly corrupted local coordinates.

**Investigation Plan:**
1. Add printf statements to `update_simulation()` to print spacecraft local/global coordinates before/after each operation
2. Check if `find_dominant_body()` is changing spacecraft parent unexpectedly
3. Verify `rk4_step()` is using correct parameters (position, velocity, dt, body_mass, parent_mass)
4. Test with spacecraft starting at parent ≠ 0 to see if issue is specific to Sun-centered orbits
5. Consider calling `compute_global_coordinates()` immediately after `add_body_to_simulation()` to ensure consistency

**Key Code Sections to Examine:**
- `src/simulation.cpp::update_simulation()` - lines 95-141
- `src/simulation.cpp::add_body_to_simulation()` - lines 29-67
- `src/physics.cpp::rk4_step()` - lines 56-89
- `src/physics.cpp::evaluate_acceleration()` - lines 91-104

**Potential Fix:**
The issue may be that we're setting spacecraft global coordinates manually in `add_body_to_simulation()`, but `update_simulation()` expects to compute them from local coordinates. The fix might be to:
1. Set only local coordinates when adding spacecraft
2. Let `update_simulation()` handle global coordinate computation
3. OR: Add a flag to skip `compute_global_coordinates()` for the first few updates after spawning

**Workaround for Testing:**
For now, test Phase 1-3 components separately without running full transfer simulation. The core functionality (calculations, launch window, spawning) is validated and working correctly.

---

## Risks and Mitigations

### High Risk
- **Energy conservation during transfer**
  - Mitigation: Verify with energy tracking in tests
  - Backup: Use smaller timestep if needed

- **SOI transition edge cases**
  - Mitigation: Comprehensive transition tracking in tests
  - Backup: Adjust hysteresis if oscillation occurs

### Medium Risk
- **Launch window calculation accuracy**
  - Mitigation: Validate against known missions (NASA data)
  - Backup: Increase tolerance window if needed

- **Spacecraft spawning bugs**
  - Mitigation: Unit tests for velocity/position
  - Backup: Manual verification with visualization

### Low Risk
- **Fast-forward simulation stability**
  - Mitigation: Use existing `update_simulation()` (tested)
  - Backup: Reduce fast-forward steps if needed

---

## Future Work (Post-Implementation)

### Immediate Next Steps
1. **Inclination Support** - Extend to 3D transfers
   - Need 3D angular position calculations
   - Longitude of ascending node, inclination, argument of periapsis
   - Phase angle calculations in 3D

2. **Capture Burns** - Add velocity reduction at arrival
   - Simulate retrograde burns for orbital capture
   - Calculate Δv needed for circularization

3. **Lambert Solver** - General transfer solver
   - Not just Hohmann transfers
   - Arbitrary departure/arrival positions and times
   - Non-planar transfers

### Visualization Features
4. **Mission GUI** - Interactive departure window visualization
   - Show current phase angle vs. required
   - Countdown to launch window
   - Transfer trajectory preview

5. **Multiple Burns** - Support for course corrections
   - Mid-course corrections
   - Gravity assist maneuvers
   - Powered flybys

6. **SOI Visualization** - Render SOI boundaries
   - Wireframe spheres for each body
   - Color-coded by mass
   - Toggle with keyboard

### Advanced Features
7. **Mission Planner** - Complete mission design tool
   - Multi-leg missions
   - Optimization (minimum Δv, minimum time)
   - Launch date search

8. **Real Ephemeris** - Use actual planetary positions
   - JPL Horizons API integration
   - Date-based initialization
   - Real mission planning

---

## References

- `docs/patched_conics_plan.md` - SOI transition implementation
- `docs/hierarchical_frames_plan.md` - Local frame integration (archived)
- `docs/implementation_plan.md` - Overall system architecture
- NASA Technical Memorandum "Hohmann Transfer Calculations"
- Orbital Mechanics for Engineering Students (Curtis)

---

## Notes

**Coordinate System:**
- All calculations assume planar motion (z = 0) for initial implementation
- Angular positions measured in XY plane
- Future work: Extend to 3D with inclination

**Timekeeping:**
- Simulation time in seconds, conversions to days for display
- Fast-forward uses 1-day steps for efficiency
- Timestep remains 60s during fast-forward

**Mass Strategy:**
- Spacecraft mass = 1.0 kg (negligible but non-zero)
- Physics engine handles test particles correctly (mass cancels)
- No N-body perturbations from spacecraft

**Validation Strategy:**
- Compare against NASA reference missions (Viking, Curiosity, etc.)
- Energy conservation tracking
- Transfer time accuracy
- SOI transition verification

**Testing Approach:**
- Unit tests for each function (formulas, calculations)
- Integration tests for full missions
- Regression tests against manual config approach