ai-shifu-course-creator

Convert raw course material into optimized, runnable MarkdownFlow teaching scripts and deploy them as live courses through a five-phase pipeline covering segmentation, orchestration, generation, optimization, and deployment.

# Course Creator

Convert raw course material into runnable, optimized MarkdownFlow lesson scripts and deploy them as live AI-Shifu courses.

## Execution Modes

- Standard mode (default): Input quality is sufficient; run requested phases in full.
- Fallback mode: Input is incomplete or low quality; produce coarse outputs, mark uncertainty, and provide focused rerun hints.

## Language Resolution Policy

See `references/language-resolution.md` for the full policy.

Resolve target language with this strict priority:
1. `explicit_output_language_request`
2. `target_language_parameter`
3. `session_language_preference`
4. `prompt_language_detection`
5. `source_material_dominant_language`
6. `default_fallback_language` (`en-US`)

## Authoring Control Inputs

Use these optional controls across all phases:

- `course_profile` (json): audience level, prerequisite level, lesson duration target, lesson count target, and assessment mode.
- `delivery_constraints` (json): interaction density, platform limits, must-cover topics, avoid topics, and non-negotiable source fragments.

See `references/input-contract.md` for recommended object shapes.

## Output Boundary

- Final outputs are learner-facing teaching content only.
- Authoring rules, pipeline notes, and process instructions stay in skill docs and references, not in lesson outputs.
- Internal design notes may appear only in HTML comments when needed.

## Pipeline Overview

```
Phase 1: Segmentation → Phase 2: Orchestration → Phase 3: Generation → Phase 4: Optimization → Phase 5: Deployment
```

## Usage Paths

### Path A: End-to-End

Run all five phases from raw material to a live deployed course.

1. Phase 1: Segment raw material into semantic units.
2. Phase 2: Orchestrate lesson boundaries and generate scripts.
3. Phase 3: Generate per-lesson MarkdownFlow scripts (called internally by Phase 2).
4. Phase 4: Audit and optimize final scripts.
5. Phase 5: Build, import, and publish to the AI-Shifu platform.

### Path B: Author Only

Run Phase 1–4 to produce optimized MDF scripts without deploying. Sub-paths:
- **Segment only**: Phase 1 alone for structured segments and manual review.
- **Generate only**: Phase 3 alone on pre-existing segments to produce lesson scripts.
- **Optimize only**: Phase 4 alone to audit and improve existing MarkdownFlow scripts.

### Path C: Deploy Only

Run Phase 5 alone to deploy pre-existing MDF files to the AI-Shifu platform.

### Path D: Manage Existing

Use Phase 5 management commands (list, show, update, rename, reorder, delete, publish, archive) on courses already on the platform.

---

## Phase 1: Segmentation

Turn messy course source material into a reliable intermediate structure for downstream lesson generation.

### Workflow

1. Remove filler language and duplicated phrasing without changing meaning.
2. Mark immutable blocks: code, images, and tables.
3. Segment by semantic continuity instead of headings alone.
4. Propose lesson boundaries with one core question per lesson.
5. Return source-linked structured segments.

### Segment Schema

Each segment includes:
- `segment_id`
- `segment_type` (`concept`, `example`, `code`, `image`, `exercise`, `transition`)
- `core_point`
- `preserve_block` (`yes` or `no`)
- `source_span`

### Transfer Signals

Capture these fields for downstream teaching quality:
- `learner_hook`: statements that can trigger learner reflection.
- `evidence_type`: one of history, phenomenon, data, mechanism, or conclusion.
- `visual_cue`: fragments suited for SVG/HTML visual support.
- `concept_conflict`: candidate idea conflicts for cognitive contrast.
- `boundary_cue`: clues for validity boundaries.
- `action_cue`: clues that can become immediate or staged actions.
- `density_cue`: high-information chunks that should not be diluted.
- `quote_cue`: original wording worth preserving.
- `visual_text_pair_cue`: clues for "visual first, explanation second" blocks.
- `interaction_intent_cue`: intent labels such as diagnose, branch, calibrate, compare.
- `compare_cue`: candidate prompts for before/after comparison.

### Phase 1 Outputs

- Ordered segment list.
- Lesson boundary candidates.
- One core question per lesson.
- Preservation block index.
- Full transfer-signal package.

See `references/segmentation-rules.md`.

### Phase 1 Validation

- Segment output covers all valid source spans in traceable order.
- Code/image/table blocks keep original placement and format.
- Every lesson candidate resolves to one core question.
- Transfer-signal fields are complete and usable downstream.
- Cleanup does not alter key facts or terminology.

---

## Phase 2: Orchestration

Convert raw course material into runnable lesson-level MarkdownFlow scripts by coordinating segmentation and generation.

### Workflow

1. Normalize source ordering and merge input material.
2. Run Phase 1 for cleanup and semantic segmentation.
3. Generate lesson-cut candidates with one core question each.
4. Run Phase 3 for lesson-level MarkdownFlow scripts.
5. Build course index and global variable table.
6. Recompute only failed lessons through strict gating.

### Mandatory Gates

All gates must pass:
- Code blocks are preserved character-by-character.
- Image links and relative placement are preserved.
- Each lesson resolves one core question.
- Each lesson contains at least one valid MarkdownFlow interaction, max five interactions total.
- Each lesson includes a minimum teaching loop: setup, explanation, interaction, close.
- Lesson language is learner-facing, not pipeline narration.
- Each lesson includes at least one deepening interaction (calibration, boundary check, or counterintuitive prompt).
- Action tasks are either immediately executable or explicitly linked to later modules.
- Variable naming is consistent and traceable.
- No unresolved placeholder variables in learner-facing text.
- Do not wrap full lessons in deterministic blocks (`=== ===` or `!=== !===`).
- Deterministic blocks are reserved for legally or operationally fixed statements only.
- If an image must remain unchanged, use single-line deterministic syntax per image.
- Use `---` between instructional blocks to keep pacing readable.
- Every variable collection step must produce immediate feedback and downstream effect.
- Core knowledge points require visual + textual explanation together.
- Consecutive variable collection cannot exceed three variables.
- Do not recollect the same variable unless explicitly marked as staged comparison.
- Never reference uncollected variables.
- Interaction prompts must be concrete and directly answerable.
- Avoid repetitive interaction semantics across lessons unless comparison intent is explicit.
- `*_viewpoint_check` interactions must branch by option and drive different next steps.
- Every interaction variable must create visible downstream impact.

### Rerun Rules

- Recompute only impacted lessons.
- Recompute dependency-linked lessons when shared variables change.
- Recompute full course only when global source order changes.

### Failure Handling

When source quality is weak:
- Deliver coarse lesson drafts first.
- Mark uncertain spans explicitly.
- Continue with best-effort generation instead of stopping.

### Phase 2 Outputs

- Lesson MarkdownFlow scripts (one file per lesson).
- Course index (lesson id, title, core question, source mapping).
- Global variable table (definition, use, cross-lesson references).

See `references/output-contract.md` and `references/preservation-rules.md`.

### Phase 2 Validation

- Lesson scripts, course index, and variable table are all present.
- Code/image preservation is exact and position-safe.
- One-core-question and interaction cap rules are satisfied per lesson.
- No unresolved variables or no-op interactions remain.
- Fallback outputs include explicit uncertainty markers and rerun hints.

---

## Phase 3: Generation

Generate runnable MarkdownFlow scripts for each lesson.

### Teaching Pattern Baseline

Use these defaults unless lesson c