---
status: pending
priority: p2
issue_id: "002"
tags: ["refactor", "maintainability", "python"]
dependencies: []
---

# Refactor PHQ-8 Scoring Magic Numbers

Extract PHQ-8 scoring constants in `src/helia/assessment/core.py` to improve maintainability and readability.

## Problem Statement

The Kieran Python Reviewer and Pattern Recognition Specialist identified "magic numbers" in the PHQ-8 scoring logic within `src/helia/assessment/core.py`. Hardcoded values make the code difficult to understand and risky to modify.

## Findings

- **File:** `src/helia/assessment/core.py`
- **Issue:** Hardcoded integers representing PHQ-8 scoring thresholds or values.
- **Recommendation:** Extract these into named constants.

## Proposed Solutions

### Option 1: Class-level Constants

**Approach:** Define capitalized constants (e.g., `MIN_SCORE`, `SEVERE_THRESHOLD`) at the top of the class or module.

**Pros:**
- Improves readability (intent is clear).
- Single source of truth for changes.

**Cons:**
- None significant.

## Recommended Action

**To be filled during triage.**

## Technical Details

**Affected files:**
- `src/helia/assessment/core.py`

## Resources

- **Source:** Kieran Python Reviewer / Pattern Recognition Specialist

## Acceptance Criteria

- [ ] All magic numbers in PHQ-8 logic replaced with named constants.
- [ ] Constants defined at module or class level.
- [ ] Logic remains functionally identical (verify with tests if available).

## Work Log

### 2025-12-20 - Initial Creation

**By:** Claude Code

**Actions:**
- Created todo based on code review findings.