|
| 1 | +<!doctype html> |
| 2 | +<html lang="en"> |
| 3 | +<head> |
| 4 | + <meta charset="utf-8"> |
| 5 | + <title>Implementation Plan: Issue #148 EnergyBank v1 Cleanup and Docs</title> |
| 6 | + <meta name="viewport" content="width=device-width, initial-scale=1"> |
| 7 | + <style> |
| 8 | + body { margin: 0; font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #f6f7f9; color: #1f2937; line-height: 1.5; } |
| 9 | + main { max-width: 1100px; margin: 0 auto; padding: 32px; } |
| 10 | + section { background: #fff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 20px; margin: 16px 0; } |
| 11 | + h1, h2 { line-height: 1.2; margin-top: 0; } |
| 12 | + code { background: #f3f4f6; padding: 2px 5px; border-radius: 4px; } |
| 13 | + .badge { display: inline-block; padding: 4px 10px; border-radius: 999px; background: #dcfce7; color: #166534; font-size: 12px; font-weight: 700; } |
| 14 | + .risk { border-left: 4px solid #dc2626; } |
| 15 | + .approval { border-left: 4px solid #d97706; } |
| 16 | + </style> |
| 17 | +</head> |
| 18 | +<body> |
| 19 | +<main> |
| 20 | + <h1>Implementation Plan: Issue #148 EnergyBank v1 Cleanup and Docs</h1> |
| 21 | + <p class="badge">Approved and implemented</p> |
| 22 | + |
| 23 | + <section> |
| 24 | + <h2>Task Summary</h2> |
| 25 | + <p>Audit remaining EnergyBank v1 code and documentation, then either remove obsolete v1 paths or explicitly document them as compatibility fallback. Update scoring docs so they describe the shipped v2 behavior rather than pending design language.</p> |
| 26 | + </section> |
| 27 | + |
| 28 | + <section> |
| 29 | + <h2>Current Behavior</h2> |
| 30 | + <ul> |
| 31 | + <li><code>internal/health/energy.go::computeEnergyBank</code> is still called by <code>internal/health/scoring.go</code>.</li> |
| 32 | + <li><code>internal/storage/briefing.go</code> computes the health response through the v1 path first, then overrides display bank/capacity/drain/verdict from <code>energy_snapshots</code> when a v2 snapshot exists.</li> |
| 33 | + <li><code>internal/storage/energy_history.go::SaveEnergyBankSnapshot</code> still writes legacy <code>daily_scores.energy_*</code> columns; <code>GetEnergyHistory</code> serves the older EOD history path.</li> |
| 34 | + <li><code>internal/storage/energy_history_v2.go</code> serves the newer hourly <code>energy_snapshots</code> path.</li> |
| 35 | + <li><code>SCORING.md</code> still says EnergyBank is computed in <code>internal/health/energy.go::computeEnergyBank</code>, while <code>ENERGY_BANK.md</code> includes v2 design/cutover history and says old formula stays live in older roadmap text.</li> |
| 36 | + </ul> |
| 37 | + </section> |
| 38 | + |
| 39 | + <section> |
| 40 | + <h2>Desired Behavior</h2> |
| 41 | + <ul> |
| 42 | + <li>Every remaining v1 reference is either removed or labeled as compatibility/fallback with a current reason.</li> |
| 43 | + <li>Docs describe the shipped v2 state machine, snapshot table, personal verdict bands, and legacy daily columns accurately.</li> |
| 44 | + <li>No destructive DB cleanup is bundled unless separately approved and reversible.</li> |
| 45 | + <li>Dashboard, Telegram, AI prompt, and MCP/debug paths continue to render EnergyBank correctly.</li> |
| 46 | + </ul> |
| 47 | + </section> |
| 48 | + |
| 49 | + <section> |
| 50 | + <h2>Assumptions And Unknowns</h2> |
| 51 | + <ul> |
| 52 | + <li>Assumption: do not drop <code>daily_scores.energy_*</code> in this PR; keep or deprecate them unless a separate migration is approved.</li> |
| 53 | + <li>Assumption: <code>computeEnergyBank</code> may still be needed as a bootstrap/fallback when no v2 snapshot exists.</li> |
| 54 | + <li>Unknown: whether the legacy sparkline path is still used by any client after the v2 hourly chart.</li> |
| 55 | + <li>Unknown: whether production has enough v2 stability to remove fallback behavior entirely; issue says at least 7 production days without material issues.</li> |
| 56 | + </ul> |
| 57 | + </section> |
| 58 | + |
| 59 | + <section> |
| 60 | + <h2>Files Likely To Change</h2> |
| 61 | + <ul> |
| 62 | + <li><code>internal/health/energy.go</code> and <code>internal/health/scoring.go</code> - only if v1 fallback can be safely removed or renamed as legacy.</li> |
| 63 | + <li><code>internal/storage/briefing.go</code> - clarify or simplify v1-to-v2 override comments and persistence behavior.</li> |
| 64 | + <li><code>internal/storage/energy_history.go</code>, <code>internal/storage/energy_history_v2.go</code>, and related UI handlers - audit whether legacy EOD history is still needed.</li> |
| 65 | + <li><code>SCORING.md</code>, <code>ENERGY_BANK.md</code>, <code>README.md</code>, <code>AGENTS.md</code>, <code>CLAUDE.md</code> - update current methodology and compatibility notes.</li> |
| 66 | + <li><code>internal/health/*energy*_test.go</code> and storage energy tests - update tests only where they pin obsolete v1 behavior.</li> |
| 67 | + </ul> |
| 68 | + </section> |
| 69 | + |
| 70 | + <section> |
| 71 | + <h2>Implementation Steps</h2> |
| 72 | + <ol> |
| 73 | + <li>Run <code>git grep computeEnergyBank</code>, <code>git grep SaveEnergyBankSnapshot</code>, and <code>git grep energy_</code> to build a final removal/deprecation list.</li> |
| 74 | + <li>Trace dashboard, Telegram report, AI prompt, MCP, and chart reads to identify which paths still depend on legacy daily columns.</li> |
| 75 | + <li>Decide between two safe paths: docs-only deprecation of v1 fallback, or code removal where no live callsite remains.</li> |
| 76 | + <li>Update methodology docs first so reviewers can check intended current behavior.</li> |
| 77 | + <li>Apply the smallest code cleanup that matches the audit; avoid schema drops.</li> |
| 78 | + <li>Run EnergyBank-focused tests and full Go verification.</li> |
| 79 | + </ol> |
| 80 | + </section> |
| 81 | + |
| 82 | + <section> |
| 83 | + <h2>Impact</h2> |
| 84 | + <ul> |
| 85 | + <li><strong>Data:</strong> no destructive migration planned; legacy columns remain unless separately approved.</li> |
| 86 | + <li><strong>API/UX:</strong> EnergyBank JSON shape should remain compatible.</li> |
| 87 | + <li><strong>Docs:</strong> methodology docs become the main output if code still needs v1 fallback.</li> |
| 88 | + <li><strong>Deployment:</strong> normal app deploy only if production code changes; docs-only changes need no deploy for runtime behavior.</li> |
| 89 | + </ul> |
| 90 | + </section> |
| 91 | + |
| 92 | + <section> |
| 93 | + <h2>Test Plan</h2> |
| 94 | + <ul> |
| 95 | + <li><code>go test ./internal/health -run "Test.*Energy|Test.*Verdict" -count=1</code></li> |
| 96 | + <li><code>go test ./internal/storage -run "Test.*Energy" -count=1</code></li> |
| 97 | + <li><code>go test ./internal/ui -run "Test.*Energy|Test.*Dashboard" -count=1</code> if UI/chart handlers change.</li> |
| 98 | + <li><code>go test ./...</code></li> |
| 99 | + <li><code>go vet ./...</code></li> |
| 100 | + <li>Manual QA if deployed: confirm dashboard hero EnergyBank, hourly chart, and Telegram morning report still render.</li> |
| 101 | + </ul> |
| 102 | + </section> |
| 103 | + |
| 104 | + <section class="risk"> |
| 105 | + <h2>Risks And Edge Cases</h2> |
| 106 | + <ul> |
| 107 | + <li>Removing v1 too early can break cold-start tenants or days with no v2 snapshot.</li> |
| 108 | + <li>Docs can become inconsistent if <code>AGENTS.md</code> and <code>CLAUDE.md</code> are not kept in lockstep.</li> |
| 109 | + <li>Legacy daily columns may still support old chart or AI history paths; audit before removal.</li> |
| 110 | + <li>Changing EnergyBank behavior under a cleanup issue would be out of scope.</li> |
| 111 | + </ul> |
| 112 | + </section> |
| 113 | + |
| 114 | + <section> |
| 115 | + <h2>Rollback Plan</h2> |
| 116 | + <p>For docs/test cleanup, revert the PR. For any code removal, restore the legacy fallback callsite and tests. No database rollback is expected because schema drops are excluded from this plan.</p> |
| 117 | + </section> |
| 118 | + |
| 119 | + <section> |
| 120 | + <h2>Open Questions</h2> |
| 121 | + <ul> |
| 122 | + <li>Should <code>computeEnergyBank</code> remain as a named legacy fallback until all tenants have v2 snapshots?</li> |
| 123 | + <li>Is the old EOD <code>GetEnergyHistory</code> path still needed by any frontend or mobile client?</li> |
| 124 | + <li>Do we want a separate future issue for dropping <code>daily_scores.energy_*</code> columns after compatibility expires?</li> |
| 125 | + </ul> |
| 126 | + </section> |
| 127 | + |
| 128 | + <section class="approval"> |
| 129 | + <h2>Approval Gate</h2> |
| 130 | + <p>Approved by the user on 2026-06-06 before implementation.</p> |
| 131 | + </section> |
| 132 | + |
| 133 | + <section> |
| 134 | + <h2>Implementation Result</h2> |
| 135 | + <ul> |
| 136 | + <li>Renamed <code>computeEnergyBank</code> to <code>computeLegacyEnergyBank</code> to make the remaining v1 behavior explicitly compatibility-only.</li> |
| 137 | + <li>Kept the legacy fallback behavior unchanged for fresh tenants and days before a v2 snapshot exists.</li> |
| 138 | + <li>Updated storage, server, UI, and chart comments that still described v2 as passive, pending, or waiting for a future UI flip.</li> |
| 139 | + <li>Updated <code>SCORING.md</code> and <code>ENERGY_BANK.md</code> so v2 is documented as the current shipped path and <code>daily_scores.energy_*</code> columns are documented as legacy compatibility columns.</li> |
| 140 | + <li>No schema drops or destructive database cleanup were included.</li> |
| 141 | + </ul> |
| 142 | + </section> |
| 143 | + |
| 144 | + <section> |
| 145 | + <h2>Verification Run</h2> |
| 146 | + <ul> |
| 147 | + <li><code>gofmt -w</code> on changed Go files.</li> |
| 148 | + <li><code>go test ./internal/health -run "Test.*Energy|Test.*Verdict" -count=1</code></li> |
| 149 | + <li><code>go test ./internal/storage -run "Test.*Energy" -count=1</code></li> |
| 150 | + <li><code>go test ./internal/ui -run "Test.*Energy|Test.*Dashboard" -count=1</code></li> |
| 151 | + <li><code>go test ./...</code></li> |
| 152 | + <li><code>go vet ./...</code></li> |
| 153 | + <li><code>git diff --check</code></li> |
| 154 | + </ul> |
| 155 | + </section> |
| 156 | + |
| 157 | + <section> |
| 158 | + <h2>Known Limitations And Follow-Up</h2> |
| 159 | + <ul> |
| 160 | + <li>The legacy fallback is intentionally still present; removing it would need a separate compatibility decision.</li> |
| 161 | + <li><code>daily_scores.energy_*</code> columns remain in place and should only be removed by a future explicit migration.</li> |
| 162 | + <li>The day-level history endpoint remains available for compatibility and AI verdict-history context.</li> |
| 163 | + </ul> |
| 164 | + </section> |
| 165 | +</main> |
| 166 | +</body> |
| 167 | +</html> |
0 commit comments