helia/todos/002-completed-p2-magic-numbers-refactor.md

status, priority, issue_id, tags, dependencies

status	priority	issue_id	tags	dependencies
pending	p2	002	refactor maintainability python

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.