From 12ec26be5f9194b7f319da212444140c57810186 Mon Sep 17 00:00:00 2001 From: dwindown Date: Sat, 4 Apr 2026 17:13:10 +0700 Subject: [PATCH] Add AI parent-variant workflow note --- AI_PARENT_VARIANT_WORKFLOW.md | 233 ++++++++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 AI_PARENT_VARIANT_WORKFLOW.md diff --git a/AI_PARENT_VARIANT_WORKFLOW.md b/AI_PARENT_VARIANT_WORKFLOW.md new file mode 100644 index 0000000..886fc54 --- /dev/null +++ b/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