AI Shifu Course Creator

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 content requires a justified variation:

1. Learner-facing language only.
2. Variable collection is distributed, not front-loaded.
3. Build evidence chain from observation to mechanism to conclusion.
4. Use visual-first explanation for abstract concepts, then textual interpretation.
5. Every collected variable must immediately affect downstream content.
6. Include at least one deepening interaction (calibration, boundary check, or misconception correction).
7. Include at least one reusable deliverable.
8. Action steps must be immediately executable or explicitly staged for downstream lessons.
9. Use carryover statements only if cross-lesson dependency is allowed.
10. Avoid exposing internal authoring terms in learner-facing text.
11. Keep interaction prompts concrete and answerable.
12. *_viewpoint_check prompts must branch with distinct feedback paths.
13. Repeated interaction patterns are allowed only when framed as staged comparison.

See references/teaching-patterns.md and references/cognitive-techniques.md.

Single-Lesson Generation Strategy

Required anchors:

1. Opening objective plus visual cover.
2. Evidence-chain explanation.
3. At least one effective interaction with visible downstream effect.
4. At least one reusable deliverable.
5. Lesson close with summary or decision checkpoint.

Optional modules:

• Viewpoint calibration.
• Misconception correction.
• Dual deliverables (understanding + action).
• Cross-lesson bridge sentence.
• Additional visual-text reinforcement blocks.

Variable Strategy

• Prefer at most one variable collection per module.
• Max five interactions per lesson (recommended three to four).
• No more than three consecutive variable collections before feedback.
• Reuse global variables when possible; add lesson-local variables only when required.
• Every variable must have downstream utility (branching, depth control, or deliverable variation).
• No unresolved placeholders in learner-facing text.
• Do not recollect the same variable unless explicitly marked as staged comparison.
• Prevent semantic duplicates even when variable names differ.

Visual-Text Coordination

• Include an SVG cover in each lesson by default.
• Every core concept must include at least one visual-plus-explanation pair.
• Visuals compress structure; text explains mechanism, limits, and pitfalls.
• Replace unstable source images with generated SVG/HTML visuals when needed.

Interaction Design

• Use no more than one viewpoint_check in a lesson unless justified.
• Each viewpoint_check must trigger a concrete next action.
• If using a "restate-boundary-counterintuitive" pattern, branch by option with distinct content.

Phase 3 Outputs

Return per lesson:

• lesson_id
• lesson_title
• mdf_script
• used_variables
• depends_on_lessons

See references/lesson-template.md.

Phase 3 Validation

• Minimum teaching loop exists (setup, explanation, interaction, close).
• Interaction outcomes visibly alter downstream content.
• Variable safety rules pass (collect before reference, no duplicate recollection).
• Core concepts satisfy visual-plus-text coordination.
• Script remains valid and runnable MarkdownFlow.

Phase 4: Optimization

Audit and improve existing MarkdownFlow teaching prompts. This phase is not for writing from scratch.

When to Use

• Gap analysis against source material.
• Script quality upgrades without full rewrites.
• Consistent chapter style with lower runtime failure risk.

Core Method

1. Start with a low-friction entry point (cover visual + one light interaction).
2. Ensure interactions change downstream logic.
3. Keep structure content-driven, not template-driven.
4. Build evidence chain: observation/history -> mechanism/data -> conclusion.
5. Use visuals for abstract structure and text for mechanism + boundaries.
6. Add viewpoint calibration with branching feedback.
7. Include concrete correction actions for major misconceptions.
8. Keep deliverables executable and reusable.
9. Stabilize syntax and variable usage.

See references/optimization-methodology.md.