Upgrade Ranker visual direction

Honor Scattermind metric hints in ranking
2026-05-26 22:39:03 +02:00 · 2026-05-26 22:31:02 +02:00
5 changed files with 113 additions and 31 deletions
@@ -47,6 +47,8 @@ Ranker's continuation job is narrow:

 `POST /api/rank-feedback` accepts a `prioritix-feature-set-v1`-style payload from Scattermind and returns ranked items plus `buildOrder.doFirst / validateNext / defer / park`. Keep this contract action-first; do not use it as a reason to add generic dashboard, auth, billing, or workspace layers before the bridge has proof.

+Feature items may include optional 1–10 `rankerHints` (`value`, `effort`, `confidence`, `urgency`, `revenue`, `novelty`, `risk`). Ranker blends those explicit Scattermind hints with text heuristics; `effort` is inverted into feasibility. Hints improve the defended order, but `recommendedLane: "defer"` or `"park"` remains a safety rail so dashboard-swamp items do not get promoted by flashy wording.
+
 Recommended payload shape:

 ```json
@@ -69,6 +71,15 @@ Recommended payload shape:
        "userValue": "A tired builder sees the next move without opening a dashboard.",
        "evidenceNeeded": "Can 3 non-AI-native users understand the first recommended action?",
        "proofSteps": ["Show a static result screen to 3 people"],
+        "rankerHints": {
+          "value": 8,
+          "effort": 3,
+          "confidence": 7,
+          "urgency": 6,
+          "revenue": 4,
+          "novelty": 5,
+          "risk": 3
+        },
        "dependencies": [],
        "risk": "May become generic roadmap UI if the source context is lost.",
        "recommendedLane": "validate-next",
@@ -4,9 +4,9 @@
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="theme-color" content="#101626" />
-    <meta name="rank-version" content="2.0.0-feedback-map-mvp" />
+    <meta name="rank-version" content="2.1.0-editorial-decision-room" />
    <title>Ranker — ranked feedback maps for messy decisions</title>
-    <link rel="stylesheet" href="/styles.css?v=2.0.0-feedback-map-mvp" />
+    <link rel="stylesheet" href="/styles.css?v=2.1.0-editorial-decision-room" />
  </head>
  <body>
    <main class="page-shell">
@@ -123,6 +123,6 @@
    </main>

    <div class="toast" id="toast" hidden></div>
-    <script src="/app.js?v=2.0.0-feedback-map-mvp" type="module"></script>
+    <script src="/app.js?v=2.1.0-editorial-decision-room" type="module"></script>
  </body>
 </html>
@@ -72,12 +72,39 @@ try {
  assert.equal(data.ranked.find(item => item.id === 'parked-bridge-dashboard').lane.source, 'hint');
  assert.equal(data.ranked.find(item => item.id === 'bridge-contract').provenance.sourceSection, 'concept-map.nextMoves');
  assert.match(data.ranked.find(item => item.id === 'bridge-contract').factors.evidenceNeeded, /Concept Map/);
+  assert.ok(data.ranked.find(item => item.id === 'bridge-contract').factors.metricHints.value === undefined);
  assert.equal(data.brief.source.artifactId, 'snapshot_123');
  assert.match(data.brief.summary, /Source: Tiny shop idea clarity pass · snapshot_123/);
  assert.ok(data.brief.next48Hours.some(item => /Open the source artifact \(snapshot_123\)/i.test(item)));
  assert.ok(data.brief.next48Hours.some(item => /Evidence to collect/i.test(item)));
  assert.match(data.brief.summary, /nearest follow-up|strongest signal/i);
-  console.log(JSON.stringify({ ok: true, top: data.ranked[0].id, provenance: data.input.provenance, buildOrder: data.buildOrder }, null, 2));
+
+  const hintedResponse = await fetch(`${base}/api/rank-feedback`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      schema: 'prioritix-feature-set-v1',
+      sourceName: 'Scattermind',
+      artifactId: 'concept_map_metric_hints',
+      idea: 'A concept map produced possible next moves for an overwhelmed solo builder.',
+      context: 'Defend build order from explicit Scattermind scoring hints plus text; do not let flashy platform language win.',
+      mode: 'mvp',
+      featureSet: {
+        features: [
+          { id: 'manual-concierge-proof', title: 'Manual concierge proof', description: 'Personally rank three real idea snapshots and turn each into a small build order preview.', rankerHints: { value: 9, effort: 2, confidence: 8, urgency: 8, risk: 2 }, evidenceNeeded: 'Will a tired user act on the first recommended move?', proofSteps: ['Run 3 manual previews'] },
+          { id: 'ai-autopilot-roadmap', title: 'AI autopilot roadmap platform', description: 'Generate a full automated roadmap with dashboard, workspace, team voting, sync, and integrations.', rankerHints: { value: 5, effort: 9, confidence: 3, urgency: 3, risk: 9 } },
+          { id: 'nice-export', title: 'Clean export of the build order', description: 'Turn the defended order into a shareable text brief.', scoring: { impact: 7, complexity: 3, certainty: 7, timing: 5, assumptionRisk: 3 }, recommendedLane: 'validate-next' },
+        ],
+      },
+    }),
+  });
+  assert.equal(hintedResponse.status, 200);
+  const hinted = await hintedResponse.json();
+  assert.equal(hinted.ranked[0].id, 'manual-concierge-proof', 'explicit low-effort/high-confidence Scattermind hints should defend the manual proof slice');
+  assert.ok(hinted.ranked[0].factors.metricHints.value >= 9);
+  assert.ok(hinted.ranked.find(item => item.id === 'ai-autopilot-roadmap').metrics.risk > hinted.ranked[0].metrics.risk);
+
+  console.log(JSON.stringify({ ok: true, top: data.ranked[0].id, hintedTop: hinted.ranked[0].id, provenance: data.input.provenance, buildOrder: data.buildOrder }, null, 2));
 } finally {
  server.kill('SIGTERM');
 }
@@ -145,6 +145,33 @@ function cleanTextList(value, maxItems = 6, maxText = 180) {
  return list.map(item => cleanText(item, maxText)).filter(Boolean).slice(0, maxItems);
 }

+function cleanMetricHints(item = {}) {
+  const raw = {
+    ...(item.factors && typeof item.factors === 'object' ? item.factors : {}),
+    ...(item.scoring && typeof item.scoring === 'object' ? item.scoring : {}),
+    ...(item.rankerHints && typeof item.rankerHints === 'object' ? item.rankerHints : {}),
+  };
+  const aliases = {
+    value: ['value', 'impact', 'userImpact', 'userValueScore'],
+    effort: ['effort', 'buildEffort', 'complexity'],
+    confidence: ['confidence', 'certainty'],
+    urgency: ['urgency', 'timing'],
+    revenue: ['revenue', 'commercial', 'buyerSignal'],
+    novelty: ['novelty', 'differentiation', 'originality'],
+    risk: ['risk', 'assumptionRisk', 'scopeRisk'],
+  };
+  return Object.fromEntries(Object.entries(aliases).map(([metric, keys]) => {
+    const found = keys.map(key => raw[key] ?? item[key]).find(value => value !== undefined && value !== null && value !== '');
+    const parsed = Number.parseFloat(found);
+    return [metric, Number.isFinite(parsed) ? Math.min(10, Math.max(1, parsed)) : null];
+  }).filter(([, value]) => value !== null));
+}
+
+function blendMetric(heuristic, explicit, weight = 0.58) {
+  if (!Number.isFinite(explicit)) return heuristic;
+  return Math.max(1, Math.min(10, heuristic * (1 - weight) + explicit * weight));
+}
+
 function rowsFrom(result) {
  const rows = result?.rows || result?.documents;
  if (!Array.isArray(rows)) throw new Error('Appwrite returned an invalid table response');
@@ -397,7 +424,7 @@ function normalizeFeatureOption(item, index, fallbackId = 'feature') {
    id: cleanText(item?.id || item?.key || `${fallbackId}-${index + 1}`, 80) || `${fallbackId}-${index + 1}`,
    title,
    description: cleanText(descriptionParts.join(' '), 760),
-    factors: { userValue, evidenceNeeded, risk, proofSteps, dependencies, recommendedLane },
+    factors: { userValue, evidenceNeeded, risk, proofSteps, dependencies, recommendedLane, metricHints: cleanMetricHints(item) },
    provenance: {
      sourceId: cleanText(item?.sourceId || item?.sourceArtifactId || item?.id || '', 120),
      sourceSection,
@@ -431,7 +458,7 @@ function scoreOption(option, mode, context = '') {
  const normalizedLaneHint = normalizeLaneHint(laneHint);
  const laneBoost = /do|first|now|build/.test(laneHint) ? 0.55 : /validate|test|proof/.test(laneHint) ? 0.25 : /defer|park|cut/.test(laneHint) ? -0.75 : 0;
  const lanePenalty = normalizedLaneHint === 'park' ? 18 : normalizedLaneHint === 'defer' ? 9 : 0;
-  const metrics = {
+  const heuristicMetrics = {
    value: Math.min(10, 4.8 + hits(text, wordSets.value) * 0.9 + coreLoopHits * 0.8 + bridgeHits * 0.75 + proofHits * 0.2 + hits(context, wordSets.value) * 0.15),
    feasibility: Math.max(1, Math.min(10, 8.2 - effortHits * 0.8 - riskHits * 0.35 - dependencyPenalty + Math.min(1.1, coreLoopHits * 0.28 + bridgeHits * 0.18 + proofHits * 0.12))),
    confidence: Math.max(1, Math.min(10, 5.8 + coreLoopHits * 0.35 + bridgeHits * 0.28 + proofHits * 0.32 + hits(text, ['manual', 'existing', 'already', 'simple', 'clear', 'known']) * 0.7 - hits(text, ['maybe', 'unknown', 'new market', 'all users']) * 0.9)),
@@ -440,6 +467,17 @@ function scoreOption(option, mode, context = '') {
    novelty: Math.min(10, 4.1 + hits(text, wordSets.novelty) * 0.95),
    risk: Math.min(10, 2.5 + riskHits * 1.1 + Math.max(0, effortHits - 2) * 0.45 + swampHits * 0.2 + dependencyPenalty),
  };
+  const hinted = factors.metricHints || {};
+  const hintedFeasibility = Number.isFinite(hinted.effort) ? 11 - hinted.effort : undefined;
+  const metrics = {
+    value: blendMetric(heuristicMetrics.value, hinted.value),
+    feasibility: blendMetric(heuristicMetrics.feasibility, hintedFeasibility),
+    confidence: blendMetric(heuristicMetrics.confidence, hinted.confidence),
+    urgency: blendMetric(heuristicMetrics.urgency, hinted.urgency),
+    revenue: blendMetric(heuristicMetrics.revenue, hinted.revenue),
+    novelty: blendMetric(heuristicMetrics.novelty, hinted.novelty),
+    risk: blendMetric(heuristicMetrics.risk, hinted.risk),
+  };
  const weights = mode.weights;
  const weighted = Object.entries(weights).reduce((sum, [key, weight]) => sum + metrics[key] * weight, 0);
  const possible = Object.entries(weights).reduce((sum, [_key, weight]) => sum + Math.abs(weight) * 10, 0);
@@ -475,11 +513,11 @@ function reasonFor(option) {
  const m = option.metrics;
  if (option.lane?.id === 'do' && /snapshot|concept map|feature set|build order|rank/i.test(`${option.title} ${option.description}`)) return 'it strengthens the Scattermind → Ranker bridge instead of inventing a generic workspace';
  if (option.factors?.evidenceNeeded && m.confidence >= 6.4) return 'it names the evidence needed, so the next move can be tested instead of guessed';
-  if (m.feasibility >= 7.2 && m.value >= 6.2) return 'high enough value with low enough delivery drag to create fast signal';
-  if (m.revenue >= 6.4) return 'clearer buyer or money signal than the rest of the list';
-  if (m.risk >= 6.5) return 'interesting, but it carries assumption risk that should be tested before build';
-  if (m.novelty >= 6.7) return 'more differentiated than the safe options, but still needs proof';
-  return 'balanced tradeoff across value, effort, confidence, and timing';
+  if (m.feasibility >= 7.2 && m.value >= 6.2) return 'it has high enough value with low enough delivery drag to create fast signal';
+  if (m.revenue >= 6.4) return 'it has a clearer buyer or money signal than the rest of the list';
+  if (m.risk >= 6.5) return 'it is interesting, but carries assumption risk that should be tested before build';
+  if (m.novelty >= 6.7) return 'it is more differentiated than the safe options, but still needs proof';
+  return 'it has the best balanced tradeoff across value, effort, confidence, and timing';
 }

 function concernFor(option) {
@@ -498,7 +536,7 @@ function createDecisionBrief({ idea, context, mode, ranked, provenance }) {
  const risky = ranked.slice().sort((a, b) => b.metrics.risk - a.metrics.risk)[0];
  const deferred = ranked.filter(item => ['defer', 'park'].includes(item.lane.id)).slice(0, 3);
  const sourceLabel = [provenance?.snapshotTitle, provenance?.artifactId].filter(Boolean).join(' · ');
-  const theme = top ? `The strongest signal is “${top.title}” because it has ${reasonFor(top)}.` : 'The list needs at least two options before ranking becomes useful.';
+  const theme = top ? `The strongest signal is “${top.title}” because ${reasonFor(top)}.` : 'The list needs at least two options before ranking becomes useful.';
  return {
    headline: top ? `Start with ${top.title}` : 'Add options to get a ranked feedback map',
    summary: `${theme}${second ? ` “${second.title}” is the nearest follow-up, not a parallel first step.` : ''}${sourceLabel ? ` Source: ${sourceLabel}.` : ''}`,
Author	SHA1	Message	Date
OpenClaw Bot	962fb3a46f	Upgrade Ranker visual direction	2026-05-26 22:39:03 +02:00
OpenClaw Bot	e8085663bd	Honor Scattermind metric hints in ranking	2026-05-26 22:31:02 +02:00