A score needs a methodology readers can inspect

If your software gives an organisation a capability score, the person reading it needs to see what was measured and which version of the rules produced it. Someone sees 68 out of 100 on a dashboard and assumes it's a stable measurement, when really it depends on how the questions were worded, what happened to missing answers, how the categories were weighted and where the thresholds were set. If all of that lives only in the code, nobody can explain the number and it's easy to misuse.

I'd start the methodology note with the decision the score is meant to support. A score that kicks off an internal planning workshop can get away with broad categories. One that's tied to funding, access or performance reviews needs a lot more checking. Then say what it can't tell you, in plain words and close to the number (a link buried in the footer won't fix what the main screen is encouraging people to believe). A self-reported score can't confirm controls actually work unless you collected evidence that they do, and if one person answered everything, the result only reflects what that person knew.

You should be able to trace an answer all the way to the displayed result. For each category score, I write down:

• which questions or evidence are included
• how each response converts to points
• any weight or cap
• what the denominator does when an item isn't applicable
• where rounding happens before display

That list catches boring bugs. A missing answer can turn into a zero in one part of the system and quietly drop out of the denominator somewhere else. Rounding each question before adding them up gives a different result from rounding the final score. I'd also keep the labels ("developing" and so on), thresholds and recommendation rules in the same versioned definition as the calculation, so they can't drift apart. If a language model writes the narrative, give it the calculated result and the approved evidence and don't let it decide the score. A reviewer should be able to reproduce the number without reading the prose.

The method will change over time as questions get clarified and weights or thresholds move, so each completed assessment should keep the rule version, the answers, the evidence, the component scores and what was shown, and the version identifier should be visible somewhere in the report. A date isn't enough, since two changes can land on the same day. When the rules change, decide whether old results stay fixed, get recalculated and marked, or show both. Silent recalculation is the one I'd avoid, because the score moves when the organisation hasn't given you anything new. And write change notes that someone can check, like "Questions 4 and 5 now share a category cap, reducing double counting when both describe the same control", rather than "updated scoring logic".

Before you release a capability score, take one completed assessment and follow it from the source answer through to the recommendation, using only what the product actually keeps. Wherever you need someone to explain a step from memory, that's a part of the method a reader can't inspect, and it's a gap to fix before the score goes out. If the versioned definition and the stored record are enough to make that trace, the person looking at 68 out of 100 has something they can check the number against.