peter-zhou-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.