chapter-content-generator

章コンテンツジェネレーター

バージョン： 1.11

バージョン 1.11 の機能：

• 目的を優先した、精密で客観的な MicroSim 仕様 - すべての仕様ブロックに、シミュレーションの作り方ではなく、学習者が何を学び、何を証明すべきか、そしてシミュレーションに必要なコンテンツ全体が記載されるようになりました。新しい構造化フィールド（Bloom Level、Bloom Verb、Learning Objective、Evidence of Mastery、Misconceptions、Instructional Rationale、Content、Provenance、Rules、Learner Activity、Feedback、Starting State、Chapter Anchors）とセルフチェックは、新しい references/microsim-specification-rules.md で定義されています。レイアウト、ピクセルサイズ、色、コントロールの配置、ライブラリの呼び出し方は、microsim-generator に委ねられます。このルールは、エージェントが仕様の不足を450件報告し、シミュレーションの49％が仕様から逸脱せざるを得なかった、112件の MicroSim 一括実行から生まれました。
• 一括処理ツールが解析できる Bloom フィールド - **Bloom Level:** と **Bloom Verb:** は、独立したヘッダー行になりました。以前のインライン形式 Learning objective (Bloom level: X; verb: Y): は解析できず、ツールは112件中109件のシミュレーションを「Create」と分類していました。
• content-element-types.md にあった実現不可能または矛盾する指示を修正 - Bloom のリストに6段階のうち4段階しか記載されていなかったこと、Mermaid では不可能なエッジのクリックを必須としていたこと、埋め込みページ内でマウスホイールによるズームを求めるグラフの例、iframe のプレースホルダーを500 pxと固定した例、閉じられていないコードブロックによって MicroSim の例がコードブロックに取り込まれていたことを修正しました。

バージョン 1.10 の機能：

• マスコットの配置ルールを一元化 - ステップ2.4の原則4から、第1章の自己紹介パターンとマスコットの登場頻度に関する数値を削除しました。これらは両方とも、正規の $BK_HOME/skills/book-installer/references/mascot-placement-rules.md に記載されるようになりました。ライブラリ内のすべてのスキルは、ルールを個別に記載し直すのではなく、このファイルを参照します。これにより、2つの異なる配置表に章ごとの回数が食い違ったまま記載されていた問題が解消されます。
• フロントマターでバージョンを追跡 - version: キーを単独で置くのではなく、metadata: の下に metadata.ibook.version として記載します。単独のキーでは厳密なパッケージ検証に失敗します。

バージョン 1.09 の機能：

• 重大な変更：CIS に基づく詳細化の予算 - 概念ごとの語数と非テキスト要素の要件は、「3000～5000語、非テキスト要素4～6個」のように章全体で一律に設定されなくなりました。各概念には、book-chapter-generator v1.0.0 以降が各章の「Concepts Covered」表に書き込む「CIS Score」列から読み取った**概念インパクトスコア（CIS）**に基づいて、個別の語数範囲と非テキスト要素の最小要件が設定されます。基礎的で影響の大きい概念は、具体例や図を用いて十分に詳しく説明し、範囲が狭く影響の小さい概念は、効率よく簡潔に扱います。以下の「詳細化の予算」（ステップ2.3b）を参照してください。book-chapter-generator v1.0.0 以降が生成した章（表形式）と、learning-graph-generator v1.06 以降が生成した learning-graph.json（node.cis を含む）が必要です。

バージョン 0.09 の機能：

• 第1章でのマスコットの自己紹介 - プロジェクトの CONTENT-GENERATION-GUIDE.md で教育用マスコットが定義されている場合、第1章で最初にマスコットを登場させる際の注意書きでは、マスコットが自ら名乗り、本全体で担うそれぞれのポーズと役割を列挙する必要があります。このパターンは、ライブラリ全体で一度だけ mascot-placement-rules.md に定義されています（ステップ2.4、原則4を参照）。 バージョン 0.07 の機能：
• 指導のための足場づくり - 定義してから表示するルールにより、図で用語を使用する前に用語を説明し、コード例を示す前にコードのパラメーターを説明し、表で概念を導入するのではなく補強します（Step 2.4、原則 3 を参照）
• 逐次実行 - トークンの過剰な使用を避けるため、一度に 1 章ずつコンテンツを生成します。ユーザーは「use parallel execution」というフレーズでこれを変更できますが、その場合、トークンが 38% 追加で使用されることをスキルが警告します
• エッジ方向の検証 - 依存関係が逆転するバグを防ぐための必須チェックです（Step 1.3a を参照）

このスキルを使用する場面

次の場合にこのスキルを使用してください：

• book-chapter-generator スキルが、index.md ファイルを含む章ディレクトリを作成済みの場合
• 章の index.md に、タイトル、概要、対象となる概念のリストが含まれている場合
• 詳細な章のコンテンツを生成する必要がある場合
• 読解レベル（中学生、高校生、大学生、大学院生）に合わせてコンテンツを調整する場合
• 図、MicroSim、インフォグラフィックなど、テキスト以外の豊富な要素を使用したい場合

次の場合はこのスキルを使用しないでください：

• 章の構成がまだ作成されていない場合（先に book-chapter-generator を使用してください）
• コンテンツがすでに存在し、編集だけが必要な場合（Edit ツールを直接使用してください）
• ほかの種類のコンテンツ（プロンプト、用語集など）を生成する場合
• ユーザーの 5 時間の期間内でのトークン使用量が 95% を超えている場合

実行モード

逐次モード（すべてのユースケースでのデフォルト）

• 並列モードは大きなオーバーヘッドがあるため、常に一度に 1 章だけを処理します
• 次の章を始める前に、章の処理が完全に終わり、セッションのログが記録されるまで待ちます
• 各章が完了したら、ユーザーに明確に伝えます

並列モード（リクエストがあった場合のみ）

並列モードは、ユーザーが並列実行を明確にリクエストした場合にのみ使用してください。 並列実行には相当なトークンの追加コストがかかることをユーザーに警告してください。

単一章モード

次の場合に使用します：

• 概要の改訂後に 1 章を更新する場合
• 一括生成の前にコンテンツ形式をテストする場合

ワークフロー

フェーズ 1：セットアップ（逐次）

このフェーズは、コンテンツの生成を始める前に一度実行し、すべてのエージェントが必要とする共有コンテキストを読み込みます。

Step 1.1：ログ記録用の開始時刻を取得する

date "+%Y-%m-%d %H:%M:%S" >>logs/ch-{NN}-content-generation.md

{NN} は、ゼロ埋めされた 2 桁の章番号です。

セッションレポート用に開始時刻を記録します。

Step 1.2：スキルの実行を通知する

ユーザーに次のように通知します：「Chapter Content Generator Skill v1.11 を［並列／逐次］モードで実行しています。」

ステップ 1.3：共有コンテキストを読み込む

すべてのエージェント向けに、次のファイルを読み込んでキャッシュします。

1. コースの説明（docs/course-description.md）

   • 対象読者と読解レベルを抽出します
   • プロジェクトの CONTENT-GENERATION-GUIDE.md にあるコースの目標とトーンのガイドラインを確認します
   • プロジェクトの CONTENT-GENERATION-GUIDE.md にあるマスコットや物語の要素（例：微積分におけるデルタ）を特定します

