---
scope: <scope-name>                # lowercase with hyphens
created: <YYYY-MM-DDTHHmmssZ>      # creation timestamp (UTC)
updated: <YYYY-MM-DDTHHmmssZ>      # last update timestamp (UTC)
version: <int>                     # increment on updates
---

# Implementation Plan: [Feature Name]

## Overview
[2-3 sentence summary of what this feature does and why it's needed]

## Phases

- [ ] [Phase 1: Phase Name](#phase-1-phase-name)
- [ ] [Phase 2: Phase Name](#phase-2-phase-name)
- [ ] [Phase N: End-to-End Validation](#phase-n-end-to-end-validation)

## Requirements

### Functional Requirements
- [FR1: Specific functional requirement]
- [FR2: Specific functional requirement]

### Non-Functional Requirements
- [NFR1: Performance, scalability, security requirements]
- [NFR2: Code quality, testing, documentation requirements]

### Assumptions & Constraints
- [Assumption 1]
- [Constraint 1]

## Architecture Analysis

### Current State
- [Description of relevant existing architecture]
- [Key files/modules that will be affected]

### Proposed Changes
- [Change 1: file path and high-level description]
- [Change 2: file path and high-level description]

### Design Decisions
1. **[Decision 1]**: [Rationale]
2. **[Decision 2]**: [Rationale]

## File Inventory

### Files to Create
- `path/to/new_file.py` - [Purpose]
- `path/to/test_new_file.py` - [Test coverage]

### Files to Modify
- `path/to/existing_file.py` - [What changes]

### Files to Delete (if any)
- `path/to/deprecated_file.py` - [Reason for removal]

## Implementation Steps
[See Phase Structure below]

## Testing Requirements
[See Testing Format below]

## Code Quality Requirements
[See Quality Checklist below]

## Dependencies

### External Dependencies
- [New package: version and purpose]

### Internal Dependencies
- [Other features or modules this depends on]

### Blocking Items
- [Items that must be completed first]

## Acceptance Criteria
[See Acceptance Criteria Format below]

## Future Enhancements
[Optional features to consider for future iterations]

### Phase N: [Phase Name - e.g., Implement process_dataframe Function]
**Goal**: [What this phase accomplishes - be specific about the single feature/function]

**Dependencies**: None / Requires Phase X completion

#### Implementation Steps

##### Step N.1: [Specific Implementation Step]
- **File**: `path/to/file.py`
- **Action**: [Detailed, specific action - what code to write]
- **Details**:
  - Create class/function `ClassName` with methods `method1()`, `method2()`
  - Key signatures: `def method1(param: Type) -> ReturnType:`
  - Important implementation notes
- **Why**: [Business/technical reason]
- **Dependencies**: None / Requires Step X.Y
- **Validation**:
  - **Command**: `uv run pytest tests/test_<module>.py::test_<function> -v`
  - **Expected**: Test passes, verifying functionality works correctly
  - **Manual Check**: Function has type hints and docstring

#### Test Steps

##### Step N.T1: Write Unit Tests
- **File**: `tests/test_<module>.py`
- **Action**: Create comprehensive unit tests
- **Details**:
  - Test success cases
  - Test edge cases
  - Test error handling
- **Validation**:
  - **Command**: `uv run pytest tests/test_<module>.py -v`
  - **Expected**: All tests pass with >90% coverage

#### Validation Steps

##### Step N.V1: Validate Implementation
- **Action**: Run all quality checks
- **Validation**:
  - **Command**: `uv run pytest tests/test_<module>.py && uv run ty check . && uv run ruff check`
  - **Expected**: All checks pass
  - **Manual Check**: Code follows project conventions

### Phase N: End-to-End Validation
**Goal**: Verify all phases work together and meet acceptance criteria

#### Step N.1: Run Full Test Suite
- **Validation**:
  - **Command**: `uv run pytest -v`
  - **Expected**: All tests pass
  - **Manual Check**: Code coverage >= 90%

#### Step N.2: Verify Acceptance Criteria
- **Action**: Check all acceptance criteria from plan overview
- **Validation**:
  - **Command**: `uv run ruff check && uv run ty check . && uv tool run pydoclint`
  - **Expected**: All quality checks pass
  - **Manual Check**: All acceptance criteria checkboxes complete

## Testing Requirements

### Unit Tests

#### Test File: `tests/test_<module>.py`
- **Test 1**: `test_<function_name>_success_case`
  - Given: [Initial state]
  - When: [Action]
  - Then: [Expected outcome]

- **Test 2**: `test_<function_name>_edge_case`
  - Given: [Edge case setup]
  - When: [Action]
  - Then: [Expected handling]

- **Test 3**: `test_<function_name>_error_handling`
  - Given: [Error condition]
  - When: [Action]
  - Then: [Expected error/exception]

### Integration Tests
- **Scenario 1**: [End-to-end flow description]
- **Scenario 2**: [Integration between components]

## Code Quality Requirements

- [ ] All functions have type hints
- [ ] All public APIs have Google-style docstrings
- [ ] Code follows project conventions
- [ ] No code duplication (DRY principle)
- [ ] Error handling with clear messages
- [ ] Passes `uv run ruff check`
- [ ] Passes `uv run ty check .`
- [ ] Passes docstring linting

## Acceptance Criteria

### Functional Acceptance
- [ ] [Specific, testable criterion 1]
- [ ] [Specific, testable criterion 2]
- [ ] [Specific, testable criterion 3]

### Quality Acceptance
- [ ] All unit tests pass (`uv run pytest`)
- [ ] All public functions have a test
- [ ] Code coverage >= 90%
- [ ] Type checking passes (`uv run ty check .`)
- [ ] Linting passes (`uv run ruff check`)
- [ ] Docstring validation passes
- [ ] No security vulnerabilities

### Documentation Acceptance
- [ ] Code is documented with Google-style docstrings
- [ ] README updated (if applicable)
- [ ] Examples provided in docstrings