peter-zhou-xiaohei-illustration

name	peter-zhou-xiaohei-illustration
description	Generate original Xiaohei teaching comics for Peter Zhou wrong-question explanations and knowledge pages. Use when creating or regenerating Xiaohei-style root-cause, concept-anchor, solution-path, or trap-guardrail illustrations for student-facing teaching artifacts.

Xiaohei Illustration

Use this child skill when a Peter Zhou workflow needs an original Xiaohei teaching illustration.

Contract

• Generate one complete 16:9 bitmap comic per illustration request.
• The comic itself carries the teaching point through Xiaohei actions, arrows/paths, and short Chinese handwritten labels.
• Do not generate a blank-label image and add text later with PIL, SVG, HTML, CSS, or a side caption. If image text is wrong, regenerate or use image editing; only use local overlay when the user explicitly approves that exception.
• Xiaohei explains thinking only. It never replaces exact source diagrams, formula rendering, safe student-facing assets, or reviewed SVG redraws needed to solve a question.

Default Explanation Workflow

1. Start from an existing ExplanationArtifact.

2. Build the dedicated image prompt:

   python skills/peter-zhou/scripts/explain_mistake.py build-xiaohei-prompt \
     --data-dir data \
     --subject <subject> \
     --explanation-id <explanation-id> \
     --output tmp/<explanation-id>-xiaohei-prompt.txt \
     --json
   

3. Use the built-in image generation tool with that prompt. Do not remove the prompt's requirement that text is generated inside the image.

4. Inspect the generated image against the QA checklist below. If text is unreadable or wrong, regenerate with fewer/shorter labels or edit the image; do not switch to post-processing by default.

5. Save the chosen project asset under data/explanation-assets/<wrong-question-id>/, using a versioned file name when replacing an existing image.

6. Attach the image through script-owned persistence:

   python skills/peter-zhou/scripts/explain_mistake.py attach-xiaohei-image \
     --data-dir data \
     --subject <subject> \
     --explanation-id <explanation-id> \
     --image-ref explanation-assets/<wrong-question-id>/<file>.png \
     --json
   

7. Re-render the explanation page with explain_mistake.py render-page.

Default Knowledge Module Workflow

1. Start from an existing KnowledgeModuleContext.

2. Generate the three default purposes when image generation is available: concept_anchor, solution_path, and trap_guardrail.

3. Build one prompt per purpose:

   python skills/peter-zhou/scripts/knowledge_learning.py build-xiaohei-prompt \
     --data-dir data \
     --context data/knowledge-modules/<subject>/<normalized_topic>/context.json \
     --purpose concept_anchor \
     --output data/knowledge-modules/<subject>/<normalized_topic>/assets/concept_anchor_prompt.txt \
     --json
   

4. Use the built-in image generation tool with that prompt. The generated drawing must contain the Chinese labels in the bitmap itself.

5. Inspect the image against the QA checklist. If it becomes a simple mascot scene, a Xiaojing/glasses figure, a PPT flowchart, or unreadable label soup, regenerate with fewer labels.

6. Save the chosen asset under data/knowledge-modules/<subject>/<normalized_topic>/assets/.

7. Attach it through script-owned persistence:

   python skills/peter-zhou/scripts/knowledge_learning.py attach-xiaohei-image \
     --data-dir data \
     --context data/knowledge-modules/<subject>/<normalized_topic>/context.json \
     --purpose concept_anchor \
     --image-ref knowledge-modules/<subject>/<normalized_topic>/assets/concept_anchor.png \
     --json
   

8. Repeat for solution_path and trap_guardrail, then re-render with knowledge_learning.py render-page.

Original Xiaohei Style

• Pure white background; minimalist black hand-drawn line art; slight pen wobble; lots of whitespace.
• Xiaohei is a small solid-black absurd creature with white dot eyes, tiny thin legs, blank serious expression, and a slightly uneven body.
• Xiaohei must perform the core conceptual action: opening, pulling, sorting, stamping, getting stuck, checking, carrying, or repairing.
• Use sparse red/orange/blue handwritten Chinese annotations: red for mistakes or warnings, orange for the main path, blue only for secondary notes.
• Keep labels short: 5-8 labels at most, usually 2-8 Chinese characters each.
• Avoid PPT/course-slide diagrams, commercial vector style, cute mascots, children's illustration, complex backgrounds, gradients, shadows, and top-left type titles.

Peter Zhou Adaptation

• For root_cause_portrait, show the student's likely wrong path first, then the missing check and the core idea.
• For concept_anchor, show the first-principles structure behind a knowledge point, not the exact original problem diagram.
• For solution_path, show how thinking moves from known conditions to target conclusion.
• For trap_guardrail, show the trap's underlying mechanism and the check that blocks it.
• In detailed mistake explanations, default to one root_cause_portrait comic in 分析错因; do not scatter Xiaohei images across every section.

QA Checklist

• The image is 16:9 and clean white.
• Xiaohei is present and doing the main cognitive action.
• The short Chinese labels are generated in the image, readable, and not replaced by external HTML text.
• The comic communicates the root cause without a separate right-side caption.
• It is a strange but clear sketch, not a formal flowchart or courseware panel.
• The asset is copied into the project and attached with attach-xiaohei-image.