kylecui/petfish.ai/course-content-authoring

Purpose

Write or refine lesson-level course content.

Default content structure

For each chapter or lesson, cover:

1. teaching objective
2. key terms/concepts
3. explanation path
4. examples or demonstrations
5. common misunderstandings
6. summary
7. optional reflection/exercise

Authoring behavior

• Write for the target audience's level, not for the source author's level.
• Prefer a teaching progression: definition -> mechanism -> example -> boundary -> takeaway.
• Keep conceptual accuracy and teaching usability aligned.
• Mark places that need diagrams, demos, or labs.

Review behavior

When reviewing existing content, look for:

• concept gaps
• sequence problems
• weak transitions
• missing examples
• excessive density
• lack of learner checkpoints

Done-Checklist

A lesson is NOT complete until every item holds:

• [ ] Objective is measurable (action verb + observable behavior)
• [ ] Prerequisites stated explicitly
• [ ] At least one worked example
• [ ] At least one misconception exposed
• [ ] Exercises carry grading criteria
• [ ] Summary ties back to the objective
• [ ] Duration budget aligns with the outline allocation
• [ ] Persisted to docs/02-content — 未写入 docs/02-content = 未完成 (not persisted = not done)

qa_scan.py check #10 verifies the presence of the explicit section markers (objective / example / exercise / duration). It is a structure completeness check, not a semantic quality assessment — passing it does not prove the lesson teaches well.

Gotchas

• Do not duplicate the outline file inside every chapter.
• Do not let examples become detached from the core point.
• Do not bury the most important explanation after too much setup.
• Do not assume the chapter is teachable just because it is technically correct.

See:

• assets/lesson-template.md
• references/teaching-flow-patterns.md
• references/pedagogy-compact.md（教学法速查：Bloom动词表/认知负荷三原则/样例渐退/误解前置/检索练习——按需读取，勿内联进正文或提示词）