---
id: TASK-149
title: Add scoreboard correlation diagnostics
status: pending
type: backend
team: Backend Senior
supporting_teams:
  - PM
roadmap_item: rcon-full-data
priority: 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.