axiom-swiftui-nav-diag

# SwiftUI Navigation Diagnostics

## Overview

**Core principle** 85% of navigation problems stem from path state management errors, view identity issues, or placement mistakes—not SwiftUI defects.

SwiftUI's navigation system is used by millions of apps and handles complex navigation patterns reliably. If your navigation is failing, not responding, or behaving unexpectedly, the issue is almost always in how you're managing navigation state, not the framework itself.

This skill provides systematic diagnostics to identify root causes in minutes, not hours.

## Red Flags — Suspect Navigation Issue

If you see ANY of these, suspect a code issue, not framework breakage:

- Navigation tap does nothing (link present but doesn't push)
- Back button pops to wrong screen or root
- Deep link opens app but shows wrong screen
- Navigation state lost when switching tabs
- Navigation state lost when app backgrounds
- Same NavigationLink pushes twice
- Navigation animation stuck or janky
- Crash with `navigationDestination` in stack trace

- ❌ **FORBIDDEN** "SwiftUI navigation is broken, let's wrap UINavigationController"
  - NavigationStack is used by Apple's own apps
  - Wrapping UIKit adds complexity and loses SwiftUI state management benefits
  - UIKit interop has its own edge cases you'll spend weeks discovering
  - Your issue is almost certainly path management, not framework defect

**Critical distinction** NavigationStack behavior is deterministic. If it's not working, you're modifying state incorrectly, have view identity issues, or navigationDestination is misplaced.

## Mandatory First Steps

**ALWAYS run these checks FIRST** (before changing code):

```swift
// 1. Add NavigationPath logging
NavigationStack(path: $path) {
    RootView()
        .onChange(of: path.count) { oldCount, newCount in
            print("📍 Path changed: \(oldCount) → \(newCount)")
            // If this never fires, link isn't modifying path
            // If it fires unexpectedly, something e