PokeGoalsHelper/CLAUDE.md

# Claude Development Guidelines

This document establishes development patterns and workflows for maintaining clean, trackable progress on the PokeGoalsHelper2 project.

## Git Workflow

### Branch Naming Convention
Use descriptive branch names following this pattern:
- `feature/description-of-feature`
- `bugfix/description-of-bug`
- `refactor/description-of-refactor`
- `docs/description-of-documentation`

Examples:
- `feature/floating-orb-ui`
- `bugfix/image-buffer-leak`
- `refactor/mvc-architecture`

### Commit Guidelines

#### Commit Early and Often
- Commit after each logical change or completion of a small task
- Don't wait to complete entire features before committing
- Use the TodoWrite tool to track progress and commit when todos are completed

#### Commit Message Format
```
<type>: <brief description>

<optional detailed description>

Related todos: #<todo-id>, #<todo-id>
```

Types:
- `feat`: New feature
- `fix`: Bug fix  
- `refactor`: Code refactoring
- `docs`: Documentation
- `test`: Testing
- `style`: Code formatting/style

Examples:
```
feat: add floating orb UI with expandable menu

Implemented CalcIV-style floating orb that expands to show
detection and filter options. Replaces old button grid layout.

Related todos: #22
```

```
fix: resolve ImageReader buffer leak causing logcat spam

- Increased buffer count from 2 to 3
- Added proper image cleanup in triggerManualDetection()
- Ensures images are closed after processing

Related todos: #buffer-fix
```

### Branch Management

1. **Create branch for each task/feature**
   ```bash
   git checkout -b feature/<description>
   ```

2. **Commit frequently during development**
   ```bash
   git add .
   git commit -m "feat: implement basic orb button structure"
   ```

3. **Push branch and create PR when complete**
   ```bash
   git push origin feature/<description>
   ```

4. **Merge to main and delete feature branch**
   ```bash
   git checkout main
   git merge feature/<description>
   git branch -d feature/<description>
   ```

## Architecture Guidelines

### Separation of Concerns

#### UI Layer (Views)
- Handle only UI interactions and display
- No business logic or direct data manipulation
- Communicate via events/callbacks

#### Business Logic Layer (Controllers/Services)  
- Handle core application logic
- Process data and make decisions
- Independent of UI implementation

#### Data Layer (Models)
- Manage data structures and persistence
- Handle API calls and data transformations
- Pure data operations

### Event-Driven Communication

Use callbacks and event buses to decouple UI from business logic:

```kotlin
// UI publishes events
interface DetectionUIEvents {
    fun onDetectionRequested()
    fun onClassFilterChanged(className: String?)
    fun onDebugModeToggled()
}

// Business logic handles events
class DetectionController : DetectionUIEvents {
    override fun onDetectionRequested() {
        // Handle detection logic
        // Notify UI via callbacks
    }
}
```

### File Organization

```
app/src/main/java/com/quillstudios/pokegoalshelper/
├── ui/
│   ├── FloatingOrbUI.kt           # UI components
│   ├── DetectionOverlay.kt        # Visual overlays
│   └── interfaces/
│       └── DetectionUIEvents.kt   # UI event interfaces
├── controllers/
│   ├── DetectionController.kt     # Business logic
│   └── ScreenCaptureController.kt # Screen capture logic  
├── models/
│   ├── Detection.kt               # Data models
│   ├── PokemonInfo.kt            # Domain models
│   └── DetectionSettings.kt       # Configuration
└── services/
    ├── YOLOOnnxDetector.kt       # YOLO inference
    └── ScreenCaptureService.kt    # Android service
```

## Development Best Practices

### Testing Approach
- Test business logic separately from UI
- Mock UI interactions for controller tests
- Use dependency injection for testability

### Code Quality
- Single responsibility principle
- Minimize coupling between layers
- Use interfaces for dependency injection
- Keep functions small and focused

### Code Style Guidelines

#### Brace Placement
- Opening braces `{` go on the line **below** functions and statements
- This improves visual separation and readability

```kotlin
// Preferred style
fun myFunction()
{
    if (condition)
    {
        // code here
    }
}

// NOT this style
fun myFunction() {
    if (condition) {
        // code here
    }
}
```

#### Variable Naming Conventions
Use different naming patterns to distinguish variable scope at a glance:

- **Local variables**: `snake_case` (e.g., `display_metrics`, `captured_image`, `window_manager`)
- **Member variables**: `camelCase` (e.g., `screenWidth`, `mediaProjection`, `isActive`)
- **Function parameters**: `camelCase` (e.g., `resultData`, `callback`, `className`)
- **Constants**: `UPPER_SNAKE_CASE` (e.g., `TAG`, `BUFFER_COUNT`)

```kotlin
class ExampleClass
{
    // Member variables in camelCase
    private var screenWidth = 0
    private var mediaProjection: MediaProjection? = null
    
    // Function parameters in camelCase
    fun processData(inputData: String, callback: (String) -> Unit)
    {
        // Local variables in snake_case
        val processed_result = inputData.uppercase()
        val final_output = "Result: $processed_result"
        
        callback(final_output)
    }
}
```

