aicyclingcoach-go/mode-help_system_implementation.md

Help System Implementation Mode Rules

Core Principles

• Help system must be accessible from any screen with a consistent shortcut ('?')
• Context-sensitive content based on active screen
• Keyboard-first navigation within the help system
• Responsive layout adapting to terminal size
• Minimal performance impact on application

Implementation Guidelines

Global Key Handling

1. Register global '?' key handler in app.go
2. Toggle help screen regardless of current active screen
3. Preserve current screen state when help is active
4. Implement help stack to support nested help contexts

Help Screen Components

• Main Help Screen (screens/help.go):

  • Display context-sensitive help based on previous screen
  • Show keyboard shortcuts for current context
  • Provide navigation to general help topics

• Help Panel Component (components/help_panel.go):

  • Reusable component for displaying help content
  • Support scrolling for longer content
  • Style with lipgloss for consistent look

Context-Sensitive Content

• Define help content for each screen:
  • Activity List: Navigation, syncing, selection
  • Activity Detail: Analysis, chart viewing, navigation
  • Route List: GPX management, route selection
• Store help content in structured format (YAML/JSON)
• Load content dynamically based on context

Navigation System

• Tab-based navigation between help sections
• Keyboard shortcuts for:
  • Close help ('esc' or 'q')
  • Navigate sections (tab/shift-tab)
  • Scroll content (arrow keys)
• Breadcrumb trail for hierarchical help

Performance Optimization

• Preload help content during app initialization
• Cache rendered help panels
• Lazy load detailed topic content
• Minimize re-renders during navigation

Error Handling

• Fallback content for missing help definitions
• Graceful degradation on rendering errors
• Help system available even when other features fail

Testing Requirements

• 100% test coverage for help navigation logic
• Golden tests for help content rendering
• Integration tests for context switching
• Test help availability during error states

Integration Points

1. Global key handler in app model (app.go)
2. Screen-specific help content definitions
3. Help panel integration in each screen
4. Help content storage and loading

Quality Standards

• Instant help toggle (<100ms response time)
• Consistent styling across all screens
• Comprehensive coverage of all features
• Accessible navigation without mouse
• Zero performance impact on main application