pam ▸ docs/generated/ralph_loop_2026-03-16_top_matched_research_candidate.md
updated 2026-03-28

Ralph Loop 2026-03-16: Top Matched Research Candidate

Why

PRD-003 candidate review already split matched-research blocker counts from unmatched research inventory, but the operator surfaces still only exposed a single generic top research candidate. That meant semantically valid sleeves could still be hidden whenever unmatched rows sorted above them in the research lane.

Change

  1. Updated research/candidate_review.py to persist top_matched_research_candidate alongside the existing matched-research blocker diagnostics.
  2. Updated research/continuous_loop.py so candidate_review_done events also carry top_matched_research_ticker.
  3. Updated research/status.py and research/discord_status.py so operator summaries show a dedicated matched-research candidate line instead of forcing operators to infer it from blocker counts alone.
  4. Added regression coverage in tests/test_candidate_review.py, tests/test_continuous_loop.py, and tests/test_research_status.py.

Validation

  1. pytest -q tests/test_candidate_review.py tests/test_continuous_loop.py tests/test_research_status.py - 34 passed in 0.16s
  2. python3 -m py_compile research/candidate_review.py research/continuous_loop.py research/status.py research/discord_status.py - passed
  3. python3 research/candidate_review.py --db data/unicorn.db --recent-runs 6 --max-per-state 5 | python3 -c 'import json,sys; payload=json.load(sys.stdin); print("matched_research_candidate_count=", payload.get("matched_research_candidate_count")); print("top_matched_research_candidate=", (payload.get("top_matched_research_candidate") or {}).get("ticker")); print("top_research_candidate=", ((payload.get("research_candidates") or [None])[0] or {}).get("ticker"))' - matched_research_candidate_count= 3 - top_matched_research_candidate= KXBRUVSEAT-35 - top_research_candidate= KXBRUVSEAT-35
  4. python3 research/status.py and python3 research/discord_status.py - blocked in this environment because runtime_config.py imports yaml and PyYAML is not installed. Status/Discord formatting is covered by the focused tests above.

Outcome

Operator-facing handoffs now identify the best semantically matched research row directly, which is a cleaner PRD-003 signal when the broader research queue contains unmatched inventory noise.