comunidadhll/ai/tasks/pending/TASK-149-scoreboard-correlation-diagnostics.md

id, title, status, type, team, supporting_teams, roadmap_item, priority

id	title	status	type	team	supporting_teams	roadmap_item	priority
TASK-149	Add scoreboard correlation diagnostics	pending	backend	Backend Senior	PM	rcon-full-data	medium

TASK-149 - Add scoreboard correlation diagnostics

Goal

Make missing scoreboard links diagnosable without exposing debug clutter in the normal UI.

Background

When the Foy match had match_url null, investigation required manual inspection of public pages, candidate tables, and historical tables. Backend diagnostics should explain whether:

• no candidates exist
• candidates exist but map/time/score mismatch
• candidates were ambiguous
• candidate URL was unsafe
• relink was not run

The known Foy diagnostic target is:

• server: comunidad-hispana-02
• RCON match key: comunidad-hispana-02:1779310451:1779315851:foywarfare
• expected candidate when available: external match id 1562115

Constraints / DO NOT BREAK

• Do not add visible debug text to historico-partida.html.
• Do not add timeline/source/debug metadata back to normal UI.
• Do not change recent card layout.
• Do not require internet for unit tests.
• Use fixtures/mocks for tests.

Allowed Changes

• A focused backend scoreboard correlation diagnostic command.
• Existing backend correlation/read helpers only when needed to reuse safe candidate selection output.
• Focused backend tests using fixtures or mocks.
• Documentation explaining the missing-scoreboard-button debug sequence.
• This task file when it moves through the task workflow.

Implementation Requirements

1. Add backend diagnostic capability for a given RCON match:
   • preferred command: python -m app.scoreboard_correlation_diagnostics --server comunidad-hispana-02 --match comunidad-hispana-02:1779310451:1779315851:foywarfare
   • optional alternative: also expose it inside storage_diagnostics, but never in normal frontend payloads
2. Diagnostic output must be JSON.
3. Include:
   • rcon_match_key
   • server
   • map
   • started_at / ended_at / closed_at / duration_seconds
   • score
   • candidate search window
   • candidate_count
   • top candidate summaries:
     • external_match_id
     • started_at
     • ended_at
     • map
     • score
     • match_url
     • correlation_score
     • rejection_reason if rejected
   • selected_candidate if any
   • final_reason
4. Add a specific diagnostic for the known Foy case.
5. Add docs explaining how to debug a missing scoreboard button:
   • run scoreboard_candidate_backfill
   • run relink
   • run scoreboard_correlation_diagnostics
   • inspect detail endpoint
6. Keep diagnostics out of normal UI.
7. Do not emit raw sensitive data.
8. Do not emit unsafe URLs.

Files to Read First

• AGENTS.md
• ai/architecture-index.md
• ai/repo-context.md
• ai/orchestrator/backend-senior.md
• backend/app/rcon_historical_read_model.py
• Backend correlation/relink code delivered by TASK-148.

Expected Files to Modify

• One backend diagnostic command module or the existing diagnostics module.
• Existing safe correlation/read helper files only if necessary.
• Focused backend diagnostic tests using fixtures/mocks.
• One focused documentation file for the debug workflow.
• This task file after moving it through the workflow.

Do not add frontend debug surfaces or widen the normal detail payload for this task.

Validation

• python -m compileall backend/app
• python -m app.scoreboard_correlation_diagnostics --server comunidad-hispana-02 --match comunidad-hispana-02:1779310451:1779315851:foywarfare
• python -m app.storage_diagnostics
• powershell -ExecutionPolicy Bypass -File scripts/run-integration-tests.ps1
• node --check frontend/assets/js/historico-partida.js
• node --check frontend/assets/js/historico.js
• node --check frontend/assets/js/historico-recent-live.js
• Review git diff --name-only and confirm the changed files match this task.

Manual Verification

1. Run diagnostics for Foy and verify it explains why 1562115 is selected or why no candidate is selected.
2. Run diagnostics for a match without public candidate and verify it explains no candidates found.
3. Normal frontend pages do not show diagnostics.

Commit Message

chore: add scoreboard correlation diagnostics

Outcome

Document diagnostic fields, known Foy output behavior, documentation added, validation performed, and any follow-up task instead of expanding normal UI payloads.

Change Budget

• Prefer fewer than 5 modified files.
• Prefer changes under 200 lines when feasible.
• Split follow-up work into a new task if the scope grows.