Why Your Scoring System Needs Built-In Explanations, Not Separate Logic

A software developer describes a recurring problem where a lead-scoring system produced numbers that could not be readily explained in review meetings, undermining confidence in the output. The root cause was a common architectural pattern: the scoring function and the explanation function were written separately, each hardcoding the same thresholds independently. When a spend threshold was updated in the scoring function but not in the explanation builder, the system began producing scores and justifications that directly contradicted each other. The proposed fix is straightforward — emit the human-readable reason for each points decision at the exact same line of code where the points are awarded, so both must be updated together. This approach ensures that any change to scoring logic automatically surfaces in the explanation, eliminating silent drift between numbers and their stated rationale.