Debug Issue

Systematically debug problems in PhotoClove using a structured approach.

When This Skill is Invoked

Claude automatically uses this skill when:

• User reports unexpected behavior or bugs
• Features aren't working correctly
• Need to understand why something failed
• Investigating error causes
• Tracing issues through frontend and backend

Debugging Process

1. Reproduce the Issue

• Understand the steps: What exactly did the user do?
• Expected behavior: What should have happened?
• Actual behavior: What actually happened?
• Frequency: Does it happen every time? Intermittently?

2. Gather Context

Check logs first (use investigate-logs skill, log files use UTC dates):

# Frontend logs (today UTC)
tail -200 ~/.local/share/photoclove/logs/photoclove-frontend-$(date -u +%Y-%m-%d).log

# Backend logs (today UTC)
tail -200 ~/.local/share/photoclove/logs/photoclove-$(date -u +%Y-%m-%d).log

# Search for errors
grep -A 5 -B 5 "ERROR" ~/.local/share/photoclove/logs/*.log | tail -50

Check state:

• What was the UI state when error occurred?
• What data was in context/state?
• What mode was the app in? (view mode, filters, etc.)

3. Trace Data Flow

Follow the complete path from user action to error:

Frontend → Backend → Database (Tauri app):

1. User interaction (component event handler)
2. State update (Context, hooks)
3. Tauri command invocation (via invoke())
4. Backend command handler (Rust)
5. Repository/database operation
6. Response back to frontend
7. UI update

Key questions at each step:

• What data is passed?
• Is it transformed correctly?
• Are there null/undefined values?
• Do types match expectations?

4. Identify the Break Point

Where does the data flow break?

• Frontend: Check LogViewer (Ctrl+Shift+L), developer console
• Backend: Check Rust logs in daily log files
• Database: Check SQL logs, table state

5. Examine the Code

Read the relevant files:

• Component handling the operation
• Context/hooks managing state
• Tauri command implementation
• Repository/database code

Look for:

• Incorrect logic
• Missing error handling
• Wrong assumptions about data
• Race conditions
• State synchronization issues

6. Test Hypothesis

Common PhotoClove Issues:

ViewMode related:

• Check if ViewMode state is correct: viewModeObj.isXxxMode()
• Verify display keys: viewModeObj.getDataAttribute()
• Ensure mode-specific data is available

Photo operations:

• Check if photo paths are correct
• Verify trash vs normal mode handling
• Ensure photo list updates after operations

Album/Tag operations:

• Verify collection IDs are defined
• Check if photos are properly associated
• Ensure UI updates after backend changes

State management:

• Check if useEffect dependencies are correct
• Verify state updates trigger re-renders
• Ensure context values are available

7. Propose Fix

Based on root cause analysis:

1. Describe the bug: What's actually wrong
2. Explain the cause: Why it happens
3. Propose solution: How to fix it
4. Consider side effects: What else might be affected
5. Test approach: How to verify the fix

Debugging Tools

Frontend (Tauri app)

• LogViewer (Ctrl+Shift+L): Interactive log browsing
• Developer Console: JavaScript console in Tauri webview
• Console logging: Temporary debugging (remove before commit)

Backend (Rust)

• Log files: ~/.local/share/photoclove/logs/photoclove-YYYY-MM-DD.log
• Cargo check: Compilation errors
• Database inspection: SQLite CLI for database debugging

Code Navigation

• docs/terms.md: Component → file mappings
• Glob/Grep: Find code patterns
• Read: Examine specific files
• LSP: Go to definition, find references

Common Bug Patterns

Frontend

• Undefined errors: Missing null checks
• State not updating: Missing dependency in useEffect
• Infinite loops: Incorrect useEffect dependencies
• Wrong data: ViewMode/mode confusion

Backend

• SQL errors: Wrong table/column names
• Path errors: Incorrect file paths
• Type errors: Data type mismatches
• Missing data: Null handling issues

Integration

• Tauri command errors: Wrong parameter names/types
• Response parsing: JSON serialization issues
• Race conditions: Async operation ordering

Best Practices

1. Start with logs - They show what actually happened
2. Reproduce first - Understand the exact steps
3. Use correlation IDs - Trace requests through the system
4. Check assumptions - Verify data at each step
5. Think systematically - Follow the data flow
6. Test the fix - Ensure it actually resolves the issue

PhotoClove-Specific Debugging

ViewMode Issues

• Check src/domain/ViewMode.js for mode logic
• Verify mode conditions in components
• Ensure display keys match ViewMode methods

Photo Operations

• Check src/hooks/usePhotoOperations.js
• Verify photo list updates via removePhotoFromList
• Ensure trash mode handling in Photo entity

Database Operations

• Check src-tauri/src/repository/meta_db/sqlite.rs
• Verify table names (plural: photo_collections, photo_metadata)
• Check IndexMap vs HashMap for order preservation

State Management

• Check Context files in src/context/
• Verify hooks in src/hooks/
• Ensure state flows correctly through components