2. 学習グラフ（docs/learning-graph/learning-graph.json および／または learning-graph.csv）

   • 依存関係を含む概念リストを読み込みます
   • 教育上の順序付けのために、概念間の関係を把握します
   • cis_max を計算します = 書籍内のすべてのノードにおける cis の最大値（max(n.get('cis', 1) for n in data['nodes'])）。この値はセッション内のすべての章で再利用します。Elaboration Budget の正規化（ステップ 2.3b）は常に全体（書籍全体を基準）で行い、章単位では行いません。概念の重要性は書籍全体に関するものであり、章単位の主張ではないためです。すべてのノードの cis が 1 の場合、学習グラフは learning-graph-generator v1.06 より前のものです。フラットな単語数に黙ってフォールバックするのではなく、その旨をユーザーに伝え、先に進む前に learning-graph.json を再生成するよう提案してください。

   !!! info "学習グラフ = 概念依存グラフ（DAG）" 学習グラフは概念依存グラフです。各エッジが「依存する」関係を表す有向非巡回グラフ（DAG）です。トポロジカルソート、サイクル検出、推移的縮約の標準的なグラフ理論アルゴリズムに合致するため、依存方向（エッジが概念から、その概念が依存する概念へ向かう方向）を使用します。

   一部の学習管理システムでは、エッジが反対方向（前提条件から、それによって可能になる概念へ向かう方向）の**イネーブルメントグラフ**を使用します。この方向は教師によってはより直感的ですが、グラフアルゴリズムにはあまり適していません。このプロジェクトでは、依存方向のみを使用します。
   

   !!! danger "重大：learning-graph.json のエッジの方向" vis-network JSON 形式では、エッジは依存する概念から前提概念へ（依存方向）向かいます。

   - エッジ `{from: 5, to: 1}` は、「生物多様性（5）は生態学（1）に依存する」という意味です
   - 「生態学が生物多様性につながる」という意味ではありません（これはイネーブルメント方向です）
   
   **前提条件マップを作成するには：**
   ```python
   # 正しい：依存方向 -- from=依存する概念、to=前提概念
   prereqs[edge['from']].add(edge['to'])
   ```
   
   **次のようにしてはいけません：**
   ```python
   # 誤り：誤ってイネーブルメント方向に変換し、すべての依存関係を逆転させる
   prereqs[edge['to']].add(edge['from'])
   ```
   
   これを誤ると、何百もの誤った違反が生じ、不適切な章構成に大量のトークンを浪費します。先に進む前に、必ずステップ 1.3a で検証してください。
   

3. 用語集（docs/glossary.md）

   • 用語の定義があれば読み込み、一貫した用語を使用します
   • ほとんどの場合、用語集はコンテンツ生成後に作成されます
   • 用語集に項目がある概念を確認します

4. プロジェクトの CONTENT-GENERATION-GUIDE.md（存在する場合）

   • プロジェクト固有のガイドラインを読み込みます
   • 読解レベル、マスコットの仕様、トーンの要件、特別な書式があれば確認します

5. 章の一覧（docs/chapters/ ディレクトリをスキャン）

   • すべての章ディレクトリを列挙します
   • コンテンツ生成が必要な章（アウトラインはあるがコンテンツがない章）を特定します

Step 1.3a: エッジの方向を検証する（必須）

依存関係データを使用する前に、エッジの方向が正しいことを確認してください。このステップにより、章の生成で最も頻繁に発生し、最も大きな損害をもたらすバグ、つまり依存関係マップが逆向きになり、無効な章の順序が気付かれないまま生成される問題を防げます。

検証手順：

1. 基礎となる概念を特定します。CSV で Dependencies が空になっているもの、または JSON で前提条件がゼロのものです
2. prereqs[edge['from']].add(edge['to']) を使用して、前提条件マップを作成します
3. 基礎となる概念について、prereqs マップにエントリがゼロであることを確認します

import json
from collections import defaultdict

with open('docs/learning-graph/learning-graph.json') as f:
    data = json.load(f)

# Build prereqs: from=dependent, to=prerequisite
prereqs = defaultdict(set)
for e in data['edges']:
    prereqs[e['from']].add(e['to'])

# Find concepts with zero prerequisites (foundational)
all_ids = {n['id'] for n in data['nodes']}
foundational = all_ids - set(prereqs.keys())

print(f"Foundational concepts (no prerequisites): {len(foundational)}")
for fid in sorted(foundational):
    node = next(n for n in data['nodes'] if n['id'] == fid)
    print(f"  {fid}: {node['label']}")

# SANITY CHECK: foundational concepts should be simple/introductory
# If you see advanced concepts here, the edge direction is WRONG

合格基準：

• 基礎となる概念は、平易で入門的な用語である必要があります（例：「Ecology」、「Energy」、「System」）
• 高度な概念（例：「Sustainability」、「Climate Change」、「Tipping Points」）が基礎となる概念として現れる場合、エッジの方向が逆になっています。作業を中止し、先に修正してください
• 基礎となる概念の数は少ないはずです（通常、概念数 200～400 のグラフで 3～10 個）
• 「基礎となる」概念が 50 個以上ある場合は、方向が逆になっている可能性が高いです

検証に失敗した場合： コンテンツ生成に進まないでください。問題をユーザーに報告し、正しいエッジの方向で再実行するよう提案してください。

Step 1.3b: 章の依存関係の順序を確認する（必須）

エッジの方向を検証した後、各章の概念の前提条件がすべて前の章で扱われていることを確認してください。これにより、後の内容を先取りせずに、既習の内容を参照できるようになります。

# Build chapter_map: concept_id -> chapter_index
chapter_map = {}
for i, (title, cids) in enumerate(chapters):
    for cid in cids:
        chapter_map[cid] = i

# Check: for every concept, all prerequisites must be in same or earlier chapter
violations = []
for i, (title, cids) in enumerate(chapters):
    for cid in cids:
        for dep in prereqs.get(cid, set()):
            if dep in chapter_map and chapter_map[dep] > i:
                violations.append(
                    f"  {nodes[cid]['label']}(ch{i+1}) needs "
                    f"{nodes[dep]['label']}(ch{chapter_map[dep]+1})"
                )

if violations:
    print(f"DEPENDENCY VIOLATIONS: {len(violations)}")
    for v in violations:
        print(v)
    print("\nDo NOT generate content until all violations are resolved.")
else:
    print("All dependencies respected. Safe to generate content.")

合格基準： 違反がゼロであること。違反がある場合は、コンテンツ生成を始める前に章の構成を修正する必要があります。

Step 1.4: 読解レベルを決定する

コースの説明から、学年相当の読解レベルを抽出します。

読解レベルの指標：

• 「grade-school」、「grade school」、「grades 1-6」、「elementary school」→ 小学校
• 「junior-high」、「junior high」、「grades 7-9」、「middle school」→ 中学校
• 「senior-high」、「senior high」、「grades 10-12」、「high school」→ 高校
• 「college」、「undergraduate」、「bachelor」→ 大学
• 「graduate」、「master」、「masters」、「master's」、「PhD」、「doctoral」→ 大学院

読解レベルの特徴：

• 小学校（1～6 年生）： とても短い文（10～14 語）、一般的な語彙、具体例、視覚資料を頻繁に使用
• 中学校（7～9 年生）： 簡潔な文（12～18 語）、一般的な語彙、具体例、視覚資料を頻繁に使用
• 高校（10～12 年生）： 複雑さに幅のある文（15～22 語）、定義を添えた専門用語、具体的な内容と抽象的な内容のバランス
• 大学： 学術的な文体（18～25 語）、専門用語、事例研究、研究の背景
• 大学院： 高度な文章表現（20～30 語以上）、専門用語を全面的に使用、理論的な深さ、研究文献

指定がない場合は、10 年生（高校）をデフォルトにします。

Step 1.5: 章をバッチに分ける（並列モード）

並列処理のために章をバッチに分けます。

バッチサイズのガイドライン：

• 4～8 章：2 エージェント（各 2～4 章）
• 9～15 章：3～4 エージェント（各 3～4 章）
• 16～24 章：4～6 エージェント（各 4～5 章）
• 25 章以上：5～6 エージェント（各 5～6 章）

23 章の場合の例：

Agent 1: Chapters 1-4 (Foundations)
Agent 2: Chapters 5-8 (Core Concepts Part 1)
Agent 3: Chapters 9-12 (Core Concepts Part 2)
Agent 4: Chapters 13-16 (Applications Part 1)
Agent 5: Chapters 17-20 (Applications Part 2)
Agent 6: Chapters 21-23 (Advanced Topics)

フェーズ 2：コンテンツの生成（並列または逐次）

並列実行

Task ツールを使用して、複数の Task エージェントを同時に起動します。各エージェントには以下を渡します。

