# AI Parent-Variant Workflow

## Goal

Keep one imported WordPress question as the canonical parent, then manage AI-generated questions as traceable children derived from that parent.

This keeps the workflow:

- consistent for content admins
- safe for reporting and history
- compatible with future direct sync from WordPress
- easy for assessment admins to review, regenerate, and retire variants

## Core Model

There are 3 logical layers:

1. Source Question
- imported from WordPress / Sejoli
- canonical business identity
- the real parent

2. Source Question Version
- each import represents a version of the source content
- needed so edits do not silently invalidate history

3. Generated Variant
- AI-generated child based on one specific source question version
- can be easier, same-level, or harder
- there may be many variants per parent and per difficulty

## Why Versioning Matters

Without versioning, any parent edit creates ambiguity:

- which parent content generated this child?
- is the child still valid after the source changes?
- should old children be deleted, archived, or reviewed?

Versioning avoids destructive behavior and preserves lineage.

## Recommended Lifecycle

### Source Question Status

- `active`
- `updated`
- `removed_from_source`
- `archived`

### Generated Variant Status

- `draft`
- `active`
- `stale`
- `rejected`
- `archived`

## What Should Happen When Parent Changes

### If parent is edited upstream

Do not auto-delete generated variants.

Instead:

- create or recognize a newer source version
- mark existing variants as `stale`
- show that their source changed after generation
- let admin decide whether to keep, archive, or regenerate

Reason:

- variants may already be used in sessions and reports
- minor source edits should not destroy downstream data
- destructive cascades create operational risk

### If parent is deleted upstream

Do not hard-delete generated variants automatically.

Instead:

- mark parent as `removed_from_source`
- mark variants as `source_removed` or `orphaned`
- block new delivery unless admin explicitly keeps them active

## Recommended Admin UX

Do not make snapshot tables the long-term center of the product.

The main working surface should be a question detail workspace:

1. Source
- stem
- options
- answer
- category
- tryout
- last imported time
- source status

2. Versions
- import history
- source diffs
- current active version

3. Generated Variants
- difficulty
- model
- status
- created time
- derived from source version X
- actions: review, approve, archive, regenerate

4. Actions
- generate easier
- generate same-level variant
- generate harder
- bulk generate
- archive stale variants

5. Usage
- impressions
- unique users shown
- family frequency
- repeat exposure signals

## Recommended Routing Direction

Current routes are implementation-driven.

Long-term, the product should center around a stable question detail route such as:

- `/admin/questions/{source_question_id}`

or

- `/admin/basis-items/{id}`

Inside that page, generated variants should be shown under the parent question.

## Operational Data Boundaries

### Source of truth

WordPress / Sejoli remains the source of truth for imported parent questions.

### Backend-native ownership

The IRT app owns:

- imported source snapshots
- source version history
- promoted basis items
- AI-generated variants
- session and scoring data
- reporting and freshness metrics

## Recommended Rules

1. Imported parent questions are canonical.
2. AI-generated questions are children of one parent version.
3. Parent edits do not hard-delete children automatically.
4. Variants should become `stale` when source content changes materially.
5. Admin should access variants from the parent question page.
6. Multiple variants per difficulty must be allowed.
7. Generation metadata should be retained for reproducibility.

## Minimal Data Relationships

Conceptually:

- `SourceQuestion`
- `SourceQuestionVersion`
- `BasisItem`
- `GeneratedVariant`
- `GenerationRun`

Key lineage:

- each generated variant points to one parent basis item
- each generated variant points to one source question version
- each generation run stores prompt, model, and settings

## Practical Workflow by Role

### Content Admin in WordPress

- creates or edits question
- exports JSON now
- later syncs by API

### Assessment Admin in IRT App

- imports snapshot
- reviews changed or new source questions
- promotes selected parent questions into basis items
- generates AI variants
- approves, archives, or regenerates variants

### Operations / Quality Admin

- monitors stale variants
- monitors family frequency
- decides when a parent question needs more diversity

## Non-Goals

Avoid:

- auto-deleting children when parent changes
- mixing parent questions and variants in one flat undifferentiated table
- forcing snapshot pages to remain the long-term UX
- assuming one variant per difficulty is enough forever

## Product Direction

The clean direction is:

- canonical imported parent
- versioned source content
- AI children with lineage and lifecycle
- parent-centered admin UX
- offline/admin-side generation, not student-time generation

This is the most consistent approach for:

- auditability
- low-friction admin work
- safe iteration
- future API sync
- long-term adaptive content expansion