home / skills / willsigmon / sigstack / navigation-debugger

navigation-debugger skill

safe

/plugins/ios-dev/skills/navigation-debugger

This skill helps you diagnose and fix navigation issues in Leavn by validating notifications, AppCoordinator routing, and deep link handling.

npx playbooks add skill willsigmon/sigstack --skill navigation-debugger

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

994 B

---
name: Navigation Debugger
description: Debug Leavn navigation issues - NotificationCenter routing, deep links, tab selection, AppCoordinator, modal presentations
allowed-tools: Read, Edit, Grep
---

# Navigation Debugger

Fix navigation bugs in Leavn:

1. **Check notification handling**:
   - Search for notification name in ContentView
   - Verify .onReceive() handlers exist
   - Check AppCoordinator navigation methods

2. **Common Leavn patterns**:
   ```swift
   // Post navigation
   NotificationCenter.default.post(
       name: .OpenBibleReference,
       userInfo: ["book": "Genesis", "chapter": 1]
   )

   // Handle in ContentView
   .onReceive(NotificationCenter.default.publisher(for: .OpenBibleReference)) {
       // Navigate to Bible
   }
   ```

3. **Debug steps**:
   - Add AppLog in notification handlers
   - Verify userInfo parsing
   - Check tab selection works
   - Test deep link URLs

Use when: Navigation broken, wrong screen, deep links fail, tab routing issues

Overview

This skill helps debug navigation problems in Leavn apps by focusing on NotificationCenter routing, deep links, tab selection, AppCoordinator calls, and modal presentation flows. It provides a concise diagnostic checklist and practical steps to find where messages are lost, parsed incorrectly, or routed to the wrong destination. Use it to quickly pinpoint where navigation logic breaks and to verify event handling and state updates.

How this skill works

Inspect notification posting and receiving patterns, verify .onReceive handlers in ContentView, and trace AppCoordinator navigation methods to confirm they react to events as expected. Check userInfo parsing and ensure tab selection/state updates are applied on the main thread. Validate deep link parsing and test modal presentations to confirm view controllers are presented in the correct context.

When to use it

Navigation actions do nothing or land on the wrong screen
Deep links open the app but don’t navigate to the target content
Tab selection does not switch to the expected tab
Modals fail to present or present on the wrong view
You need to confirm NotificationCenter-based routing is wired correctly

Best practices

Add lightweight AppLog statements in every notification handler and coordinator entry point
Always validate userInfo keys and types before using them to navigate
Update UI and selection state on the main thread to avoid race conditions
Centralize navigation decisions in AppCoordinator to keep routing predictable
Test deep links and notification flows in isolation with deterministic payloads

Example use cases

A push notification posts .OpenBibleReference but the Bible screen never appears — use the checklist to confirm the .onReceive handler and AppCoordinator method ran
A deep link like myapp://bible/genesis/1 opens the app but lands on Home — inspect URL parsing, userInfo mapping, and tab selection code
Tapping a notification should select the Bible tab but stays on the current tab — verify tab selection state updates and coordinator invocation
A modal intended to show a chapter appears behind the current view — check presentation context and whether a navigation controller is used

FAQ

What logs should I add to trace a notification?

Log entry and exit in the .onReceive handler and AppCoordinator navigation method, plus the raw userInfo payload and any parsed values.

How do I test deep links reliably?

Use deterministic URL payloads and run them in the simulator and device. Create unit tests for URL parsing and manual integration tests that assert tab selection and final view type.