1. 共有コンテキスト（コース情報、読解レベル、用語集の用語、トーンのガイドライン）
2. 担当する章（特定の章ディレクトリ）
3. コンテンツ形式のテンプレート（このスキルの標準形式）
4. 出力指示（各章の index.md にコンテンツを書き込む）

エージェントプロンプトのテンプレート：

You are generating educational content for an intelligent textbook. Generate
detailed chapter content for the following chapters.

COURSE CONTEXT:
- Course: [course name]
- Target audience: [audience]
- Reading level: [level] - [characteristics]
- Tone: [tone guidelines from course description or CONTENT-GENERATION-GUIDE.md]

ELABORATION BUDGET (per concept -- computed in Step 2.3b, see below):
[Insert the per-chapter elaboration budget table here: Concept | CIS | Tier | Target Words | Required Elements]

CONTENT GUIDELINES:
- Follow the per-concept word count and required-element targets in the
  Elaboration Budget table above -- do NOT apply a flat word count to every
  concept regardless of importance
- No more than 4 paragraphs of pure text without a non-text element
- Use diverse element types (lists, tables, diagrams, MicroSims)
- Present concepts in pedagogical order (simple to complex)
- Include LaTeX equations where appropriate (backslash delimiters: `\( \)` for inline, `\[ \]` for display)

SCAFFOLDING (CRITICAL):
- Define every technical term in prose BEFORE it appears in a diagram, code block, or table
- Before code examples, explain what the code does and what key parameters mean in plain language
- Tables must summarize concepts already explained — never introduce new concepts via tables
- Add bridging sentences before complex elements ("Before we examine this diagram, let's define...")

MASCOT (if a mascot is defined in CONTENT-GENERATION-GUIDE.md):
- The pose-by-pose rules, per-chapter counts, and hard limits are defined in the
  project's CONTENT-GENERATION-GUIDE.md (rendered from the canonical
  $BK_HOME/skills/book-installer/references/mascot-placement-rules.md). Read that
  section before placing any mascot admonition and follow it exactly.
- If you are processing CHAPTER 1, the FIRST mascot admonition must be the
  one-time self-introduction described in those rules. See Step 2.4 principle 4.
- For chapters 2 and beyond, open with a normal mascot-welcome admonition that gets straight into chapter-specific content. Do NOT repeat the self-introduction.

NON-TEXT ELEMENTS:
- Markdown lists and tables: embed directly (blank line before)
- Diagrams, MicroSims, infographics: use <details markdown="1"> blocks with #### Diagram: header

SPECIFICATIONS (read references/microsim-specification-rules.md first):
- Use the block template exactly: sim-id, Library, Status, Bloom Level, Bloom Verb and
  Learning Objective as separate bold header lines
- State WHAT the learner must learn and prove: Evidence of Mastery, Misconceptions,
  Instructional Rationale, complete Content (every item written out), Provenance, Rules, Learner Activity,
  Feedback, Starting State, Chapter Anchors
- Do NOT specify HOW to build it: no pixel sizes, layout, control placement, colors,
  breakpoints, library calls or "Implementation:" lines
- Run the self-check in that file on every specification before writing the chapter

CHAPTERS TO PROCESS:
[List specific chapter directories with full paths]

FOR EACH CHAPTER:
1. Read the chapter index.md file to get title, summary, and the "Concepts
   Covered" table (Concept | CIS Score)
2. Compute the Elaboration Budget for this chapter's concepts (Step 2.3b) --
   the chapter's total word count is the SUM of each concept's target, not
   a flat chapter-wide number. Chapters with more high-CIS concepts will
   naturally run longer than chapters of mostly narrow, low-CIS concepts --
   this is expected and correct, not an error to normalize away.
3. Generate content following each concept's individual word-count range
   and required-element targets from the budget table
4. Verify all concepts from "Concepts Covered" are addressed AND that each
   one's actual word count and element mix roughly matches its budget tier
5. Write the content to docs/chapters/[chapter-dir]/index.md

METADATA FORMAT (add to top of each file). Put double quotes around every value that contains a
colon, and always around title, description and date. An unquoted value with a colon is invalid YAML:
mkdocs then prints the frontmatter at the top of the page and drops its metadata, without failing
`mkdocs build --strict`. Escape any inner double quote as \".
---
title: "[Chapter Title]"
description: "[Short description]"
generated_by: claude skill chapter-content-generator
date: "[YYYY-MM-DD HH:MM:SS]"
version: 1.11
---

