peter-zhou-knowledge-learning

name	peter-zhou-knowledge-learning
description	Create reusable graph-grounded system knowledge lessons for recurring weak topics. Use for learning-unit selection, agent teaching drafts, controlled explanatory animation, linked practice, and archived HTML courseware.

Knowledge Learning

Use this subskill when the user asks to learn a knowledge point, a weak tag surfaced by overview, or a larger system topic such as "指数方程中的分类讨论" rather than one surface wrong-question tag.

Core contract:

• Use scripts/workflow.py start --kind knowledge_courseware after graph selection and verified practice are ready. The workflow stops only for graph_teaching_draft.v1, then scripts build and validate the courseware.
• Normalize subject and knowledge tag.
• Check scripts/learning_profile.py show --data-dir <dir> --json and use grade/stage, explanation preference, difficulty preference, goals, and weak subjects when present. For deep modules, build-context reads LearningProfile automatically when available and marks the Phase 1 contract as source="inferred" when it is missing; do not block module generation solely because the profile has not been created yet.
• For deep learning, first select a bounded graph learning unit. The graph owns the topic boundary, prerequisite order, target skills, misconceptions, and verified exercises.
• If a broad tag would pull unrelated evidence into a system topic, pass curated --wrong-question-id <id> values so the module is grounded in the exact wrong questions the agent selected.
• Render the archival continuous deep module with scripts/knowledge_learning.py render-page --data-dir <dir> --context <context.json> --json when a long reference page is useful.
• Use scripts/knowledge_learning.py build-courseware as the only default student-courseware entry. It builds the context, renders HTML, and runs semantic validation in one command. Do not separately call render-courseware as a shortcut.
• Before a source-backed junior-high module, run scripts/knowledge_graph.py audit-sources --json and scripts/knowledge_graph.py validate-seed --seed-dir references/knowledge-graph/math-junior-high --json. The installed skill must work from the packaged source contracts and normalized seed; .reference-projects/ is never a runtime dependency.
• Keep recognition-time knowledge_tags[] as lightweight display/aggregation fields. Use optional knowledge_refs[] only after a reviewed topic overlay maps a wrong question to stable graph nodes. Every ref carries topic_id, graph_version, node_id, role (primary, secondary, or prerequisite), and a short rationale.
• Resolve every system topic through scripts/knowledge_graph.py resolve-topic-package --topic <slug> --data-dir <dir> --json. A versioned packaged_reviewed package wins; otherwise a validated agent_generated archive under data/knowledge-assets/topics/<slug>/package.json is reused. Build the slice with build-topic-slice --topic <slug> --data-dir <dir> --mistake-bank <subject.json> --output <topic.json> --json. Apply mappings only through apply-topic-mappings; do not let the agent hand-edit mistake-bank arrays.
• Select the smallest graph needed for the requested mode with select-subgraph: mode=explanation starts from one wrong question and returns its primary/secondary nodes plus required prerequisites; mode=deep-learning returns reviewed learning_units[]. A learning unit must be a coherent connected path, not every downstream application sharing a broad tag.
• Treat upstream K12-KGraph exercises as candidates. Promote them with apply-exercise-verifications only after all checks pass: answer correctness, notation integrity, complete context, uniqueness from source mistakes, and node alignment. A topic package may instead carry exactly three exercises already verified against the same five checks; normalize those only through build-topic-exercise-pool. select-practice refuses unverified exercises and emits student tasks without answers plus a separate script-side grading key.
• In rendered practice, keep the correct answer collapsed. 显示答案 stays disabled until the student enters and submits that task's answer; submission locks the answer field, then enables the separate answer toggle. Downloaded submission JSON continues to carry the student's answer for later Agent grading.
• After the topic package is resolved, the running agent creates only graph_teaching_draft.v1 for the courseware stage. The draft contains one entry, exactly three mechanism cards, one summary, and semantic animation specs. Every mechanism card must cite selected node ids. The agent may write friendly explanations, analogies, and minimal examples, but it must not alter the resolved knowledge scope, prerequisite path, linked evidence, or practice set.
• Build graph-backed courseware with build-courseware --knowledge-selection <selection.json> --knowledge-practice <practice.json> --teaching-draft <draft.json>. The script owns evidence quality filtering, context assembly, graph_lesson_blueprint.v1, rendering, metadata, and final validation.
• render-courseware rejects any context without graph_lesson_blueprint.v1. Do not retry through the historical topic-name/TeachAny renderer. render-page remains the archival continuous-page path for historical contexts.
• If resolution finds no topic package, the running agent owns one explicit bootstrap step: author a candidate from the packaged base graph, current student evidence, and checked subject knowledge; label it asset_origin="agent_generated" and verification_status="agent_verified"; include provenance plus exactly three verified prerequisite/core/transfer exercises; then call archive-agent-topic. The script validates graph references, mappings, learning-unit coherence, the five exercise checks, content hash, and archive location. Never write this candidate into the Skill's packaged overlay directory or label it packaged_reviewed.
• One eligible wrong question is enough to ground a deep module; three wrong questions are not required. The separate requirement is exactly three verified practice roles. If the agent cannot verify the candidate, any exercise, or a coherent learning unit, mark the uncertainty outside the archive and stop. Do not bypass the archive validator or claim that courseware was completed.
• Agent topic archives record generated_by, generated_at, base_graph_version, source_refs, content_hash, and validation_report. Same-hash regeneration is reused. Different content requires explicit --refresh. If a packaged topic later appears, it takes precedence while the Agent archive remains a distinguishable audit asset.
• Wrong-question evidence is script-filtered before it can influence the lesson or mastery links. Records with total confidence < 0.70, or without visible question, student answer, or mistake analysis, are listed under excluded_wrong_question_evidence and are not linked to the generated courseware.
• Content target: 55% graph/verified exercises, 25% current-model teaching translation, 15% student mistake evidence, and 5% fixed template copy. Previously frozen Agent prose may contribute at most 5% and cannot be the source of a knowledge claim.
• A deep module is not a wrapper around one tag and is not a wrong-question explanation. Wrong questions select emphasis; they do not define the entire lesson sequence.
• Wrong questions are supporting evidence for why the topic matters. They should not be the main teaching path, the only worked example, or the default Xiaohei prompt input.
• Use the same pixel/Minecraft visual language and wide-screen useful canvas as the current Peter Zhou pages. The default student HTML is exactly six cards: entry/diagnosis with visible eligible mistake evidence, three graph-grounded mechanisms, three linked exercises, and one exam-check summary.
• Do not add animation to entry, practice, or summary cards. Each mechanism card has one teaching animation with a single stated goal.
• Animation defaults to paused. It provides previous, next, optional auto-play, and replay controls. Steps persist earlier mathematical states, highlight only the change, and finish with a concrete student check. Decorative card motion does not satisfy the contract.
• Use a subject visual adapter only when it reveals a mechanism: algebra area/formula morph, geometry construction, physics state/force evolution, or another causal change. Prefer a static figure when time does not matter.
• Reuse the adapted xiaohei-illustration/ child skill for default knowledge-module comics: concept_anchor, solution_path, and trap_guardrail.
• For each default comic, build the prompt with scripts/knowledge_learning.py build-xiaohei-prompt --data-dir <dir> --context <context.json> --purpose <purpose> --output <prompt.txt> --json, generate a real original Xiaohei bitmap when image generation is available, copy it under data/knowledge-modules/<subject>/<normalized_topic>/assets/, then attach it with scripts/knowledge_learning.py attach-xiaohei-image --data-dir <dir> --context <context.json> --purpose <purpose> --image-ref <ref> --json.
• Re-render the module after attaching images. If image generation is unavailable or a generated image fails QA, keep the shot list and saved prompt without blocking the learning artifact.
• Treat overview knowledge_page_recommendations[] as lightweight suggestions. If the recommendation is status="recommended", ask for user confirmation before generating a page. If it is status="archived", reuse the existing html_ref.
• Use scripts/knowledge_overview.py knowledge-page only for the existing lightweight subject/tag KnowledgePage path.
• Store/reuse lightweight page metadata through data/knowledge-pages/index.json.
• Use --refresh only when an archived page should be regenerated after template/content improvements or user-requested correction.
• Generate local HTML focused on the minimum graph-selected first principles, mechanism animations, examples, common errors, three linked exercises, and a reusable final check. Extra illustrations or games are optional assets and must not expand the default six-card path unless the user requests them.
• Do not create learning-session or completion-tracking tables.

Distinction:

• ExplanationArtifact: teaches one wrong question.
• KnowledgePage: lightweight reusable page for one normalized weak tag.
• KnowledgeModuleContext: archived system-topic evidence plus a validated graph lesson blueprint generated from multiple wrong-question signals.