234 lines
5.2 KiB
Markdown
234 lines
5.2 KiB
Markdown
# 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
|