Skip to content

Commit b4c658d

Browse files
jdiegosierraclaude
andcommitted
docs: add section explaining why reports are better than numeric scores
- Add "Why Reports Instead of Scores?" section to README - Explain limitations of numeric scoring systems (lack of context, hidden bias) - Highlight transparency, fairness, and configurability benefits - Emphasize information over judgment approach - Compare with score-based tools like SlopScore Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent 21caa3c commit b4c658d

1 file changed

Lines changed: 42 additions & 0 deletions

File tree

README.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,48 @@ Example report:
5858
- Consider reviewing code from other contributors to build reputation
5959
```
6060

61+
## Why Reports Instead of Scores?
62+
63+
Unlike tools that assign a single numeric score (e.g., "45/100"), **Contributor Report** provides detailed, transparent
64+
reports. Here's why:
65+
66+
### Numeric Scores Hide Important Context
67+
68+
A score like "45/100 - Review Carefully" doesn't tell you:
69+
70+
- **Which specific metrics failed** or why
71+
- **What to review** or what concerns exist
72+
- **How the contributor can improve**
73+
- **Why the threshold was set at that number**
74+
75+
### Reports Provide Transparency & Fairness
76+
77+
Open source values transparency. Contributors deserve to see:
78+
79+
- Exactly what metrics were evaluated
80+
- The actual values vs required thresholds
81+
- Clear, actionable recommendations
82+
- Fair handling of new accounts and limited data
83+
84+
### Every Project is Different
85+
86+
A one-size-fits-all score assumes all projects value the same things. But:
87+
88+
- A documentation project may not care about code reviews
89+
- A security-critical project might require high review activity
90+
- An experimental project might welcome new contributors with limited history
91+
92+
**Detailed reports let you configure thresholds** that match your project's needs and make informed decisions based on
93+
your own standards.
94+
95+
### Information, Not Judgment
96+
97+
This action doesn't claim to know if someone is "good" or "bad". Instead, it provides **objective data and clear
98+
metrics** so maintainers can make informed decisions. It's the difference between:
99+
100+
- ❌ "This PR author scores 45/100" (black-box judgment)
101+
- ✅ "This PR author has these metrics, here's what they mean, you decide" (transparent information)
102+
61103
### Metrics
62104

63105
| Metric | Description | Default Threshold |

0 commit comments

Comments
 (0)