medium priority low complexity documentation pending documentor Tier 6

Acceptance Criteria

Documentation covers all four contract areas: router route declaration, TabStateManager consumption API, NavigationStateRepository lifecycle, and accessibility context change stream
Each section includes at minimum one complete, compilable Dart code example
Router contract section explains how to add a new GoRoute with correct PopScope wrapping and RouteMetadata declaration
TabStateManager API section shows how a ConsumerWidget reads activeTabIndex using select() and how to access a stack snapshot for a specific tab
NavigationStateRepository lifecycle section explicitly states: what events trigger a save, what events trigger a clear, and what the initial state is for a first-time user
Accessibility stream section documents the AccessibilityContextChange type, all ContextChangeReason values, the fallback label behavior, and how NavigationAccessibilityService subscribes
Document is stored in the project's docs/ directory as a markdown file (or Dart doc comments if co-located with the code — follow existing project convention)
A senior Flutter developer unfamiliar with this epic can implement a new tab and a new sub-route by following the guide without asking questions

Technical Requirements

frameworks
Flutter
GoRouter
Riverpod
apis
All public APIs of TabStateManager
NavigationStateRepository public interface
AccessibilityContextChange stream
data models
NavigationRouteConfig
TabStateSnapshot
AccessibilityContextChange
ContextChangeReason
security requirements
Documentation must note which fields in RouteMetadata are PII-sensitive and must not be logged

Execution Context

Execution Tier
Tier 6

Tier 6 - 158 tasks

Can start after Tier 5 completes

Implementation Notes

Follow the existing documentation style in the project (check docs/ or README for conventions before writing). Structure the document with an overview diagram showing the four components and their relationships, then one section per contract. For the code examples, use minimal but realistic snippets — show just enough context that the reader knows where the code goes (e.g., inside build(), inside a provider definition). Explicitly document the negative cases: what happens if a component calls setActiveTab before hydration completes, what happens if RouteMetadata is missing, what happens if the accessibility stream subscription is never cancelled.

These are the questions that will surface during implementation and having the answers in the guide saves future debugging time.

Testing Requirements

Documentation does not require automated tests, but each code example should be verified to compile against the actual source (e.g., by including it in a doc_test/ directory or running dart analyze on the snippets). A peer review by one team member who was not involved in the epic implementation is the acceptance gate — they should confirm the guide is sufficient to implement a new route without asking clarifying questions.

Component
Navigation Route Configuration
infrastructure medium
Epic Risks (2)
high impact medium prob technical

StatefulShellRoute branch navigator state can interact unexpectedly with GoRouter's imperative navigation (go, push, replace), causing state snapshots to desync from actual route stacks. This could manifest as a user returning to a tab and seeing a different screen than expected, breaking the core motor-fatigue promise.

Mitigation & Contingency

Mitigation: Write integration tests that simulate cross-tab navigation with nested pushes before any UI layer is built. Pin go_router to a tested minor version and review the StatefulShellRoute changelog before upgrading.

Contingency: If branch navigator state consistently desyncs, fall back to a manual stack snapshot strategy using a custom NavigatorObserver that records and replays navigation events independently of StatefulShellRoute internals.

medium impact medium prob technical

Persisted navigation stacks in shared_preferences can become stale or corrupt if route paths are renamed during development, causing app crashes or infinite redirect loops on cold start for users who have an old snapshot.

Mitigation & Contingency

Mitigation: Version the persisted schema with a format key. On app start, validate that all stored route paths exist in the current route config before restoring; silently discard invalid entries rather than crashing.

Contingency: Implement a safe-mode cold start that skips state restoration after a detected crash (via a dirty-launch flag written at startup and cleared on successful first frame), falling back to the default root tab.