Add AI parent-variant workflow note

AI_PARENT_VARIANT_WORKFLOW.md

@@ -0,0 +1,233 @@
+# 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