#### Benefits of This Style
- **Instant recognition**: Variable scope is immediately visible
- **Improved debugging**: Easy to distinguish locals from members
- **Better readability**: Clean visual structure with separated braces
- **Consistent codebase**: All new code follows the same patterns

### Documentation
- Update this file when patterns change
- Document complex business logic
- Use clear variable and function names
- Add TODO comments for future improvements

## Current Architecture Status

### Phase 1: Current State (Coupled)
- UI and business logic mixed in ScreenCaptureService
- Direct calls between UI and YOLO detector
- Monolithic service class

### Phase 2: Target State (Decoupled)
- Separate UI components with event interfaces
- Controller layer handling business logic
- Clean dependency injection
- Testable, maintainable architecture

## Commit Reminders

Before each commit, ensure:
- [ ] Code follows separation of concerns
- [ ] No business logic in UI classes
- [ ] Interfaces used for layer communication
- [ ] Todo list updated with progress
- [ ] Commit message follows format guidelines
- [ ] Branch name is descriptive

## Build Commands

### Compilation
```bash
JAVA_HOME="C:\\Program Files\\Android\\Android Studio\\jbr" ./gradlew assembleDebug
```

### Compilation (Skip Lint)
```bash
JAVA_HOME="C:\\Program Files\\Android\\Android Studio\\jbr" ./gradlew assembleDebug -x lint
```

### Lint Check
```bash
JAVA_HOME="C:\\Program Files\\Android\\Android Studio\\jbr" ./gradlew lintDebug
```

### Type Check
```bash
JAVA_HOME="C:\\Program Files\\Android\\Android Studio\\jbr" ./gradlew compileDebugKotlin
```

**Note**: The key is using `JAVA_HOME` pointing to Android Studio's JBR (Java Runtime) and using `./gradlew` (not `gradlew.bat` or `cmd.exe`).

## Atlassian Integration

This project is connected to the following Atlassian resources:

### Jira Project
- **Cloud ID**: `99236c42-6dc2-4abb-a828-8ad797987eb0`
- **Project**: PokeGoalsHelper (Key: **PGH**)
- **URL**: https://quillstudios.atlassian.net
- **Available Issue Types**: Task, Sub-task

### Confluence Space
- **Cloud ID**: `99236c42-6dc2-4abb-a828-8ad797987eb0`
- **Space**: PokeGoalsHelper (Key: **PokeGoalsH**, ID: 98676)
- **URL**: https://quillstudios.atlassian.net/wiki

When referencing Jira or Confluence in conversations, always use these project identifiers.

## Claude Instructions

When working on this project:
1. Always create a new branch for each task
2. Commit frequently with descriptive messages
3. Use TodoWrite tool to track progress
4. Follow MVC/event-driven patterns
5. Separate UI logic from business logic
6. Test changes incrementally
7. Update documentation when architecture changes
8. Use the build commands above for compilation testing
9. When asked about Jira/Confluence, use the Atlassian resources defined above

## JIRA Management Guidelines

### Task Status Updates
- **NEVER edit task descriptions** to update status or progress
- **ALWAYS use comments** to provide status updates instead
- **Preserve original task descriptions** - they document the original intent and requirements
- **Comments should include**: current progress, blockers, next steps, implementation notes

### Task Completion Rules
- **NEVER mark tasks as "Done"** without explicit user approval
- **Code compilation ≠ task completion** - must be tested on actual device
- **Implementation complete ≠ task complete** - requires validation and testing
- **Always check with user** before transitioning tasks to "Done" status
- **Use "In Progress"** for actively worked tasks, even if implementation is complete

### Progress Documentation
- **Use comments for progress updates**:
  ```
  Progress Update:
  ✅ Implementation complete - added close functionality to drawer
  ✅ Compilation successful 
  🔄 Next steps: Device testing required before marking complete
  📋 Files modified: ResultsBottomDrawer.kt, enhanced swipe-to-dismiss
  ```

### Status Workflow
1. **To Do** → Start working
2. **In Progress** → Implementation and testing in progress
3. **Ready for Review** → Implementation complete, needs device testing/validation
4. **Done** → Only after user confirmation that feature works as expected

### Implementation vs Completion
- **Implementation Complete**: Code written, compiles, logic appears correct
- **Task Complete**: Feature tested on device, user validated, works as intended
- **Always distinguish** between these two states in updates

### Example Comment Format
```
**Implementation Progress:**
- ✅ Added swipe-to-dismiss functionality 
- ✅ Enhanced close buttons in both states
- ✅ Build compilation successful
- 🔄 **Pending**: Device testing to validate gesture behavior
- 🔄 **Pending**: User validation of close functionality

**Technical Details:**
- Modified touch handling in ResultsBottomDrawer.kt
- Enhanced gesture detection for full dismiss vs collapse
- Added header close button for expanded state

**Next Steps:**
- Device testing required
- User validation needed before marking Done
```

This preserves original task intent while providing clear progress visibility.