knowledge-html-learning-page

name	knowledge-html-learning-page
description	Use when organizing knowledge from local PDF/DOCX/PPT/Markdown/TXT files, project codebases, or web research into Chinese HTML learning pages, course notes, tutorials, study guides, formula-heavy lessons, code walkthroughs, or multi-file static learning sites that require a plan/review gate before generation.

Knowledge HTML Learning Page

Overview

Create source-grounded Chinese HTML learning pages from local documents, codebases, and web references. The core rule is: draft first, promote to plan, get human review, then generate HTML one chapter at a time with evidence.

Use this with the project mineru skill when local documents include PDF, Word, PowerPoint, images, scanned pages, tables, or formulas. If MinerU output is incomplete or visually ambiguous, use a vision model pass on selected pages/slides and record the comparison.

Hard Gate

Do not generate final HTML before the human reviews the learning plan.

Allowed before review:

• Discover and parse sources.
• Save source indexes, extracted notes, code maps, formula notes, image inventories, draft.md, plan.md, and review-gate.md.
• Produce small HTML snippets only inside the plan as examples of proposed structure.

Forbidden before review:

• Creating final.html, dist/, or full chapter HTML files.
• Saying a generated page is ready.
• Treating "draft HTML" as draft.md or plan.md.
• Generating all chapters at once without chapter validation, evaluation, and promotion evidence.

Workflow

1. Intake Sources

Identify source categories and keep them separated in notes:

Source	Required handling
PDF, DOCX, PPT, images, scanned docs	Use mineru when applicable; preserve Markdown, formulas, tables, and extracted images. If extraction quality is poor, run a visual-model extraction pass on the affected pages/slides.
Markdown/TXT	Read headings, examples, formulas, and image references; normalize into staged notes.
Project codebase	Explore structure, read real files, tests, examples, and call paths before explaining code.
Web search	Use only when needed for missing background, official docs, or verification; label external material clearly.

For document parsing, load and follow mineru. Typical command shapes:

python3 .agents/skills/mineru/scripts/mineru.py lecture.pdf --output .learning-pages/<topic>/mineru-output --json
python3 .agents/skills/mineru/scripts/mineru.py ./docs/ --output .learning-pages/<topic>/mineru-output --workers 8 --resume
python3 .agents/skills/mineru/scripts/mineru.py scanned.pdf --ocr --lang ch --output .learning-pages/<topic>/mineru-output

After MinerU parsing, assess extraction quality before planning. Use visual-model extraction when:

• A page/slide is mostly diagram, chart, table, or formula image.
• MinerU drops labels, arrows, equations, table structure, or speaker-note context.
• OCR text conflicts with visible content.
• A formula or figure is central to teaching and needs precise interpretation.

Record visual extraction in visual-extraction-notes.md and reconcile it with MinerU output in source-index.md or extracted-notes.md. Do not silently replace MinerU text with visual-model guesses.

2. Create Intermediate Workspace

Before planning, create a topic workspace using references/workspace-layout.md. Save intermediate files under .learning-pages/<topic>/.

Minimum required files before review:

• source-index.md
• extracted-notes.md
• code-map.md when a codebase is involved
• web-references.md when web search is used
• formula-notes.md when formulas appear
• image-inventory.md when images, SVGs, or generated visuals are needed
• visual-extraction-notes.md when visual-model extraction is used
• draft.md
• plan.md
• review-gate.md

3. Build draft.md

Use references/draft-workflow.md. draft.md must be written before plan.md and must include:

• Current total problem and learning goal.
• Learning stages.
• Major risks and unknowns.
• Candidate learning content ranked by value.
• First chapter detailed teaching steps.
• Validation and evaluation approach.
• Evidence needed to promote or reject content.

Reject or revise draft.md if it is only a syllabus, only a table of contents, or lacks evidence requirements.

4. Promote draft.md To plan.md

Use references/plan-workflow.md. plan.md must be directly decomposable into chapter loops. Every chapter must state:

