mitai-jinkendo/.claude/docs/audit/platzhalter/reconciliation-2026-03-30/IMPLEMENTATION_WAVES.md

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