fix(baseball): render CoachHelm insight body on player profile (#474)

[njrini99-code]

What & Why

The CoachHelm engine persists per-player insight detail copy in the body column of baseball_coach_insights (engine-run.ts buildInsightRow sets body: c.body). The player profile and command-center peek panels, however, read only insight.description, which is not populated on engine-generated rows. Result: insight titles rendered but the detail/recommended-action copy was blank, making CoachHelm signals look broken or low-confidence on the two primary places coaches review per-player insights.

Changes

• src/lib/types/index.ts — add optional body?: string | null to BaseballCoachInsight (the player page selects *, so the column is present at runtime; this makes the read type-safe).
• src/components/baseball/player-profile/PlayerInsightsPanel.tsx — compute const detail = insight.body ?? insight.description and use it for both the collapsed one-line preview and the expanded detail paragraph.
• src/components/baseball/command-center/TeamPlayerPeekPanel.tsx — render insight.body ?? insight.description.

Read-model normalization on a single field (body ?? description) keeps legacy/manually-authored rows (which use description) working while surfacing engine rows.

Acceptance criteria

• Player insights UI displays insight.body ?? insight.description.
• Engine-generated insights show full description and recommended action on the player profile.
• Command Center peek panel shows the same text shown in the daily brief (item.body).

Scope

Minimal, display-only. No server-action, auth, migration, or table changes.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
helmv3	Ready	Preview, Comment	Jul 1, 2026 4:59pm

[qodo-code-review]

PR Summary by Qodo

Fix CoachHelm insight detail rendering by falling back to body text

🐞 Bug fix 🕐 10-20 Minutes

AI Description

• Render CoachHelm insight detail text using body ?? description in key player UIs.
• Extend BaseballCoachInsight type to include optional body for engine-generated rows.
• Keep legacy/manual insights working by preserving description as the fallback.

Diagram

graph TD
engine["CoachHelm engine"] --> db[("baseball_coach_insights") ] --> types["BaseballCoachInsight type"] --> fallback{"detail = body ?? description"}
fallback --> playerPanel["PlayerInsightsPanel"]
fallback --> peekPanel["TeamPlayerPeekPanel"]
subgraph Legend
  direction LR
  _svc(["Service"]) ~~~ _db[("Database")] ~~~ _mod["Module/File"] ~~~ _dec{"Decision"}
end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Normalize on write (engine populates `description` too)

• ➕ UI stays simpler (can keep reading description only)
• ➕ Avoids duplicating fallback logic across components
• ➖ Touches ingestion/engine paths; higher risk than a display-only fix
• ➖ Harder to guarantee for already-persisted rows without a backfill

2. Schema unification (rename/migrate to a single canonical column)

• ➕ Eliminates long-term ambiguity between body vs description
• ➕ Reduces future UI/backend mismatch risk
• ➖ Requires migration/backfill and coordinated rollout
• ➖ Larger scope than necessary for the immediate rendering bug

Recommendation: The PR’s approach (UI fallback body ?? description + typed body) is the best fit for the stated minimal, display-only scope. If this mismatch recurs in other surfaces, consider a backend normalization (on write or via a view) to centralize the canonical insight text.

Files changed (3) +8 / -5

Bug fix (3) +8 / -5

TeamPlayerPeekPanel.tsxShow insight detail using 'body ?? description' in peek panel +1/-1

Show insight detail using 'body ?? description' in peek panel

• Updates the insight preview text to render 'insight.body' when present, falling back to 'insight.description' for legacy rows. This prevents engine-generated insights from appearing blank in the command-center peek UI.

src/components/baseball/command-center/TeamPlayerPeekPanel.tsx

PlayerInsightsPanel.tsxNormalize insight detail rendering in player profile panel +6/-4

Normalize insight detail rendering in player profile panel

• Introduces a 'detail' value computed as 'insight.body ?? insight.description'. Uses 'detail' for both the collapsed one-line preview and the expanded detail paragraph, ensuring engine and manual insights render consistently.

src/components/baseball/player-profile/PlayerInsightsPanel.tsx

index.tsAdd optional 'body' to 'BaseballCoachInsight' +1/-0

Add optional 'body' to 'BaseballCoachInsight'

• Extends the shared insight type with 'body?: string | null' to reflect the engine-persisted column and allow type-safe reads in the UI. Keeps 'description' as the existing required field for legacy/manual insights.

src/lib/types/index.ts

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 93 rules

✅ Skills: modern-saas-ui, pproenca-dot-skills-framer-motion

1. Insight type not type-safe 🐞 Bug ⚙ Maintainability

Description

BaseballCoachInsight still requires description: string even though persisted
baseball_coach_insights rows (including engine-generated rows) use body and do not include a
description column, so TypeScript will continue to allow insight.description reads without
null/undefined handling. This undercuts the PR’s “type-safe” goal and makes it easy for future UI
code to regress back to rendering blank insight detail.

Code

src/lib/types/index.ts[R264-266]

  title: string;
  description: string;
+  body?: string | null; // Engine-persisted insight text (baseball_coach_insights.body); UI reads body ?? description

Relevance

⭐⭐⭐ High

Team fixes schema/type drift to match live DB (e.g., corrected nonexistent columns + handwritten
types in PR #618).

PR-#618
PR-#36

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The DB schema and generated DB types show baseball_coach_insights has a body column and no
description, and the engine write-path populates body. The player profile page selects * from
baseball_coach_insights, so any description field is not guaranteed to exist at runtime, which
is why the UI now falls back to body ?? description.

src/lib/types/index.ts[255-279]
supabase/migrations/20260527000000_prod_public_baseline.sql[7508-7521]
src/lib/types/database.ts[1917-1943]
src/lib/baseball/coachhelm/engine-run.ts[878-907]
src/app/baseball/(dashboard)/dashboard/players/[id]/page.tsx[115-124]
src/components/baseball/player-profile/PlayerInsightsPanel.tsx[92-125]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`BaseballCoachInsight` currently models `description` as a required string, but persisted CoachHelm insights are stored in `baseball_coach_insights.body` (and the generated DB types/schema reflect `body` with no `description`). This means UI code can compile while still incorrectly assuming `description` exists.

## Issue Context
This PR updates UI code to render `body ?? description`, implicitly acknowledging that `description` may be absent on engine rows.

## Fix Focus Areas
- src/lib/types/index.ts[255-279]

## Suggested fix
- Update `BaseballCoachInsight` so `description` is `optional` and `nullable` (e.g. `description?: string | null`) to match the reality that many rows will not have it.
- Keep `body?: string | null` (or make it non-optional if you want the interface to represent a full DB row), and consider adding a small comment/docstring clarifying that `body` is the persisted detail field and `description` is legacy/compat.
- Re-run TypeScript checks and update any callers that relied on `description` being required.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

1. Insight type not type-safe 🐞 Bug ⚙ Maintainability

BaseballCoachInsight still requires description: string even though persisted
baseball_coach_insights rows (including engine-generated rows) use body and do not include a
description column, so TypeScript will continue to allow insight.description reads without
null/undefined handling. This undercuts the PR’s “type-safe” goal and makes it easy for future UI
code to regress back to rendering blank insight detail.

Agent Prompt

## Issue description
`BaseballCoachInsight` currently models `description` as a required string, but persisted CoachHelm insights are stored in `baseball_coach_insights.body` (and the generated DB types/schema reflect `body` with no `description`). This means UI code can compile while still incorrectly assuming `description` exists.

## Issue Context
This PR updates UI code to render `body ?? description`, implicitly acknowledging that `description` may be absent on engine rows.

## Fix Focus Areas
- src/lib/types/index.ts[255-279]

## Suggested fix
- Update `BaseballCoachInsight` so `description` is `optional` and `nullable` (e.g. `description?: string | null`) to match the reality that many rows will not have it.
- Keep `body?: string | null` (or make it non-optional if you want the interface to represent a full DB row), and consider adding a small comment/docstring clarifying that `body` is the persisted detail field and `description` is legacy/compat.
- Re-run TypeScript checks and update any callers that relied on `description` being required.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[njrini99-code]

🤖 Mission Control — PR summary

Changes: Player profile + command-center peek now read insight.body ?? insight.description, so engine-generated CoachHelm insight detail copy renders. Adds optional body? to the type. Closes #474.
Areas / risk: Read-path only — low risk.
Watch: Engine-run insights show detail/recommended-action copy instead of blank.
CI: ❌ Business contracts (advisory), Playwright, Supabase RLS, Unit tests failing — review before merge. (lighthouse-preview = known noise.)
Note: Bundled into batch #650.

[qodo-code-review]

CI Feedback 🧐

A test triggered by this PR failed. Here is an AI-generated analysis of the failure:

Action: all

Failed stage: Fail if any required CI check failed [❌]

Failed test name: ""

Failure summary: The action failed because a step explicitly exited with a non-zero status: - The workflow ran echo "One or more CI checks failed." and then executed exit 1, which caused the job to fail with Process completed with exit code 1. - The log does not include the underlying failing CI check(s); this job appears to be a final “fail-if-any-check-failed” gate rather than the original failure.

Relevant error logs: 1: ##[group]Runner Image Provisioner 2: Hosted Compute Agent ... 12: ##[endgroup] 13: ##[group]Runner Image 14: Image: ubuntu-24.04 15: Version: 20260622.220.1 16: Included Software: https://github.com/actions/runner-images/blob/ubuntu24/20260622.220/images/ubuntu/Ubuntu2404-Readme.md 17: Image Release: https://github.com/actions/runner-images/releases/tag/ubuntu24%2F20260622.220 18: ##[endgroup] 19: ##[group]GITHUB_TOKEN Permissions 20: Contents: read 21: Metadata: read 22: ##[endgroup] 23: Secret source: Actions 24: Prepare workflow directory 25: Prepare all required actions 26: Complete job name: all 27: ##[group]Run echo "One or more CI checks failed." 28: �[36;1mecho "One or more CI checks failed."�[0m 29: �[36;1mexit 1�[0m 30: shell: /usr/bin/bash -e {0} 31: env: 32: NEXT_PUBLIC_SUPABASE_URL: *** 33: NEXT_PUBLIC_SUPABASE_ANON_KEY: *** 34: NODE_OPTIONS: --max-old-space-size=8192 35: ##[endgroup] 36: One or more CI checks failed. 37: ##[error]Process completed with exit code 1. 38: Cleaning up orphan processes