github-analytics-scoring

name

github-analytics-scoring

description

Scoring formulas and analytical frameworks for GitHub workflow agents. Covers repository health scoring (0-100, A-F grades), priority scoring for issues/PRs/discussions, confidence levels for analytics findings, delta tracking (Fixed/New/Persistent/Regressed), velocity metrics, contributor metrics, bottleneck detection, and trend classification. Use when computing scores, tracking remediation progress, building prioritized dashboards, or detecting workflow bottlenecks.

GitHub Analytics Scoring

Repository Health Score

Health Score = 100 - (sum of weighted penalties)

Penalties — CI & Reliability:
  Failing workflow, high confidence:         -10 points
  Flaky test (3+ failures/week):             - 5 points
  No CI configured:                          - 8 points

Penalties — Issues & PRs:
  Critical unresolved bug (P0):             -10 points
  Security alert (critical severity):       -10 points
  Security alert (high severity):           - 5 points
  PR open >14 days (stale):                 - 3 points each (max -9)
  Issue @mentioned, no response >7 days:    - 5 points each (max -10)
  >10 open issues with no labels/triage:    - 3 points

Penalties — Community Health:
  No CONTRIBUTING.md:                        - 5 points
  No CODE_OF_CONDUCT.md:                     - 3 points
  No branch protection on main:              - 5 points
  0 open "good first issue" labels:          - 2 points

Floor: 0 (minimum score)

Score Grades

Score	Grade	Meaning
90–100	A	Excellent — healthy repo, minimal issues
75–89	B	Good — minor issues, well-managed
50–74	C	Needs attention — multiple signals requiring action
25–49	D	Poor — significant problems impacting velocity
0–24	F	Critical — major issues blocking team progress

---

Priority Scoring for Issues

Internally score each issue to determine sort order in dashboards and reports:

Signal	Points
User @mentioned and hasn't responded	+5
P0, P1, critical, urgent, blocker label	+3
Tied to upcoming release milestone	+3
New comments from others since user's last activity	+2
High community interest (5+ positive reactions)	+2
bug label	+1
Assigned to user	+1
Active related discussion thread	+1
wontfix, duplicate, question label	-1
No activity >14 days	-2

Priority Scoring for Pull Requests

Signal	Points
Review requested, user hasn't reviewed	+5
PR has "changes requested" — author needs to update	+4
PR is approved and ready to merge	+3
Targets a release branch with upcoming deadline	+3
CI failed on this PR	+2
Merge conflicts present	+2
High community interest (5+ positive reactions)	+2
New comments on the PR	+1
Active discussion thread linked to this PR	+1
Draft PR	-1
No activity >7 days	-2

Priority Scoring for Discussions

Signal	Points
User was @mentioned	+3
High activity (10+ comments in 24h)	+2
Linked to an issue/PR the user owns	+1
No activity >7 days	-1

---

Confidence Levels for Analytics Findings

Apply confidence levels to all bottleneck findings, health score deductions, and anomaly detections. Every finding in a report MUST include its confidence level.

Level	When to Use	Impact on Report
High	Multiple corroborating signals, definitively observed (e.g., CI has failed 5 times this week, confirmed by logs)	Report as fact; recommend remediation
Medium	Found by one source, likely issue (e.g., PR open 14 days but author may be on leave)	Report as finding; suggest investigation
Low	Possible pattern, needs human review (e.g., velocity seems low but may be seasonal)	Flag as observation; don't deduct from score

Confidence Tag Format in Reports

| Finding | Severity | Confidence | Recommendation |
|---------|----------|-----------|----------------|
| 3 PRs stale >14 days | High | **High** | Assign reviewers or close |
| Velocity 40% below 4-week avg | Medium | **Medium** | Verify — may be holiday period |
| Issue activity spike on Fridays | Low | **Low** | Monitor for 2 weeks before acting |

---

Delta Tracking

When re-running an analysis against a previous report, classify every finding by change status:

Status	Definition
Fixed	Was in previous report; no longer present
New	Not in previous report; appears now
Persistent	Remains from previous report, unchanged
Regressed	Was previously fixed but has returned

Delta Report Section Format

## Changes Since Last Report ({previous date})