• What this chapter teaches.
• Why it matters.
• How it relates to previous and later context.
• Important concepts, formulas, algorithms, and ideas.
• Classic teaching case or worked example.
• Exercises.
• Validation checks, evaluation criteria, evidence needed, blockers, and output target.

Stop after writing plan.md and review-gate.md. Do not proceed to HTML until the user approves or the continuation instruction explicitly authorizes proceeding.

5. Generate Learning Pages By Chapter Loop

After approval, generate static document-style HTML using references/chapter-generation-loop.md and references/html-page-template.md.

Inner chapter loop:

• Implement one chapter's teaching plan.
• Run validation.
• If validation fails, revise or reject.
• If validation passes, run evaluation.
• Record result.
• Decide keep, revise, or reject before moving to the next chapter.

Outer chapter promote rule:

• Promote only when validation passes.
• Correctness requirements are satisfied.
• Evidence is recorded.
• Blockers are explicit.
• promotion-log.md includes the decision.

Rejected chapters must be recorded in promotion-log.md; never drop them silently.

Content requirements:

• Use Chinese as the main language; keep professional terms in English where useful.
• Teach in a human sequence: intuition -> definition -> derivation -> example -> practice -> summary.
• Explain formulas in detail: symbols, assumptions, units, derivation steps, intuition, edge cases, and common mistakes.
• Add internal anchors and links back to earlier explanations when a later section depends on them.
• Include examples and exercises where useful; answers default collapsed with <details>.
• Use source-grounded diagrams or images. Use SVG for precise conceptual diagrams; use GPT image generation only for pedagogical visuals that are hard to draw as SVG.

UI requirements:

• Document-style page, not dashboard.
• Light background, readable typography, high contrast, generous line height.
• Clear section rhythm, semantic HTML, responsive content width.
• Clear math rendering with MathJax by default or KaTeX for faster standard TeX.
• Use separate chapter HTML files when one large HTML file would hurt search, review, or navigation.

6. Quality Gate

Before completion, run references/quality-checklist.md against the workspace and generated HTML.

Reject and revise if any of these appear:

• Shallow summary that skips important source content.
• Generic AI prose or repetitive filler transitions.
• Dashboard layout, dark theme, KPI cards, or decorative SaaS styling.
• Formulas shown without explanation.
• Images used without captions or text alternatives.
• Web material blended into source notes without labeling.
• Broken relative links or assets.
• Visible exercise answers that should be collapsed.
• Missing per-chapter validation/evaluation evidence.
• Promoted or rejected chapters missing from promotion-log.md.

Common Mistakes

Mistake	Correction
Generating HTML immediately	Write draft.md, promote it to plan.md, write review-gate.md, then stop for review.
Treating the draft as the plan	Use draft.md for learning-design hypotheses and plan.md for loop-executable chapter plans.
Batch-generating all chapters	Use the chapter loop and promote each chapter with evidence.
Dropping weak chapters silently	Record revise or reject in promotion-log.md with evidence.
Summarizing slides instead of teaching	Reorder content by learner progression and explain missing reasoning.
Ignoring hard PDF/PPT formulas	Use MinerU/OCR first; if quality is poor, run visual-model extraction on the affected pages/slides, compare results, and mark uncertain symbols.
Pretending code was analyzed	Read actual code paths, tests, and examples; cite files in code-map.md.
Using web search silently	Separate web references and explain why each external source was used.
Making a dashboard	Use article layout, semantic sections, and restrained typography.

References

• references/workspace-layout.md - intermediate files and output structure.
• references/draft-workflow.md - required draft.md schema and depth gate.
• references/plan-workflow.md - required plan.md schema and chapter-loop decomposition.
• references/chapter-generation-loop.md - per-chapter validation, evaluation, promote/reject workflow.
• references/html-page-template.md - HTML, CSS, math, image, SVG, and exercise patterns.
• references/quality-checklist.md - final verification checklist.
• references/skill-test-scenarios.md - pressure scenarios for future skill edits.