Explanation

Explanation

Use this subskill when the user asks why a wrong question is wrong or how to solve it.

Core contract:

• Use scripts/workflow.py start --kind mistake_explanation --wrong-question-id <id> for the normal path. It reuses an existing archived HTML page without a model call, otherwise stops for one bounded explanation candidate and one default Xiaohei image task.
• Load the RawMistakeRecord and its crop image.
• Check scripts/learning_profile.py show --data-dir <dir> --json when personalization would help. If no profile exists, ask the short first-use interview through scripts/learning_profile.py interview-prompt --json and persist with learning_profile.py upsert; do not block the explanation if the user skips it.
• Use scripts/explain_mistake.py build-prompt so the model receives both raw fields and the crop path.
• Re-interpret the visual crop and compare with the recognition-time lightweight analysis.
• Generate student-facing Chinese teaching content by default unless the user asks for another language.
• Keep explanations concise. Prefer short diagnostic sentences and compact checklists over long prose paragraphs.
• Every explanation must first name the core knowledge point from the examiner's perspective, then explain how this specific question tests that point. Store this in core_concept_analysis, including first_principle and invariant_across_variants so the student can see the same essence through different surface variants.
• In 找错因, reconstruct the student's likely wrong solving path from the visible answer/work: what they probably did, what rule or shortcut they misapplied, why that path may have looked reasonable, and what concrete check would have caught it.
• Include TeachAny-style low-cost teaching structure by default: teaching_sequence[], interactive_checks[], and dynamic_visual_plan when a staged visual explanation would help. teaching_sequence[] is source material for dynamic demos or fallback only; do not render it as a long separate explanation when a dynamic visual exists.
• Include one default original-Xiaohei teaching comic for the analysis/root-cause block. Read ../xiaohei-illustration/SKILL.md before generating the bitmap. It should be a 16:9 multi-panel storyboard, not a single mascot scene: several Xiaohei actions, arrows/paths, and short Chinese handwritten labels should carry the core mistake diagnosis inside the image itself. Generate this bitmap by default before rendering the final HTML, attach it with scripts/explain_mistake.py attach-xiaohei-image, and do not scatter Xiaohei illustrations or duplicate side captions across every section.
• Cache structured ExplanationArtifact output by subject with scripts/explain_mistake.py cache-artifact. Reuse the existing archived explanation for a wrong question by default; use --regenerate only when the user explicitly asks to regenerate.
• Keep generated materials archived through ExplanationArtifact.generated_assets. HTML pages, generated illustration images, dynamic visuals, and subject diagrams should be appended as generated assets instead of being treated as disposable temp output.
• Use optional_generation_tasks for high-cost follow-up material only: dynamic visuals beyond the default, subject diagram generation/redraw, knowledge-page generation, or video search. Default Xiaohei generation is not optional.
• Leave video_recommendations empty by default. Only add videos when the user explicitly asks, and verify each recommendation at generation time; never invent links.
• Generate rich local HTML by default with scripts/explain_mistake.py render-page.
• Keep the HTML page compact, navigable, and wide-screen friendly: render four clickable anchor stages (原题截图, 分析错因, 搭正解, 防陷阱练习) instead of dumping every section as a long vertical essay.
• Put the source crop in its own full-width first row.
• In 分析错因, use two flashcards: left is the one-sentence summary plus core_concept_analysis, right is “让我猜猜你为什么错” from the reconstructed student path. Put one full-width Xiaohei comic below those two cards.
• In 搭正解, use full-width blocks instead of side-by-side cards: first a step-reveal/dynamic-demo card, then a subject visual card for the core concept. Use a diagram or dynamic demo according to concept complexity.
• In 防陷阱练习, use two flashcards: left is the first-principles trap and check logic, right is 2-3 concrete transfer_practice_questions. These must be real new 举一反三 questions, not meta-questions about the original mistake. No Xiaohei illustration in this section.
• Explanation-page 练一下 answers are submitted as downloaded AnswerSubmissionBundle JSON. They should use grading_ref and question_snapshot, not embedded answer keys. Import and grade them through scripts/submission_intake.py.
• On desktop and wide screens, use the available canvas for the media column so subject diagrams and embedded teaching HTML are readable without zooming or scrolling inside the frame.
• Render mathematical expressions from formula_latex[] as LaTeX in the HTML page, with MathJax enhancement and a local formatted fallback. Common inline notation (^, _, \frac, \pm, \le, \ge) should still be rendered readably in prose where the local renderer supports it.
• If image generation is unavailable, persist the illustration shot list and prompts instead of blocking the explanation.