# [Enhancement] Make Repository Health Scores Interactive and Explainable

Start in the Repository Explorer and trace the existing health score calculation and data flow, including the related work in issue #222. Confirm which component scores and metrics are available before defining the side panel views. Done means the primary Breakdown interaction is aligned with the existing score, with supporting views and tests scoped to the available data.

Feature and its Use Cases

Overview

I propose improving the Repository Explorer's health score experience by allowing users to click on a repository's health score and view detailed information about it.

Currently, an overall score such as 71 provides a quick summary, but users may not understand what contributes to that score or which areas need attention.

The goal is to make the health score more transparent, understandable, and actionable through an interactive details panel.

Proposed UI

When a user clicks on a repository's health score, a side panel opens with three views:

• Breakdown — Understand why the repository has its score.
• Recommendations — Identify potential areas for improvement.
• Raw Metrics — Explore the data behind the score.

---

1. Breakdown View (Primary Focus)

The Breakdown view is the main focus of this proposal.

Instead of displaying only the overall score, this view would explain the individual factors contributing to the repository's health score.

Proposed Information

• Individual health categories.
• Component scores.
• Contribution or weight, if supported by the scoring system.
• Visual indicators.
• Short explanations of each category.

Example Categories

• Activity Health
• Issue Health
• Pull Request Health
• Contributor Health
• Maintenance

The categories should be based on the actual scoring system used by the project.

UI Reference

The proposed design shows how users can understand the factors contributing to the overall repository health score.

Why This Matters

A user should be able to answer:

Why does this repository have a health score of 71?

The Breakdown view should provide that explanation without requiring users to inspect multiple separate sections.

---

2. Recommendations View

The Recommendations view would provide actionable suggestions based on the repository's available health metrics.

Example Recommendations

• Review stale issues.
• Address long-running pull requests.
• Improve repository documentation.
• Review maintenance-related gaps.

Recommendations should be based on actual repository data and clearly defined rules.

UI Reference

The proposed design shows how improvement suggestions could be presented in a dedicated view.

---

3. Raw Metrics View

The Raw Metrics view would show the underlying repository metrics used in the health score calculation.

Example Metrics

Activity

• Commit activity.
• Recent development activity.

Issues

• Open issues.
• Closed issues.
• Stale issues.

Pull Requests

• Open pull requests.
• Merged pull requests.
• Long-running pull requests.

Contributors

• Contributor statistics.
• Active contributors, if available.

Maintenance

• Repository documentation checks.
• License availability, if used by the scoring system.

The final metrics should be based on the data actually used by the existing scoring implementation.

UI Reference

The proposed design shows how users could inspect the data behind the health score.

---

4. User Interaction Flow

The proposed interaction would work as follows:

1. User opens the Repository Explorer.
2. User clicks on a repository's health score.
3. A health details side panel opens.
4. The Breakdown view is displayed by default.
5. User can switch between Breakdown, Recommendations, and Raw Metrics.
6. User can understand the score and explore its supporting information.

Complete UI Reference

This screenshot demonstrates the proposed health score interaction and details panel.

---

5. Technical Considerations

This proposal focuses on improving how users explore and understand health score information. It does not propose creating a separate scoring system.

Before implementation, the existing health score calculation and data flow should be investigated.

Proposed Technical Approach

• Reuse the existing health score calculation and repository data.
• Identify whether component-level scores and weights are already available.
• Avoid duplicating scoring logic inside the UI.
• Ensure the displayed Breakdown is consistent with the actual overall score.
• Handle missing metrics, loading states, and errors.
• Add appropriate tests for the new functionality.

If the current scoring implementation only returns an overall score, it may need to expose additional component-level information for the Breakdown view.

The implementation should follow the existing project architecture and design system.

---

6. Scope and Priority

Primary Focus: Breakdown

The initial focus would be the interactive Breakdown view:

• Clickable repository health score.
• Health details side panel.
• Component-level score information.
• Explanation of factors contributing to the score.

Supporting Views

• Recommendations.
• Raw Metrics.

These supporting views can be implemented based on available data, project requirements, and maintainer feedback.

---

7. Relationship to Existing Health Scorecard Work

I understand that Issue #222 proposes a Repository Health & Risk Scorecard.

This proposal focuses on the interactive user experience for exploring an individual repository's health score within the Repository Explorer.

The intention is to complement the existing scoring work by providing a clear way for users to understand the score and inspect its supporting information.

The proposed UI and implementation scope can be adjusted to align with the existing health score architecture.

---

8. Expected Outcome

The proposed feature would help users move from:

Overall Score → Breakdown → Supporting Metrics → Potential Improvements

This would make repository health scores easier to understand and provide users with more context about the factors affecting repository health.

---

Questions for Maintainers

• Does the existing health score implementation expose the data required for a detailed Breakdown view?
• Can this interaction be integrated into the current Repository Explorer?
• Which component-level scores and metrics are currently available?
• Would this be suitable as a complementary enhancement to the existing health scorecard work?

Additional Context

No response

Code of Conduct

• I have joined the Discord server and will post updates there
• I have searched existing issues to avoid duplicates