REPORT when done:
- Chapter name
- Word count (and how it compares to the sum of the concepts' budgeted targets)
- Non-text elements (lists, tables, admonitions, diagrams, MicroSims)
- Concepts covered (X of Y), with any concept whose actual length fell outside its budget's tolerance flagged

逐次実行

逐次モードの場合、または章が 4 章未満の場合は、以下の章ごとの手順に従い、一度に 1 章ずつ処理します。

フェーズ 2 の手順（章ごと — エージェントまたは逐次モードで使用）

Step 2.1: チャプターファイルの存在を確認する

チャプターファイルが存在し、必要な要素が含まれていることを確認します。

想定される入力形式：

• チャプター名："01-intro-to-itil-and-config-mgmt" または "Chapter 1"
• 完全なパス："/docs/chapters/01-intro-to-itil-and-config-mgmt/index.md"
• 相対パス："chapters/01-intro-to-itil-and-config-mgmt/index.md"

チャプターディレクトリの構成：

/docs/chapters/NN-lowercase-name/index.md

ここで：

• NN = 先頭にゼロを付けた2桁のチャプター番号（例："01"、"07"、"12"）
• lowercase-name = スペースを含まず、ハイフンで区切られた、URL に適した小文字の名前

並列エージェントの起動： ユーザーが並列実行をリクエストした場合にのみ行います。

Task ツールを複数回、1つのメッセージ内で呼び出して、エージェントを並列実行します。

[Call Task tool for Agent 1: Chapters 1-4]
[Call Task tool for Agent 2: Chapters 5-8]
[Call Task tool for Agent 3: Chapters 9-12]
[Call Task tool for Agent 4: Chapters 13-16]
[Call Task tool for Agent 5: Chapters 17-20]
[Call Task tool for Agent 6: Chapters 21-23]

重要： Task ツールの呼び出しはすべて、並列実行するために1つのメッセージ内にまとめる必要があります。別々のメッセージで送信した場合、順次実行されます。

Step 2.2: チャプターの概要を確認する

チャプターファイルを開き、必要な要素が含まれていることを確認します。

必要な要素：

1. ヘッダー1（# タイトル）のタイトル
2. レベル2のヘッダー（## Summary）にあるSummary
3. レベル2のヘッダー（## Concepts Covered）にあるConcepts Coveredと、Concept | CIS Score の Markdown テーブル（book-chapter-generator v1.0.0 以降で生成されます。Step 1.4a を参照）

操作：

1. チャプターの index.md ファイルを解析します
2. 以下を抽出します：
   • チャプタータイトル
   • Summary のテキスト
   • Concepts Covered の表：(concept_name, cis_score) のペアのリスト。行の順序は記載順（学習上の順序）を維持します
3. いずれかの要素が欠けている場合は、チャプターをスキップするか、ユーザーに内容の提供を依頼します
4. "Concepts Covered" が CIS スコアのない番号付きリスト（book-chapter-generator v1.0.0 より前に生成されたチャプター）の場合、CIS 値をでっち上げてはいけません。その旨をユーザーに報告し、現在の book-chapter-generator でチャプターのひな形を再生成するよう提案します
5. Elaboration Budget（Step 2.3b）および Step 2.5 での検証に備えて、概念／CIS のリストを保存します

Step 2.3: メタデータを追加する

index ファイルの先頭にメタデータを追加します：

---
title: "Chapter Title"
description: "Short description of title"
generated_by: claude skill chapter-content-generator
date: "YYYY-MM-DD HH:MM:SS"
version: 1.11
---

フロントマターのルール： コロンを含むフロントマターの値はすべて二重引用符で囲み、内部の二重引用符は \" としてエスケープします。title、description、date は必ず引用符で囲みます。タイトルや説明にはコロンがよく含まれ（"Kinematics: Where Is the Hand?" など）、タイムスタンプには必ず含まれるためです。引用符で囲まれていない description: A chapter on X: how Y works は無効な YAML です。その場合、mkdocs はページの先頭にフロントマターを表示してメタデータを破棄します。また、mkdocs build --strict でもエラーにならないため、問題を示すエラーがないままページが正しく表示されません。コロンを含むキー（og:image）を引用符で囲む必要はありません。引用符で囲むのは値だけです。チャプターを書き込んだ後、フロントマターが解析できることを確認します：

python3 -c "import sys,yaml; t=open(sys.argv[1]).read(); d=yaml.safe_load(t.split('---')[1]); print(d['title'], '|', d['date'])" docs/chapters/NN-name/index.md

これにより、date の値は YAML のタイムスタンプではなく文字列になります。これは後続のツールが想定している形式です。

ステップ 2.3b：詳細化予算を計算する（CIS に基づく）

このステップは、「1章あたり3000～5000語、テキスト以外の要素を4～6個」という従来の一律の指示に置き換わるものです。 コンテンツの長さや詳しさは章ごとではなく、概念ごとに設定します。各概念の Concept Impact Score（CIS）に基づき、多くの概念が推移的に依存する概念には十分な詳細化（具体例や図など）を施し、影響の小さい限定的な概念は効率よく簡潔に扱います。これは、人間の専門家が周辺的な用語よりも基礎的な考え方に多くの説明を費やすのと同じです。

1. 各概念の詳細化スコア E(c) を計算します。

import math

# cis_max was computed once in Step 1.3 across the WHOLE book -- reuse it
# here. Normalization is always GLOBAL, never local to this chapter: a
# concept's importance is a book-wide claim. (An earlier, chapter-local
# normalization was tried and rejected -- it produced a degenerate result
# where a chapter's own single most-important concept always looked like
# the book's most important concept, even when it wasn't.)
def elaboration_score(cis, cis_max):
    if cis_max <= 1:
        return 0.0
    return math.log(cis + 1) / math.log(cis_max + 1)

E(c) は [0, 1] の範囲です。生の CIS ではなく log(cis+1) を使うことが重要です。CIS は裾の重い分布になるため（一般的な約200概念のグラフでは、概念の約半数が最低値の CIS 1 に位置します）、線形スケールや母集団のパーセンタイルを使うと、下位半分の概念がすべて同じように扱われる一方で、1つか2つのハブ概念がスコアの範囲を支配してしまいます。この問題は開発中に実際に発見され、修正されました。詳細に関心がある場合は、「Predicting Concept Content Size」論文（定義4）を参照してください。

2. E(c) からティアを割り当てます。

ティア	E(c) の範囲	目標語数	必須要素
A（十分に詳しく扱う）	>= 0.5	500-750	>=1個の具体例 AND >=1個の図／チャート／表／MicroSim
B（標準）	0.2 <= E(c) < 0.5	250-400	>=1個の具体例
C（簡潔に扱う）	< 0.2	120-200	明確な定義。短い例は任意で、必須ではありません

これらの境界値と範囲は、開発中に CIS のプロファイルが正反対の実際の2つの章（基礎的な章と専門的な章）で検証した、妥当な出発点です。固定不変の値ではありません。実際の内容に対して章のティア構成が不自然な場合（例：すべての概念が同じティアになる場合）は、生成前にティア分けを確認してください。ただし、一律の章ごとの語数に暗黙に戻してはいけません。

3. 章の詳細化予算表を作成します（「扱う概念」と同じ教育上の順序で、概念ごとに1行）。

概念	CIS	E(c)	ティア	目標語数	必須要素
[概念 1]	187	0.83	A	500-750	具体例 + 図
[概念 2]	4	0.22	B	250-400	具体例
[概念 3]	1	0.00	C	120-200	定義

章の合計語数は、概念ごとの目標語数の合計です。個別に設定するものではありません。ティアAの概念を複数含む章は、ティアCの概念が中心の章より自然と長くなります。このばらつきこそが意図したものであり、均一化すべき問題ではありません（下記の「よくある落とし穴」を参照）。

4. この表を使ってステップ 2.4 を進めます。 文章を生成するときは、章全体の長さをすべての概念に均等に割り振るのではなく、概念ごとの予算行に従ってください。

ステップ 2.4：詳細な章のコンテンツを生成する

章のアウトライン、概念リスト、読解レベルに基づいて、包括的な教育コンテンツを生成します。

コンテンツ生成の原則：

1. 読解レベルへの適応：

   • 適切な文の複雑さ、語彙、説明スタイルを適用します
   • 具体的なガイドラインについては references/reading-levels.md を参照してください

2. 概念の順序：

   • 簡単な概念から提示し、複雑な概念は後にします
   • 自然な教育上の進行に従います
   • 「扱う概念」リストの順序に必ずしも従う必要はありません
   • 先に説明した概念を土台として構成します

3. 足場づくり — 表示する前に定義する：

   • ビジュアルより先に用語を説明する： 図、コード例、表の前には必ず、そこに含まれるすべての専門用語を定義する文章を置いてください。図に「ベクトル」や「埋め込み」が含まれる場合は、その用語を図の直前の段落で説明してください。読者がテキスト以外の要素で初めて用語に出会うことがないようにしてください。
   • コードの前に橋渡しの文を置く： コード例の前には必ず、コードの動作と主要なパラメーターの意味を平易な言葉で説明する文を置いてください。コードを先に示し、説明を後のセクションに回してはいけません。説明は必ず先に置いてください。例：「temperature パラメーターはランダム性を制御します（0 = 決定的、1 = 創造的）。max_tokens パラメーターは、応答の最大長を設定します。」
   • 先に文章で説明し、表で補強する： 表は、読者がすでに理解している情報を要約または比較するために使います。新しい概念を表で導入してはいけません。手順は、（1）文章で概念を説明し、（2）その後、概念を整理または比較する表を示す、です。読者が表のセルから意味を逆算する必要がある場合、その表を出すのは時期尚早です。
   • これから示す内容を案内する： 複雑な要素の前には、読み進めるための手がかりを加えてください。「この図を見る前に、2つの重要な用語を定義しましょう。」や「次の表は、先ほど説明した3つのアプローチをまとめたものです。」といった一文を添えることで、参照資料を、学びを導く内容にできます。

4. マスコットの配置（マスコットを定義している場合）：

   各ポーズが担う教育上の役割、章ごとに配置する各ポーズの数、厳守すべき上限、そして一度だけ行う第1章での自己紹介の形式は、このライブラリのすべてのスキルで共有される単一のファイルに定義されています。

   $BK_HOME/skills/book-installer/references/mascot-placement-rules.md
   

   各書籍には、そのルールをレンダリングしたコピーが、それぞれの CONTENT-GENERATION-GUIDE.md 内の `` センチネルの間に記載されています。マスコットの注意書きを配置する前に、そのセクションを読み、記載内容に厳密に従ってください。

   ここでルールを言い直したり、プロジェクトで定義されていないポーズの役割を作ったりしないでください。ルールを変更する必要がある場合は、すべてのスキルに変更が一度に反映されるよう、正規のファイルを変更してください。

   特に見落とされやすいため、次の2点を改めて示します。

   • 第1章での自己紹介は、マスコットが初めて登場する際の一度だけ行います。第2章以降は、章固有の内容にすぐ入る通常の mascot-welcome で始めてください。
   • マスコット画像は、注意書きの本文内に Markdown の画像構文 ![alt](path){ class="mascot-admonition-img" } を使って配置してください。生の HTML <img> タグは使わないでください。

5. テキスト以外の要素：

   • 各概念について、Elaboration Budget（Step 2.3b）の Required Elements 列に従ってください。Tier A の概念には、実例と図／チャート／表／MicroSim が必要です。Tier B には実例が必要です。Tier C では明確な定義のみが必要です。これらは概念ごとの最低要件であり、概念の構成とは無関係に章全体で満たすべき要素数ではありません。
   • 目標：テキストのみの段落が4段落を超えて続かないようにしてください。
   • 多様な要素タイプを使ってください（同じタイプを繰り返さないでください）。
   • インタラクティブ要素（インフォグラフィック、MicroSim）を特に重視してください。
   • 適切な場合は、バックスラッシュ区切りの LaTeX を使って数式を表示してください。
     • インライン数式：文中の数式には \( equation \) を使います。
     • ディスプレイ数式：独立した行に置く数式には \[ equation \] を使います。
   • ドル記号の区切り文字（$ または $$）は使わないでください。
   • 数式の適切な書式については、references 内の math-equations.md ファイルを参照してください。

テキスト以外の要素の種類：

Markdown に直接埋め込む要素（<details markdown="1"> ブロックは不要）：

1. Markdown リスト（箇条書きまたは番号付き）— リストの前には必ず空行を入れてください
2. Markdown 表— 表の前には必ず空行を入れてください

図のヘッダーと <details markdown="1"> 仕様ブロックが必要な要素： 3. 図表・作図 - システムアーキテクチャ、関係性、データフロー 4. インタラクティブなインフォグラフィック - クリック可能な概念マップ、段階的な情報開示、用語集に沿った定義がツールチップに表示されるホバー表示 5. MicroSim - インタラクティブなコントロールを備えた p5.js シミュレーション 6. グラフ - 定量データを示す棒グラフ、折れ線グラフ、円グラフ 7. タイムライン - 歴史的な変遷、連続する出来事 8. マップ - 移動を示す矢印を含む地理的な分布 9. ワークフロー図 - ホバーテキスト付きのビジネスプロセス 10. グラフデータモデル - vis-network を使用したエンティティの関係 11. 因果ループ図 - システム思考や因果関係の説明に使用

MicroSim の再利用チェック（新しいインタラクティブ要素の仕様を書く前に必須）：

dmccreary/* の教科書には、すでに何百もの MicroSim があり、search-microsims カタログにインデックス登録されています。MicroSim、ワークフロー図、グラフ、タイムライン、マップ、インフォグラフィックの SPECIFICATION ブロックを書く前に、既存のホスト済み MicroSim が同じ概念を教えているか確認してください。該当するものがあれば、ゼロから生成してデバッグする必要のある新しいものを仕様化する代わりに、iframe で埋め込んでください。

1. 利用可能か確認（セッションごとに1回）： 次を実行します。 test -x /Users/dan/Documents/ws/search-microsims/.venv-embeddings/bin/python && test -f /Users/dan/Documents/ws/search-microsims/data/microsims-embeddings.json && echo AVAILABLE AVAILABLE が出力されない場合は、セッション全体でこの再利用手順をスキップし、以下の説明どおりに仕様を生成してください。機能低下時も処理を継続し、検索サービスが章の生成を妨げないようにしてください。
2. 要素の WHAT クエリを下書きします。 埋め込みクエリの形式は次のとおりです。 Title: <working title> | Topic: <concept> | Subjects: <subject areas> | Grade Level: <level> | Learning Objectives: <objective with Bloom verb>
3. 再利用検索を実行します。

   /Users/dan/Documents/ws/search-microsims/.venv-embeddings/bin/python \
     /Users/dan/Documents/ws/search-microsims/src/find-similar-templates/find-similar-templates.py \
     --mode reuse --query "<WHAT query>" --top 3 --json --quiet
   

   コマンドでエラーが発生した場合、または約60秒を超えて時間がかかる場合は、セッションの残りの間、通常の仕様生成に切り替えてください。
4. 最上位の検索結果の recommendation フィールドを使って判断します。
   • reuse（WHAT スコア ≥ 0.75）：仕様の代わりに、以下の再利用ブロックを出力します。候補の grade_level と subject がこの書籍に適しているか、まず妥当性を確認してください。明らかに不適切な場合（例：中学校向けの書籍に大学院レベルのシミュレーションがある場合）は、template として扱います。docs/sims/<sim-id>/ がこの書籍内にすでに存在する場合は、相対パスの iframe を使ってローカルのシミュレーションを埋め込んでください。
   • template（0.60 ≤ WHAT スコア < 0.75）：通常の仕様を書き、details ブロックに次の1行を追加します。**Template:** <github_url of top match><br/> これにより microsim-generator は、既存のシミュレーションのコードを出発点として使用できます。
   • generate（WHAT スコア < 0.60）：通常どおり仕様を書きます。
5. 再利用の判断を記録します。 章の生成サマリーに、再利用数、テンプレートからの作成数、新規仕様作成数を記録します。

再利用ブロックの構造（再利用時は仕様の代わりに使用）：

#### Diagram: [Title of the existing MicroSim]

<iframe src="[fullscreen_url from the search result]" width="100%" height="500px" scrolling="no"></iframe>

[Run the [Title] MicroSim fullscreen]([fullscreen_url]){ .md-button }

<details markdown="1">
<summary>[Title] (reused MicroSim)</summary>
Type: [element-type]
**sim-id:** [sim directory name from the source repo]<br/>
**Library:** [framework from the search result]<br/>
**Status:** Reused<br/>
**Source:** [live_url from the search result]<br/>
**Source Repo:** [github_url from the search result]<br/>
**Bloom Level:** [Remember | Understand | Apply | Analyze | Evaluate | Create]<br/>
**Bloom Verb:** [one verb from that level's list]<br/>
**Learning Objective:** The learner will [verb] [the objective as used in this chapter].

Reused from the MicroSim catalog (WHAT match score [what_score]).
</details>

**Status:** Reused フィールドにより、後続のバッチツールはシミュレーションのスキャフォールディングや実装を試みなくなります。generate-todo.py は再利用された仕様を TODO.md から除外し、extract-sim-specs.py は完了として記録します。Reused はライフサイクルの最終状態です。再利用されたシミュレーションは、すでにソースリポジトリにデプロイされているため、specified → scaffolded → implemented → validated → deployed と進むことはありません。

新しい <details markdown="1"> 仕様を作成する際は、必ず最初に references/microsim-specification-rules.md を読み、そこにあるブロックをそのまま使用してください。

#### Diagram: [Title Case Name]

<details markdown="1">
<summary>[Title Case Name]</summary>
Type: [microsim | chart | diagram | infographic | timeline | map | workflow | graph-model | causal-loop]
**sim-id:** [kebab-case-directory-name]<br/>
**Library:** [p5.js | Chart.js | Plotly | Mermaid | vis-network | vis-timeline | Leaflet | venn.js | html]<br/>
**Status:** Specified<br/>
**Bloom Level:** [Remember | Understand | Apply | Analyze | Evaluate | Create]<br/>
**Bloom Verb:** [one verb from that level's list in references/blooms-taxonomy.md]<br/>
**Learning Objective:** The learner will [verb] [specific content] [condition or criterion].

**Prerequisites:** [terms the learner needs; each is defined in the prose above this block]

**Evidence of Mastery:** [the learner action that demonstrates the verb, and the rule that decides correct/incorrect]

**Misconceptions:** [wrong ideas the sim should expose and correct, or "none"]

**Instructional Rationale:** [why this kind of activity produces the evidence at this Bloom level]

**Content:** [every item, value, definition and label the learner sees, written out in full]

**Provenance:** [chapter section, file path or URL, synthetic with seed, or illustrative]

**Rules:** [formulas, thresholds with >= or >, ranges as min/max/step/default/unit, tie-breaks, edge cases]

**Learner Activity:** [numbered steps: what the learner does, what changes, what they should notice]

**Feedback:** [items, order, attempts, correctness rule, correct and incorrect messages, when answers are revealed]

**Starting State:** [what the learner sees first, and the question it poses]

**Chapter Anchors:** [every number, name and claim the chapter prose states about this sim, or "none"]
</details>

新しい仕様に iframe を追加しないでください。シミュレーションの構築後、microsim-generator が適切な高さで挿入します。

次の6つのヘッダー行は、バッチユーティリティ（extract-sim-specs.py、create-microsim-todo-json-files.py、generate-sim-scaffold.py）によって解析されます。

• sim-id — ケバブケースのディレクトリ名（例：angle-type-explorer）。docs/sims/<sim-id>/ に使用します
• Library — リストから選択する値。ジェネレーターのルートと CDN を選択します。「HTML and CSS」などの自由入力は認識されず、p5.js にフォールバックします
• Status — 新しい仕様では Specified、再利用チェックで既存の MicroSim と一致した場合は Reused（終端状態のため、バッチツールではスキップされます）
• Bloom Level と Bloom Verb — それぞれ別の行に、値のみを記載します（Analyze (L4) ではなく Analyze）
• Learning Objective — 1文で記載し、その後に空行を入れます

<details markdown="1"> ブロック内のテキストはインデントしないでください。<details markdown="1"> ブロック内の行頭にスペースやタブを入れないでください。

詳細の前に、必ず #### Diagram: というプレフィックスを付けたレベル4の見出しを入れてください。これは必須です！

仕様の要件（ルール全文、例、セルフチェックについては references/microsim-specification-rules.md を参照してください）：

• 目標を最初に記載します。 ブルーム動詞を1つ使った、測定可能な目標を1つ設定します。習得の証拠には、学習者のアクティビティで実際に可能な操作と、それが正解かどうかを判定するルールを記載します。
• コンテンツを完全に記載します。 学習者が目にする項目をすべて書き出します。「たとえば」「など」や「12枚のカード一式」と書いて4枚だけ示すことは避けてください。学習者が分類または回答する項目には、正解と、そのフィードバックとなる1文の理由を記載します。
• 出典を明記したコンテンツにします。 すべての事実値について、章のセクション、ファイルパスまたは URL、シード値を指定した合成データ、あるいは説明用データのいずれかを出典として明記します。シミュレーションでは、合成データと説明用データにラベルを付けてください。現実世界の事実（座標、日付、統計など）をジェネレーターに推測させないでください。
• 説明ではなくルールを記載します。 しきい値には >= または > を使います。調整可能な数値にはすべて最小値、最大値、刻み幅、デフォルト値、単位を指定し、デフォルト値は刻み幅に沿った値にします。
• 章との整合性を保ちます。 シミュレーションについて本文に記載するすべての数値は、Chapter Anchors にも同じ値で記載します。
• ビルド手順は記載しません。 ピクセルサイズ、キャンバスの高さ、レイアウト、コントロールの配置、ブレークポイント、色、フォント、ライブラリ呼び出し、および Implementation: の行は microsim-generator に任せます。ただし、教える内容そのものが視覚的な特性である場合は除きます。
• 各要素タイプの適性については references/content-element-types.md を参照してください。

コンテンツの構成：

1. 章の要約につながる導入段落から始めます
2. 概念を教育的な順序（簡単なものから複雑なものへ）で提示します
3. テキスト以外の要素を全体に自然に組み込みます
4. Markdown のリストと表を頻繁に使用します（その前には空行を入れてください）
5. 複雑な視覚要素やインタラクティブ要素には <details markdown="1"> ブロックを使用します
6. 各 details ブロックの前に、レベル4の Markdown 見出しを置きます #### Diagram: [Diagram Name]
7. End with summary or key takeaways section

Interactive elements emphasis:

CRITICAL: Every diagram, chart, infographic, MicroSim, timeline, map, workflow, and graph model MUST be interactive. NEVER specify a static image that does not give the learner feedback. At minimum, every visual element must support at least one of: clickable nodes/regions/bars that open an infobox, hoverable elements that reveal tooltips, or controls that change the rendered output. Mermaid diagrams are acceptable ONLY when every node has a click directive that reveals a definition or explanation in an infobox — a plain Mermaid diagram with no click handlers is a static image and is forbidden. If a candidate diagram cannot meet this bar, redesign it as a MicroSim, an interactive infographic, or a clickable Mermaid diagram — or cut it. See references/content-element-types.md "CRITICAL RULE: Every Visual Element Must Be Interactive" for the full specification.

• Prioritize MicroSims and infographics that enable:
  • Student interaction tracking
  • Progress gauging
  • Personalized content recommendations
• Each interactive element has exactly one Learning Objective, with its Bloom Level and Bloom Verb on separate header lines (see the template above)
• Choose the level from the 2001 Bloom Taxonomy:
  • Remembering: Recalling facts, terms, basic concepts, and answers without necessarily understanding their meaning.
  • Understanding: Explaining ideas or concepts, demonstrating comprehension by summarizing or rephrasing information.
  • Applying: Using acquired knowledge to solve problems in new or unfamiliar situations.
  • Analyzing: Breaking down information into parts to understand its structure and relationships, and drawing comparisons.
  • Evaluating: Making judgments about information based on set criteria or standards, requiring critical thinking and justification.
  • Creating: Producing new or original work by combining elements to form a novel whole or solution.
• For the per-level action-verb lists and detailed question-writing guidance, read the canonical reference references/blooms-taxonomy.md (also used by faq-generator and quiz-generator).

Step 2.5: Verify Completeness

After generating chapter content, verify all concepts have been covered.

Verification process:

1. Review the generated content
2. Check that each concept from "Concepts Covered" list appears in the content
3. Create a checklist showing which concepts were covered
4. If any concepts missing:
   • Add content covering those concepts
   • Integrate them naturally into existing structure
5. Update the chapter index.md file with the complete generated content
6. Make Absolutely Sure that the content has been written to the chapter index.md file. Do a word count to make sure that ALL the content is present and that the TODO has been removed.
7. Run the Self-Check in references/microsim-specification-rules.md on every specification block in the chapter and fix each failure. At minimum, confirm for each block:
   • the Bloom Level, Bloom Verb and Learning Objective lines are present and consistent
   • the Evidence of Mastery is possible with the described Learner Activity
   • every count in the spec matches the items listed in Content
   • every number matches the chapter prose
   • the block contains no pixel sizes, layout, colors or Implementation: line

Actions:

• Replace the "TODO: Generate Chapter Content" placeholder with generated content
• Keep the existing title, summary, concepts list, and prerequisites sections
• Add the new detailed content after the prerequisites section

Phase 3: Aggregation (Sequential, after parallel agents complete)

After all parallel agents complete, aggregate results.

Step 3.1: Collect Agent Results

Wait for all Task agents to complete. Collect from each:

• List of chapter files created/updated
• Per-chapter statistics (word count, non-text elements, concepts covered)
• Any errors or issues encountered

Step 3.2: Generate Summary Report

Create a summary of all content generation:

# Chapter Content Generation Report

Generated: YYYY-MM-DD
Execution Mode: Parallel (6 agents)
Wall-clock Time: X minutes Y seconds

## Overall Statistics

- **Total Chapters:** 23
- **Total Words:** ~100,000
- **Avg Words per Chapter:** ~4,350
- **Total Non-text Elements:** ~115

## Execution Summary (Parallel Mode)

| Agent | Chapters | Words | Elements | Time |
|-------|----------|-------|----------|------|
| Agent 1 | 1-4 | 17,200 | 20 | 3m 15s |
| Agent 2 | 5-8 | 18,100 | 22 | 3m 42s |
| Agent 3 | 9-12 | 17,800 | 19 | 3m 28s |
| Agent 4 | 13-16 | 18,500 | 21 | 3m 51s |
| Agent 5 | 17-20 | 17,900 | 18 | 3m 33s |
| Agent 6 | 21-23 | 13,200 | 15 | 2m 45s |

## Per-Chapter Summary

| Chapter | Words | Lists | Tables | Diagrams | MicroSims | Concepts |
|---------|-------|-------|--------|----------|-----------|----------|
| 1. Foundations | 4,200 | 6 | 3 | 2 | 1 | 15/15 ✓ |
| 2. Limits | 4,500 | 5 | 2 | 3 | 2 | 14/14 ✓ |
| ... | ... | ... | ... | ... | ... | ... |

ステップ 3.3：終了時刻を記録してセッションログを書き込む

終了時刻を記録します：

date "+%Y-%m-%d %H:%M:%S"

セッション情報を logs/chapter-content-generator-YYYY-MM-DD.md にエクスポートします：

# Chapter Content Generator Session Log

**Skill Version:** 1.11
**Date:** YYYY-MM-DD
**Execution Mode:** Parallel (6 agents)

## Timing

| Metric | Value |
|--------|-------|
| Start Time | YYYY-MM-DD HH:MM:SS |
| End Time | YYYY-MM-DD HH:MM:SS |
| Elapsed Time | X minutes Y seconds |

## Token Usage

| Phase | Estimated Tokens |
|-------|------------------|
| Setup (shared context) | ~20,000 |
| Agent 1 (Ch 1-4) | ~80,000 |
| Agent 2 (Ch 5-8) | ~80,000 |
| ... | ... |
| Aggregation | ~5,000 |
| **Total** | ~500,000 |

## Results

- Total chapters: N
- Total words: ~X
- All chapters written successfully: Yes/No

## Files Created/Updated

[List all chapter index.md files]

ステップ 3.4：ユーザーに通知する

ユーザーに通知します：

「Chapter Content Generator v1.11 が完了しました！

• モード： 並列（6エージェント）
• 経過時間： X分Y秒
• 処理した章： 23
• 合計語数： 約100,000
• テキスト以外の要素： 約115

すべての章のコンテンツを、それぞれの index.md ファイルに書き込みました。

セッションログを logs/chapter-content-generator-YYYY-MM-DD.md に記録しました」

リソース

このスキルには、コンテンツ生成の詳細なガイドラインを示す参考ファイルが含まれています。

references/content-element-types.md

テキスト以外のすべての要素タイプ（上記の3〜11）の包括的な仕様です。以下を含みます。

• 各要素タイプを使用する場面
• 仕様に必要な情報
• 実装方法
• <details markdown="1"> ブロック形式の仕様例
• 各 details 要素の前にレベル4の Diagram 見出しを配置

#### Diagram: [Diagram Name]

図、MicroSim、インフォグラフィック、チャート、タイムライン、マップ、ワークフロー、グラフモデルを適切に仕様化するため、コンテンツの生成時にこの参考資料を読み込んでください。

references/microsim-specification-rules.md

正確な仕様ブロックを記述するためのルールです。以下を含みます。

• 6つの機械可読なヘッダー行を含むブロックのテンプレート
• 各フィールドに1つずつ対応するルール R1–R14。それぞれ、防止する失敗と不適切な例・適切な例を示します
• microsim-generator に任せる内容（レイアウト、サイズ、色、ライブラリの呼び出し）
• Type/Library の表
• 章を仕上げる前に、すべてのブロックで実行するセルフチェック
• 完全な記述例

<details markdown="1"> 仕様を記述する前に、このリファレンスを読み込んでください。

references/reading-levels.md

さまざまな読解レベルに合わせてコンテンツを調整するための詳細なガイドラインです。以下を含みます。

• 文の構造と長さに関するガイドライン
• 語彙の選択
• 説明のスタイル
• 例の複雑さ
• 想定する背景知識
• 各レベルの例文

適切な読解レベルに合わせてコンテンツを記述する際に、このリファレンスを読み込んでください。

ベストプラクティス

1. 必ずリファレンスを読む： コンテンツを生成する前に、references/content-element-types.md、references/microsim-specification-rules.md、references/reading-levels.md を読み込みます

2. 空行を維持する： Markdown のリストと表の前には、必ず空行を入れます（MkDocs の要件）

3. 教育的な順序： 概念のリスト順に縛られず、最も効果的な順序で概念を教えます

4. 視覚的な多様性： 同じ種類を繰り返すのではなく、さまざまな種類のテキスト以外の要素を組み合わせます

5. インタラクティブな要素を重視： 学生のエンゲージメントを追跡できる MicroSim とインフォグラフィックを優先します

6. 正確な仕様： 各 <details markdown="1"> ブロックには、学習者が何を学ぶ必要があるか、またそれを教えるために必要な内容を漏れなく記述します。これにより、ジェネレーターが内容、ルール、フィードバックを創作する必要がなくなります。どのように作るかはジェネレーターに任せます。references/microsim-specification-rules.md を参照してください

7. 概念の統合： 概念を個別のトピックとして扱うのではなく、自然に織り交ぜます

8. 適切な深さ： 説明の深さを読解レベルに合わせます（中学生向けにはより多くの足場かけを、大学院生向けにはより多くの理論を用意します）

9. 足場かけ — 読む体験： リファレンス文書ではなく、ガイド付きチュートリアルとして読めるコンテンツを生成します。図、コードブロック、表など、テキスト以外の各要素は、その前にある文章を読んだ後の自然な成果として感じられるようにします。「学生が上から下へ順に読んだとき、各要素にたどり着くまでに、それを理解するための用語や背景を身につけているだろうか？」と問いかけます。そうでなければ、その要素の前に橋渡しとなる文章を加えます。

10. 検証： 「Concepts Covered」リストのすべての概念が生成されたコンテンツに含まれていることを必ず確認します

11. 一貫したスタイル： 章全体を通して、語り口、用語、視覚的なスタイルに一貫性を保ちます

12. 並列実行： 4章以上を処理する場合は、効率化のため必ず並列モードを使用します

13. 実際のタイムスタンプ： 合成データではなく、必ず実際のシステムタイムスタンプを使用します

14. 絵文字の節度： 絵文字は、章で教える比喩を表す場合に限って使用します。装飾的な絵文字は、教科書のマスコットや太字と定義を組み合わせた語彙の提示と競合するため、使用しないでください。Mayer の一貫性の原則によると、装飾的なビジュアルは、学生に親しみやすいと感じられる場合でも、測定可能な形で記憶の定着を低下させます。エンゲージメントと学習は同じではありません。

15. マスコットの配置： プロジェクトの CONTENT-GENERATION-GUIDE.md でマスコットが定義されている場合は、レンダリング後のマスコット配置ルール（ポーズの選択、章ごとの数、上限、Chapter 1 での一度限りの自己紹介）に厳密に従います。マスコットが定義されていない場合は、完全に省略します。Step 2.4 の原則 4 を参照してください。

避けるべきよくある落とし穴

依存関係の方向（最優先）：

• ❌ prereqs[edge['to']].add(edge['from']) で前提条件のマップを作成すること — すべての依存関係が逆転します
• ❌ エッジの方向の検証（ステップ 1.3a）を省略すること — 逆転したマップによって、不正な章が気付かれないまま生成されます
• ❌ 依存関係の違反があるのに、章の生成を続行すること（ステップ 1.3b）
• ✅ 常に prereqs[edge['from']].add(edge['to']) を使用します — from＝依存する側、to＝前提条件
• ✅ 続行する前に、基礎となる概念が正しいことを必ず確認します
• ✅ コンテンツを生成する前に、依存関係の違反が 0 件であることを必ず確認します

CIS に基づく詳細化予算（高優先度 — v1.09 の新機能）：

• ❌ CIS スコアに関係なく、章内のすべての概念に一律の単語数を適用すること
• ❌ E(c) を書籍全体の cis_max ではなく、この章の概念だけを対象に正規化すること（ステップ 1.3） — これは開発中に試され、結果が不適切なものになりました
• ❌ 章ごとの単語数の違いを平準化すべき誤差として扱うこと — Tier A の概念が複数ある章は、Tier C の概念が大半を占める章より長くなるべきです
• ❌ 「内容を充実させる」ためだけに、必須ではない図や MicroSim を Tier C の概念に追加すること、または執筆が進んでいるからといって Tier A の概念を定義だけで済ませること
• ✅ 各概念の単語数と必須要素は、章全体の平均ではなく、詳細化予算の行（ステップ 2.3b）に基づいて決まります
• ✅ cis_max はステップ 1.3 で書籍全体を対象に一度だけ計算し、すべての章で再利用します
• ✅ 章の実際の単語数は、一律の 3000〜5000 という範囲ではなく、予算目標の合計と比較して報告します

足場づくり（重要 — 読者の体験）：

• ❌ 図に、直前の本文で定義されていない用語（例：「ベクトル」「埋め込み」）が使われている
• ❌ コード例に、後のセクションでしか説明されないパラメーター（例：temperature、max_tokens）が含まれている
• ❌ 表で、本文ですでに説明した概念を要約するのではなく、新しい概念を紹介している
• ❌ つなぎの文（「この図を見る前に……」など）がないまま、複雑な要素が登場する
• ✅ テキスト以外の要素に出てくる技術用語はすべて、その直前の本文で定義されています
• ✅ コード例の前には、そのコードの動作とパラメーターの意味を平易な言葉で説明します
• ✅ 表は内容を補強し、整理するためのものです — 新しい概念を紹介してはいけません
• ✅ ナビゲーションの手がかり（「この図を見る前に、2 つの用語を定義しましょう」など）で、移行時に読者を案内します

マスコットの使用：

• ❌ 第 1 章の最初のマスコットの注意書きで自己紹介を省き、すぐに章の内容に入る
• ❌ 第 2 章以降でマスコットの自己紹介を繰り返す（自己紹介は第 1 章で一度だけにします）
• ❌ プロジェクトの CONTENT-GENERATION-GUIDE.md で定義されていないポーズの役割を考案する
• ❌ マスコットを単なる飾りとして扱う、またはレンダリング後のマスコット配置ルールで定められた上限を超えて配置する
• ✅ 第 1 章の最初のマスコットの注意書きでは、マスコットが担うすべてのポーズの役割を列挙して自己紹介します
• ✅ 第 2 章以降は、通常のマスコットによる歓迎から始め、すぐに内容に入ります
• ✅ マスコットの注意書きは間隔を空け、必要な場面で使います。飾りとして使ってはいけません

コンテンツの品質：

• ❌ テキスト以外の要素を挟まずに 4 段落を超える
• ❌ 同じ種類の要素を繰り返し使用する
• ❌ 「扱う概念」リストの概念が抜けている
• ❌ 読解レベルに対して内容が難しすぎる、または易しすぎる MicroSim の仕様（最優先事項 — v1.11 で追加）：
• ❌ Bloom レベルを目標文の中に記述する（Learning objective (Bloom level: X; verb: Y): ...）— バッチツールで解析できず、シミュレーションに「Create」のラベルが付けられます
• ❌ 動詞が「理解する」「学ぶ」「知る」「探る」のいずれかである目標、または複数の目標を組み合わせた目標
• ❌ 内容の種類を示すだけで、内容自体を提示しない（「たとえば、12 枚のカード……」「3 つのデータセット」「6 つの目標」）
• ❌ アクティビティで実証できない目標（選択肢が 3 つなのに設定レイヤーが 5 つある、「ノードの形状が 4 種類」とあるのに定義されているのは 3 種類）
• ❌ 項目数、試行ルール、正誤判定ルール、フィードバック文のいずれかがないクイズや確認問題
• ❌ しきい値を >= 0.95 ではなく「0.95 より大きい」と記述する、ステップまたは単位のない範囲、ステップ幅に合わないデフォルト値
• ❌ 仕様内の数値が章の本文と異なる（仕様では 12 種類、本文では 13 種類）
• ❌ レイアウト、ピクセルサイズ、キャンバスの高さ、色、コントロールの配置、ブレークポイント、ライブラリ呼び出しを指定する — これらが自己矛盾する仕様の大半を引き起こしています
• ❌ 埋め込みシミュレーションで Mermaid のエッジのクリック、Mermaid の <-- 矢印、マウスホイールでのズームを要求する
• ❌ 自由記述の Library 値（「HTML と CSS」、「すべてのノードにクリックディレクティブを付けた Mermaid」）
• ✅ **Bloom Level:**、**Bloom Verb:**、**Learning Objective:** をそれぞれ独立した行に記載する
• ✅ 正解と、各項目に対する 1 文の理由を含め、内容をすべて記述する
• ✅ すべての事実値に Provenance を付ける。合成データや例示用データにはその旨を明記する
• ✅ Evidence of Mastery、Feedback、Chapter Anchors を記入し、すべてのブロックでセルフチェックを実施する

書式設定：

• ❌ リストや表の前に空行がない
• ❌ <details> ブロック内の内容がインデントされている
• ❌ <details> ブロックの前に #### Diagram: ヘッダーがない
• ❌ 閉じタグ </details> がない
• ❌ コロンを含むフロントマター値を引用符で囲んでいない（description: Kinematics: where is the hand?、または date: 2026-10-07 08:49:36）
• ✅ コロンを含むフロントマター値はすべて、また title、description、date は常に二重引用符で囲む

並列実行：

• ❌ Task 呼び出しを別々のメッセージで送信する（逐次実行になります）
• ❌ 集約の前にすべてのエージェントの完了を待たない
• ❌ すべてのエージェントの統計を集約し忘れる
• ❌ 実際のタイムスタンプではなく、合成タイムスタンプを使用する

出力ファイルの概要

必須（章ごと）：

1. 章のコンテンツ：docs/chapters/[chapter-name]/index.md

推奨（全体集約）： 2. logs/chapter-content-generator-YYYY-MM-DD.md - 所要時間を含むセッションログ

任意： 3. 章ごとの統計をまとめた概要レポート

セッションの例

並列モード（デフォルト）

ユーザー：「すべての章のコンテンツを生成してください」

エージェント（このスキルを使用）：

1. 開始時刻を記録する
2. 「Chapter Content Generator Skill v1.11 を並列モードで実行しています」と通知する
3. 共通コンテキスト（コースの説明、学習グラフ、用語集、CONTENT-GENERATION-GUIDE.md）を読み込む
4. 読解レベルを判断する（例：高校生向け）
5. 章のディレクトリをスキャンし、コンテンツが必要な 23 章を見つける
6. バッチを計画する：エージェント 6 個、各エージェントが約 4 章を担当
7. 1 つのメッセージで Task エージェントを 6 個起動する（並列実行）
8. すべてのエージェントが完了するまで待機する
9. すべてのエージェントの結果を集約する
10. 終了時刻を記録する
11. セッションログを書き込む
12. 次のように報告する：「Chapter Content Generator v1.11 が完了しました！ モード：並列。所要時間：18 分 32 秒。章数：23。語数：約 100,000。」

順次モード

ユーザー：「第3章のみのコンテンツを生成してください」

エージェント（このスキルを使用）：

1. 共有コンテキストを読み込みます
2. 必須要素を含む第3章のファイルが存在することを確認します
3. 読解レベルを判断します
4. 各概念の CIS スコア（ステップ 2.3b）から詳細化予算を算出します。たとえば、Tier A が 4 個、Tier B が 6 個、Tier C が 5 個の概念で、この章の目標文字数は約 4,000 語になります
5. 各概念に割り当てられた個別の予算に従い、各 Tier に必要な要素を盛り込んでコンテンツを生成します
6. すべての概念が網羅され、おおむね割り当てられた文字数の範囲内であることを確認します
7. コンテンツを章の index.md に書き込みます
8. 次のように報告します：「第3章のコンテンツを生成しました。語数：4,050（予算：3,950）。要素：7。概念：15/15。」

レポートの例

✅ Chapter content generated successfully!

Chapter: 01-intro-to-itil-and-config-mgmt
Reading level: Graduate
Content length: ~3,500 words

Non-text elements:
- 6 markdown lists
- 3 markdown tables
- 2 diagrams (CMDB architecture, ITIL process flow)
- 1 interactive timeline (ITIL evolution)
- 1 MicroSim (Configuration drift simulator)
- 1 workflow diagram (Change management process)

Interactive elements: 2 (timeline, MicroSim)
Skills required: 2 (microsim-p5 for MicroSim, infographic-generator for timeline)

All 20 concepts covered: ✓

!!! Note 注意書きを機能させるには、mkdocs.yml で admonition と pymdownx.details を有効にする必要があります。