Generic Questions Framework (Preseason, H2H, and Future Variants)

[PhilipWoulfe]

Epic: Generic Questions Framework (Preseason, H2H, and Future Variants)

Summary

Create a reusable question domain and processing framework so preseason questions, head-to-head questions, and future migration-specific question types can be ingested, scored, reconciled, and reviewed using one consistent model.

Why This Epic

Current migration flow handles position selections but does not provide first-class support for preseason or H2H questions.

Without a generic framework:

• Each new question type requires custom pipeline logic.
• Admin review experiences become fragmented.
• Future migration adapters will duplicate domain and scoring behavior.

Goals

• Introduce a canonical question model that supports multiple question categories.
• Support ingestion, scoring, and reconciliation for preseason and H2H as first implementations.
• Keep question framework extensible for future migration variants.
• Preserve full traceability from source cell/row to persisted answer and calculated score.

Non-Goals

• Implementing all future question variants in this phase.
• Replacing race position scoring logic.
• Redesigning non-admin user-facing gameplay UX.

Target Architecture

• Question template model scoped by competition and season.
• Participant answer model linked to run, template, participant, and source provenance.
• Actual answer model and scoring strategy model by question category.
• Reconciliation model preserving imported score, calculated score, delta, and reason.
• Admin/API views built from the same generic query contract.

Data Model Direction

Proposed logical entities:

• QuestionTemplates
  • QuestionId, CompetitionId, Season, QuestionCategory, Prompt, OptionsJson, Status
• QuestionAnswers
  • RunId, QuestionId, ParticipantId, ImportedAnswer, NormalizedAnswer, SourceRow, SourceColumn
• QuestionActuals
  • RunId, QuestionId, ActualAnswer, ActualSourceRow, ActualSourceColumn
• QuestionScores
  • RunId, QuestionId, ParticipantId, ImportedPoints, CalculatedPoints, DeltaPoints, ReasonCode

User Stories

Story 1: Define canonical question domain model and taxonomy

As an engineer, I want one question model with category taxonomy so preseason and H2H can be represented without special-case tables.

Story 2: Add question template persistence with competition-season scope

As an operator, I want templates scoped to competition and season so question definitions do not bleed across contexts.

Story 3: Add participant answer persistence with source provenance

As a reviewer, I want persisted source row and column references so answer lineage is auditable.

Story 4: Add actual-answer persistence and normalization pipeline

As a maintainer, I want actual-answer handling standardized so scoring can be deterministic.

Story 5: Implement generic question scoring engine with pluggable strategies

As a product owner, I want category-based scoring strategies so preseason and H2H can share framework-level orchestration.

Story 6: Add preseason migration adapter on top of generic framework

As an operator, I want preseason rows mapped through the generic framework so migration does not require a one-off preseason-only path.

Story 7: Add H2H migration adapter on top of generic framework

As an operator, I want H2H rows mapped through the same framework so logic parity and supportability improve.

Story 8: Add admin/API question reconciliation views

As an admin, I want filtered question diffs and summaries so I can review imported versus calculated values across categories.

Story 9: Add extension test harness for future question category onboarding

As a developer, I want a test harness proving new categories can be added with minimal changes.

Delivery Plan

1. Canonical question schema and contracts
2. Ingestion and normalization pipeline
3. Scoring strategy abstraction
4. Preseason and H2H adapters
5. API and admin review surfaces
6. Extension and regression test coverage

Risks and Mitigations

• Risk: Over-generalization blocks delivery.

• Mitigation: Start with preseason and H2H only while validating extension seams.

• Risk: Source format drift by competition.

• Mitigation: Keep adapter boundaries strict and mapped to shared domain contracts.

Definition of Done

• Preseason and H2H question flows are persisted and reconciled through the same domain model.
• Imported and calculated question scores are both preserved with reasoned deltas.
• Admin/API can query question diffs with deterministic filtering and ordering.
• Tests demonstrate extension to a new mock question category without schema redesign.