# Implementation Waves

**Generated:** 2026-03-30 14:58:37

This document outlines a cluster-based implementation plan for placeholder remediation.

## Overview

Total remediation effort: **82-110 hours** over 4-6 weeks

### Timeline

- **Wave 1 (P0):** Week 1 - Critical fixes (14-20 hours)
- **Wave 2 (P1):** Weeks 2-3 - High priority (26-34 hours)
- **Wave 3 (P2):** Weeks 4-5 - Medium priority (18-24 hours)
- **Wave 4 (P3):** Later - Nice to have (24-32 hours)

## Wave 1: Critical Fixes (P0)

**Scope:** 83 placeholders
**Timeline:** Week 1
**Effort:** 14-20 hours

### 1.1 Resolve Known Conflicts (3 placeholders, 2 hours)

- `weight_trend`: Update docs to match code (28d)
- `activity_summary`: Update docs to match code (14d)
- `activity_detail`: Needs code review to determine actual time window

### 1.2 Classify Time Windows (74 placeholders, 8-12 hours)

**Method:**
1. Name-based extraction (`*_7d`, `*_28d` patterns) - automatic
2. Code parameter extraction - semi-automatic
3. Manual classification for unclear cases

### 1.3 Add Categories and Descriptions (49 placeholders, 4-6 hours)

**Method:**
- Bulk update from audit semantic analysis
- Use provided classifications from audit report

## Wave 2: High Priority (P1)

**Scope:** 10 placeholders
**Timeline:** Weeks 2-3
**Effort:** 26-34 hours

### 2.1 Add Confidence Logic (11 trend/delta placeholders, 12-16 hours)

**Placeholders:**
- `weight_28d_slope`, `weight_90d_slope`, `weight_7d_median`
- `fm_28d_change`, `lbm_28d_change`
- `waist_28d_delta`, `hip_28d_delta`, `chest_28d_delta`, `arm_28d_delta`, `thigh_28d_delta`
- `vo2max_trend_28d`

**Pattern:** `confidence = calculate_confidence(data_points, time_window_days, 'trend')`

### 2.2 Structured Missing-Value Policy (70 placeholders, 8-10 hours)

**Refactor:**
- Keep legacy string for backward compatibility
- Add structured fields: `available`, `missing_reason`, `value_raw`

### 2.3 Document Data Layer Modules (100 placeholders, 6-8 hours)

**Method:**
- Trace resolver functions to data layer
- Document source tables from SQL queries

## Wave 3: Medium Priority (P2)

**Scope:** 10 placeholders
**Timeline:** Weeks 4-5
**Effort:** 18-24 hours

### 3.1 Integrate Unused Placeholders (67 placeholders, 4-6 hours)

**Method:**
- Product management review for 30 planned placeholders
- Technical review for 37 plausible placeholders
- Create prompt use cases (5-10 quick wins)

### 3.2 Metadata Completeness (111 placeholders, 10-12 hours)

**Target:** Minimum 60% of placeholders with score >60

### 3.3 Production Status (20-30 core placeholders, 4-6 hours)

**Criteria:**
- Metadata completeness >= 80%
- Used-by >= 1
- No known issues
- Time window + confidence defined

## Wave 4: Nice to Have (P3)

**Scope:** 8 placeholders
**Timeline:** Later
**Effort:** 24-32 hours

### 4.1 Validation Framework (16-20 hours)

**Features:**
- Pre-commit hook for normative spec validation
- CI/CD consistency checks (code-catalog)
- Template generator for new placeholders

### 4.2 Migration Guides (8-12 hours)

**Content:**
- Best-practice guide (based on compliant examples)
- Anti-patterns to avoid
- Upgrade path for legacy prompts

## Dependencies

- **Wave 1 → Wave 2:** Time window classification must be complete before confidence logic
- **Wave 2 → Wave 3:** Data layer documentation enables better integration planning
- **Wave 3 → Wave 4:** Production-ready placeholders provide best-practice models

## Success Metrics

### After Wave 1:
- 0 unknown time windows
- 0 unknown categories
- 0 code-documentation conflicts

### After Wave 2:
- 70%+ placeholders with confidence logic
- 100% placeholders with structured missing-value policies
- 100% placeholders with documented data layers

### After Wave 3:
- 50-60% placeholder usage rate
- 60%+ placeholders with metadata completeness >60
- 20-30 production-ready placeholders

### After Wave 4:
- Automated validation in CI/CD
- Best-practice documentation for developers
- Sustainable maintenance process