From 28ba9d58b992cb723b3f657afc166681aeb4dc79 Mon Sep 17 00:00:00 2001
From: Monster0506 <tjraklovits@gmail.com>
Date: Sun, 20 Sep 2026 04:37:15 -0400
Subject: [PATCH] Document why the BLS-grounded Market Potential pipeline isn't
 wired in (#266)

IMarketPotentialPipeline/MarketPotentialPipeline (#96-99) is registered
in DI but never called from any page - /market-potential and the
Dashboard both still use the AI-guess-only ICompensationEstimationService
(#148). This isn't dead code or an oversight: GetCompensationAsync needs
a BLS series ID per matched occupation, which was meant to come from
O*NET occupation data (#93/#94), but eBay and O*NET were both dropped
from project scope (#177) before that occupation-to-series mapping was
built. Wiring the real pipeline into the UI requires first deciding how
to get that mapping without O*NET.

Documented this on both interfaces (with a cross-reference between them)
so a future contributor doesn't have to re-discover it, and so it isn't
mistaken for abandoned code.

No behavior change - doc comments only.
---
 HumanCapital/ICompensationEstimationService.cs |  9 ++++++++-
 HumanCapital/IMarketPotentialPipeline.cs       | 13 +++++++++++++
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/HumanCapital/ICompensationEstimationService.cs b/HumanCapital/ICompensationEstimationService.cs
index dd25564..f66824d 100644
--- a/HumanCapital/ICompensationEstimationService.cs
+++ b/HumanCapital/ICompensationEstimationService.cs
@@ -8,6 +8,12 @@ namespace MoneyMirror.HumanCapital;
 /// before #24 (real wage-data retrieval + deterministic aggregation) is
 /// built; see #148 for the swap-out plan.
 /// </summary>
+/// <remarks>
+/// #266: #24's real, BLS-grounded replacement already exists and is
+/// registered in DI - see <see cref="IMarketPotentialPipeline"/> - but
+/// nothing in the UI calls it yet. See that type's remarks for why the
+/// swap hasn't happened.
+/// </remarks>
 public interface ICompensationEstimationService
 {
     /// <exception cref="CompensationEstimationException">
@@ -15,5 +21,6 @@ public interface ICompensationEstimationService
     /// </exception>
     Task<CompensationEstimate> EstimateAsync(
         IReadOnlyList<OccupationMatch> occupations,
-        CancellationToken cancellationToken = default);
+        CancellationToken cancellationToken = default
+    );
 }
diff --git a/HumanCapital/IMarketPotentialPipeline.cs b/HumanCapital/IMarketPotentialPipeline.cs
index 1943498..16d9809 100644
--- a/HumanCapital/IMarketPotentialPipeline.cs
+++ b/HumanCapital/IMarketPotentialPipeline.cs
@@ -8,6 +8,19 @@ namespace MoneyMirror.HumanCapital;
 /// prose (#99). No AI participates in choosing the numbers - only in
 /// describing them afterward.
 /// </summary>
+/// <remarks>
+/// #266: not currently called from any page - <c>/market-potential</c> and
+/// the Dashboard still use the AI-guess-only <see cref="ICompensationEstimationService"/>
+/// (#148), whose UI explicitly labels its output "AI estimate - not based
+/// on live wage data". This isn't an oversight: this method needs a BLS
+/// series ID per matched occupation, which was meant to come from O*NET
+/// occupation data (#93/#94, HC4) - but eBay and O*NET were both dropped
+/// from project scope (see #177) before that occupation-to-series mapping
+/// was built. Wiring this in requires deciding how to get that mapping
+/// without O*NET (a fixed lookup table for common titles? a second LLM
+/// call to guess a series ID, no longer "no AI in choosing the number"?)
+/// before this pipeline can replace the AI-guess path in the UI.
+/// </remarks>
 public interface IMarketPotentialPipeline
 {
     /// <returns>