Goal engine V1: depth scope, whitelist mapping, versioning, and confidence gate

DEC-0072 - Goal engine V1: depth scope, whitelist mapping, versioning, and confidence gate

Context

DEC-0071 locked program/form-aware goals. To make this usable in real product operation, the system still needs precise scope depth, conversion safety, version behavior, and display confidence guardrails.

Decision

Goal scope depth:

• lock depth at program + assessment_form + skill.
• each goal record carries:
  • goal_program_id,
  • goal_assessment_form,
  • goal_skill_id,
  • goal_scale_profile_id,
  • goal_target_value.

Scale mapping policy:

• comparison mode normalized is allowed only via explicit approved mapping table.
• no generic auto-convert-to-percent fallback across unrelated scales.

Primary/secondary goals:

• one active primary goal is required when user has at least one goal.
• one optional secondary goal is allowed.
• default product emphasis (Home summary and recommendation priority) follows primary goal.

Goal versioning:

• every goal update creates new immutable goal_version_id.
• attempt/result stores goal_version_id_at_submission.
• historical comparison reads version-at-submission to avoid retroactive distortion.

Confidence gate for numeric goal-gap:

• show numeric goal-gap only when:
  • comparison is direct | normalized, and
  • comparable attempts in latest 30 active days >= 3.
• otherwise hide numeric gap and keep trend/progress-only interpretation.

Fallback recommendation when incompatible/low-confidence:

• if comparison is not_comparable or sample gate fails:
  • prioritize recommendations in same assessment_form,
  • prefer same skill first when inventory allows.

Decision Value

• Prevents misleading goal-gap metrics.
• Keeps UX simple: users still get clear guidance even when exact comparison is unavailable.
• Scales cleanly with new programs/forms through profile + mapping configuration.

Rationale

The best experience here is trustworthy guidance, not forced numeric precision. A confidence gate and whitelist mapping protect trust while still preserving momentum through trend-based feedback and aligned recommendations.

Implications

• Product/UX impact:
  • goal setup gets clearer structure without forcing complexity in UI copy.
  • users see consistent behavior when switching goal setups.
• Data/logic impact:
  • metrics and result pipelines need version-aware and profile-aware fields.
• Operational impact:
  • content/academic teams can add mappings deliberately instead of inheriting risky auto-conversions.

Alternatives considered

• Option A: auto-convert all scale types to percent.
• Option B: support many concurrent equal-priority goals.

Open follow-ups

• No open blocker for baseline lock.