Keep the scoring engine explicit

Keep the scoring engine in a small, testable service or module. It validates inputs, applies rules in a documented order and emits a structured result. It should not depend on conversation history, the current prompt or the model selected for the interview.

A typical calculation request includes the methodology version, assessment run identifier and a map of confirmed answer values. The response can include:

• validation errors for missing or malformed inputs;
• each rule identifier and whether it matched;
• intermediate dimension values where the method uses them;
• the final level or profile;
• reason codes linked to explanation text;
• warnings for incomplete or conflicting evidence;
• a hash or stable identifier for the calculation inputs.

Use decimal or integer arithmetic where the methodology requires exact thresholds. Define rounding in one place and test values on either side of every boundary. Avoid letting interface formatting decide the value later consumed by another rule.

Handle missing data deliberately. Zero, false, unknown and not applicable are different states. Treating a missing answer as zero can punish incomplete evidence without saying so. Ignoring it can inflate a percentage by shrinking the denominator. The methodology owner must choose the behaviour, and the engine should expose it in the result.

Keep explanation generation tied to reason codes. A model may turn structured reasons into readable prose, but the report should retain the underlying codes and facts. Check generated prose against those facts before release, especially where the wording could imply certification, causation or comparison not present in the rules.

Make recalculation idempotent. Running the same version against the same confirmed answers should produce the same result identifier or an equivalent result with a recorded duplicate relationship. This prevents a retry from creating several apparently independent scores.