| Change | Finding | Details |
|--------|---------|---------|
| ✅ Fixed | 3 stale PRs resolved | Team cleared the backlog |
| 🆕 New | CI failing on main | Build broke in last 24h |
| ⚠️ Persistent (#3) | Velocity 30% below baseline | Third consecutive week |
| 🔄 Regressed | Security alert reopened | lodash advisory re-filed |

**Progress:** {N} fixed, {M} new, {P} persistent, {Q} regressed
**Score change:** {current_score} ({+/-N} from {previous_score})

Escalation Rule

If a finding is Persistent for 3+ consecutive reports, escalate:

⚠️ Escalation: [{Finding}] has been present for {N} consecutive reports. Consider a team discussion or explicit ownership assignment to resolve this.

---

Velocity Metrics

Metric	Formula	Healthy	Warning	Critical
PR merge rate	PRs merged / week	>3/week	1–3/week	<1/week
Issue close rate	Issues closed / week	>5/week	2–5/week	<2/week
Review turnaround	Avg hours PR open before first review	<24h	24–72h	>72h
Issue response time	Avg hours until first team response	<8h	8–48h	>48h
Stale PR ratio	PRs open >14 days / total open PRs	<10%	10–30%	>30%
CI reliability	Passing runs / total runs (7-day)	>95%	80–95%	<80%

---

Contributor Metrics

Metric	Formula	Notes
PR commit ratio	Commits / PRs merged	High ratio = large PRs, consider splitting
Review coverage	PRs reviewed by others / total PRs merged	Low = single-contributor bottleneck
First-time contributor rate	New contributors / total active contributors	Healthy community growth signal
Contributor retention	Active last month AND active this month / active last month	Engagement health
Bus factor	Min contributors whose departure halts 50%+ of commits	<3 is high risk

---

Bottleneck Categories

Category	Signals	Example Finding
Review bottleneck	High PR open time, review-requested PRs >3 days	"4 PRs waiting for review >3 days — assign or redistribute"
CI bottleneck	Frequent failures, long runtimes	"Test suite 45min avg — 2× slower than 4-week average"
Stale work	Issues/PRs with no activity >14 days	"7 issues open >30 days with no recent comments"
Knowledge concentration	80%+ commits from one contributor	"3 of 4 core modules have only one contributor — bus factor 1"
Response lag	>24h average first response to new issues	"Average first response: 38h — community may feel unsupported"
Security debt	Open Dependabot alerts unresolved >7 days	"2 critical alerts open for 12 days"
Release congestion	>10 merged PRs unreleased	"11 merged PRs awaiting release — coordinate cut date"

---

Trend Classification

Trend	Definition
Improving	Score increased 5+ points vs previous report
Stable	Score within 5 points of previous report
Declining	Score decreased 5+ points vs previous report
Recovering	Score increased after 2+ consecutive Declining reports
New	No previous report to compare

---

Scorecard Output Format

Single Repo

## Repository Health Score

| Metric | Value |
|--------|-------|
| Repo | [owner/repo](url) |
| Score | {0-100} |
| Grade | {A-F} |
| Trend | {Improving / Stable / Declining} |
| Open Security Alerts | {count} |
| Stale PRs (>14 days) | {count} |
| CI Reliability (7-day) | {%} |
| Unanswered @mentions | {count} |

Multi-Repo Scorecard

## Repository Health Scorecard

| Repo | Score | Grade | Trend | Critical Issues | Notes |
|------|-------|-------|-------|-----------------|-------|
| owner/repo-a | 88 | B | Improving | 0 | |
| owner/repo-b | 54 | C | Declining | 1 | Security alert unresolved |
| owner/repo-c | 22 | F | Stable | 3 | Review bottleneck + stale PRs |
| **Average** | **54.7** | **C** | — | **4** | |

---

Sprint & Iteration Metrics

When project boards are configured, track sprint metrics:

Metric	Formula
Sprint completion rate	Done items / total sprint items × 100
Carryover rate	Items moved to next sprint / planned items
Cycle time	Average days from "In Progress" to "Done"
Throughput	Items completed per sprint
Blocked rate	Items in "Blocked" state / total in-progress