Add frontend conventions to scorecard AGENTS.md for empty states and i18n namespaces
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 78/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- typescript
- Domain
- documentation, frontend
Research direction
Start with workspaces/scorecard/AGENTS.md and inspect ref.ts for the canonical translation namespace map. Add the requested frontend conventions for i18n namespaces, empty/error rendering, AggregatedMetricCard dispatch, and threshold responsibilities; done means the guidance is documented and can be referenced during the next three relevant scorecard PRs.
Written by the indexing model from the issue text.
Description
What happened
On PR #4395, the review agent ran 6 times (run 1, run 2, run 3, run 4, run 5, run 6) and approved every time with only low-severity code-pattern findings. Two human reviewers then caught substantive issues the agent missed:
- Eswaraiahsapram (review) identified that empty/error scalar aggregates — where all entities fail calculation (
total === 0 && calculationErrorCount > 0) — rendered as a green 0 value instead of defaulting to grey. This is a functional correctness bug in the UI state handling. - imykhno (comment) identified that scalar type labels (Min, Max, Sum, Count, Average) were placed under the
metric.i18n namespace instead ofaggregation., violating the workspace's implicit namespace convention for aggregation-specific terminology.
The current workspaces/scorecard/AGENTS.md is entirely backend-focused: it documents metric providers, threshold resolution, metric ID naming, and config schema. It has zero frontend guidance — no component conventions, no empty/error state patterns, and no i18n key naming conventions.
What could go better
The review agent had no documented frontend conventions to reference when reviewing UI component code. It focused on what it could infer from code patterns alone — type definition consistency, regex edge cases, JSX syntax. The two issues humans caught both required domain knowledge that exists implicitly in the team but is not captured in AGENTS.md:
- Empty/error state rendering: The convention that cards with no successful samples should render as grey (not success-green) is a UX principle the team enforces but hasn't documented.
- i18n key namespaces: The convention that aggregation-specific labels belong under
aggregation.*(notmetric.*) reflects a deliberate namespace structure in the translation files.
Confidence is high that documenting these conventions would help both the review agent and code agent (which uses Cursor in this workflow). The agent demonstrably reads and applies AGENTS.md guidance — its threshold-resolution review guidance already shows this. The gap is simply that frontend conventions are absent from the file.
Proposed change
Add a ## Frontend Component Conventions section to workspaces/scorecard/AGENTS.md covering:
-
i18n translation key namespaces: Document that translation keys are organized by domain —
metric.<id>for individual metric display names,aggregation.<type>for aggregation type labels (min, max, sum, count, average), and any other established prefixes. Referenceref.tsas the canonical namespace map. -
Empty and error state rendering: Document that when a scalar aggregation has no successful samples (
total === 0andcalculationErrorCount > 0), the card must render in a neutral/grey state — not apply threshold coloring that would imply a valid result. More generally, state the principle: do not render success/failure coloring when the underlying data is absent or entirely errored. -
AggregatedMetricCard dispatch pattern: Document that
AggregatedMetricCarduses result-shape-based discrimination (numericvaluefield vs.values[]array) rather than type-name matching to select the card variant. This was a deliberate architectural choice in this PR that the review agent noted but flagged as scope creep. -
Frontend/backend responsibility boundary for threshold evaluation: Note that threshold evaluation is the backend's responsibility. The frontend mirrors the logic only for coloring display purposes and should defer to backend-provided values when available (follow-up tracked in RHIDP-16510).
Validation criteria
On the next 3 scorecard workspace PRs that modify frontend components or translation files, the review agent should (a) reference the documented conventions when reviewing i18n key additions and (b) flag violations of the empty-state rendering pattern if present. If the review agent's findings on those PRs include at least one domain-convention-based observation (rather than only code-pattern findings), the improvement is validated.
Generated by retro agent from https://github.com/redhat-developer/rhdh-plugins/pull/4395
- Dominant language
- TypeScript
- Stars
- 48
- Forks
- 120
- Avg merge
- 2d 4h
- Merged PRs (30d)
- 333
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from redhat-developer/rhdh-plugins
-
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
redhat-developer/rhdh-plugins#4887 · 2 comments ·
-
feature fullsend ready-for-triage Review effort 1/5 triaged
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
redhat-developer/rhdh-plugins#4799 · 2 comments ·
-
Add Backstage entity provider design concepts to ai-integrations AGENTS.md for specification review Opendocumentation ready-for-triage ready-to-code Review effort 1/5 workspace/ai-integrations
Difficulty 1/5 Under an hour Newbie friendliness 88/100
redhat-developer/rhdh-plugins#4788 · 5 comments ·
-
documentation ready-for-triage ready-to-code Review effort 1/5 workspace/ai-integrations
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
redhat-developer/rhdh-plugins#4781 · 3 comments ·
-
documentation ready-for-triage ready-to-code Review effort 1/5 workspace/scorecard
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
redhat-developer/rhdh-plugins#4777 · 3 comments ·
All issues in redhat-developer/rhdh-plugins
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
Eynzof/Hermes-CN-Desktop#610 ·
-
bug clawsweeper:linked-pr-open clawsweeper:needs-live-repro clawsweeper:no-new-fix-pr impact:message-loss issue-rating: 🐚 platinum hermit P2 regression
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
calcite-components needs triage refactor
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Esri/calcite-design-system#15203 ·
-
Difficulty 1/5 Under an hour Newbie friendliness 78/100
fullcalendar/fullcalendar#8106 ·