tutorial

ランタイム設定（ステップ 0 — 処理を開始する前）

ドメイン固有の動作を設定するため、次のファイルを読み込みます。

1. ops/derivation-manifest.md — 用語の対応、プラットフォームに関するヒント

   • メモフォルダー名には vocabulary.notes を使用します
   • メモの種類への言及には vocabulary.note / vocabulary.note_plural を使用します
   • 抽出を表す動詞には vocabulary.reduce を使用します
   • 関連付けを見つける動詞には vocabulary.reflect を使用します
   • MOC への言及には vocabulary.topic_map を使用します
   • 受信トレイフォルダー名には vocabulary.inbox を使用します

2. ops/config.yaml — 処理の深さ、ドメインコンテキスト

これらのファイルが存在しない場合は、汎用のデフォルトを使用します。

今すぐ実行

対象：$ARGUMENTS

• ops/tutorial-state.yaml が存在し、current_step <= 5 の場合：保存されたステップから再開します
• 対象が「reset」の場合：ops/tutorial-state.yaml を削除し、最初から開始します
• 状態ファイルが存在しない場合：トラックの選択から新しいチュートリアルを開始します

今すぐ開始してください。 以下の内容で進行します。

---

再開の検出

ops/tutorial-state.yaml を読み込みます。ファイルが存在し、チュートリアルが未完了の場合は、次を表示します。

--=={ ars contexta : tutorial }==--

  Welcome back.
  Track: [track]     [step-progress] Step [N] of 5
  Resuming where you left off...

保存された current_step に進みます。トラックを再度尋ねてはいけません。current_step > 5 の場合、チュートリアルは完了です。リセットするかどうかを尋ねます。

進捗インジケーターの形式：

• ステップ 1 / 5：[=> ]
• ステップ 2 / 5：[==> ]
• ステップ 3 / 5：[===> ]
• ステップ 4 / 5：[====> ]
• ステップ 5 / 5：[=====>]

トラックの選択（新しいチュートリアルのみ）

見出しを表示してから、AskUserQuestion を使用します。

--=={ ars contexta : tutorial }==--

Which track fits your work best?

  (a) Researcher -- academic papers, domain
      research, literature processing

  (b) Manager -- meeting notes, strategy docs,
      decision tracking

  (c) Personal -- daily observations, goal
      setting, reflective journaling

回答を待ちます。a/b/c を researcher/manager/personal に対応付けます。

初期状態を ops/tutorial-state.yaml に書き込みます。

track: [researcher|manager|personal]
current_step: 1
completed_steps: []
started: [ISO 8601 UTC]
last_activity: [ISO 8601 UTC]

---

ステップの実行パターン

すべてのステップは WHY / DO / SEE に従います。各ステップの前に進捗バーを表示します。各ステップの後、ops/tutorial-state.yaml を更新します（completed_steps に追加し、current_step を増やし、last_activity を更新します）。

トラック適応の参照

各ステップでは、選択されたトラックに合わせて言葉遣いと例を調整します。構成は同じですが、内容は異なります。

ステップ	研究者	マネージャー	個人
記録	論文の主張	会議での決定	ある一日に得た気づき
発見	論文間のつながり	決定と関係者のつながり	観察と目標のパターン
処理	論文からの抽出	会議メモの採掘	ジャーナルの結晶化
維持	古くなった主張、切れた引用	孤立した決定	つながりのない振り返り
振り返り	研究グラフの成長	組織の記憶	自己理解のパターン

---

ステップ 1：記録 — 最初の {vocabulary.note} を作成する

理由：

--=={ ars contexta : tutorial }==--
  [=>    ] Step 1 of 5 -- Capture

  Everything starts with a thought worth keeping.

トラックに合わせて考え方を調整します：

トラック	理由の説明
researcher	「覚えておく価値のある何かに気づいたとき、研究は始まります。論文の主張、複数の研究に共通するパターン、まだ問われていない問いなどです。このシステムは、これらを文章形式のタイトルとして記録します。それぞれのタイトルは、ほかのメモとリンクしたときに自然に読める命題です。」
manager	「優れた意思決定は、観察したことを記録するところから始まります。会議で見つけたパターン、関係者の懸念、戦略的な洞察などです。このシステムは、それらをつながりのあるメモに変換します。各タイトルは、「Q3 の計画」のようなラベルではなく、「Q3 の進捗はコンテキストスイッチを減らすことにかかっている」のような、完結した考えです。」
personal	「成長は、気づくことから始まります。散歩中の発見、1 週間の中で見つけたパターン、大切なものは何かという問いなどです。このシステムは、それらを文章形式のメモとして記録します。それぞれのタイトルは、「朝の習慣が効果的なのは、意思決定の疲労を減らすから」のように、あなたが心から信じていることです。」

実行：

トラックに合わせたプロンプトで AskUserQuestion を使用します：

トラック	プロンプト
researcher	「研究で得た主張、観察、問いを共有してください。覚えておき、さらに深めたいと心から思うことを、1 文でお願いします。」
manager	「仕事での意思決定、パターン、洞察を共有してください。会議やプロジェクトを通じて追跡する価値のあることを、1 文でお願いします。」
personal	「考え、観察、気づきを共有してください。覚えておきたいと心から思うことを、1 文でお願いします。」

入力を実際の {vocabulary.note} に変換します：

1. 入力を文章形式のタイトルのファイル名に変換します（小文字、安全な文字、完全な文）
2. YAML フロントマターを作成します：

   ---
   description: [adds context beyond the title — scope, mechanism, or implication]
   topics: ["[[index]]"]
   created: [today's date]
   ---
   

3. 考えを掘り下げる 2～3 文を書きます
4. ハブの {vocabulary.topic_map} へリンクする Topics フッターを追加します
5. ファイルを {vocabulary.notes}/ に書き込みます

確認：

  Note created:
    {vocabulary.notes}/[filename].md

  Title: [the prose title]
  Description: [the description]
  Topics: [[index]]

  Notice how the title works as prose:
    "Since [[your note title]], the question
     becomes..."

  That is what makes notes linkable. The title
  IS the thought, expressed as a sentence.

状態を更新してから、ステップ 2 に進みます。

---

ステップ 2：発見 — つながりを見つける

理由：

--=={ ars contexta : tutorial }==--
  [==>   ] Step 2 of 5 -- Discover

  A note alone is a file. Notes that connect
  become a knowledge graph.

トラックに合わせて調整します：

トラック	理由の説明
研究者	「主張がつながると、研究の知識は積み重なります。方法論に関する発見は、ツールに関する発見を発展させるかもしれません。ある研究のパターンは、別の研究のパターンと矛盾するかもしれません。洞察が生まれるのは、個々の論文の中ではなく、アイデア同士の関係の中です。」
マネージャー	「意思決定がつながると、組織の知識は積み重なります。採用の判断は、人員体制への懸念に関係するかもしれません。戦略の転換は、複数のプロジェクトに影響します。つながりから、個々の選択の背後にある仕組みが見えてきます。」
個人	「観察がつながると、自己理解は深まります。朝の習慣についての気づきは、エネルギーのパターンと関係するかもしれません。人間関係についての観察は、コミュニケーションに関する気づきを発展させるかもしれません。つながりから、自分が実際に何を信じているのかが見えてきます。」

実行：

トラックに合わせたプロンプトで AskUserQuestion を使用します：

トラック	プロンプト
研究者	「2つ目の研究上の洞察を共有してください。できれば最初のノートにつながるものが理想ですが、実際の主張であればどのようなものでもかまいません。」
マネージャー	「もう1つ仕事上の観察を共有してください。できれば最初の内容に関係するものが理想ですが、実際の洞察であればどのようなものでもかまいません。」
個人	「もう1つ考えを共有してください。できれば最初の内容につながるものが理想ですが、実際の観察であればどのようなものでもかまいません。」

2つ目の {vocabulary.note} を作成します。その後、最初の {vocabulary.note} とのつながりを探します：

1. 両方の {vocabulary.note_plural} を読みます
2. 明確化テストを行います：「[[note A]] は [具体的な理由] により [[note B]] とつながっている」と完成させられますか？
3. 本当につながりがある場合：
   • 片方または両方の {vocabulary.note_plural} にインラインの wiki リンクを追加します
   • 文脈を説明する語句とともに relevant_notes エントリーを追加します
4. 本当につながりがない場合：
   • 無理につながりを作ることは、つながりがないことより悪いと説明します
   • 「これらのノートはまだつながっていませんが、それで問題ありません。グラフは時間とともに成長します。」

確認：

つながっている場合：

  Note created and connected:
    {vocabulary.notes}/[filename].md

  Connection:
    [[note A]] connects to [[note B]]
    because [your articulated reason]

  This is what /reflect does at scale --
  finding genuine connections across your
  entire graph.

つながっていない場合：

  Note created:
    {vocabulary.notes}/[filename].md

  No genuine connection to your first note.
  That is fine -- forced connections pollute
  the graph. Real connections emerge as your
  graph grows.

状態を更新してから、ステップ 3 に進みます。

---

ステップ 3：処理 — 構造化された知識を抽出する

理由：

--=={ ars contexta : tutorial }==--
  [===>  ] Step 3 of 5 -- Process

  Raw material becomes structured knowledge
  through extraction. You mine for atomic
  insights, not summaries.

トラックに合わせて調整します：

トラック	理由の説明
研究者	「1本の論文には数多くの主張が含まれていますが、研究にとって重要なのはその一部だけです。抽出とは、残す価値のある命題、つまり具体的な主張、方法論上の選択、意外な発見を見極め、それぞれを独立したノートにすることです。これが /{reduce} の実践です。」
マネージャー	「議事録や戦略文書には、埋もれた洞察が含まれています。抽出とは、意思決定、前提、リスク要因を見つけ、それぞれを追跡し、つなげられる独立したノートにすることです。これが /{reduce} の実践です。」
個人	「日記や日々のノートには、まだ整理されていない観察が含まれています。抽出とは、洞察、パターン、真の気づきを見つけ、それぞれをほかのすべてとともに積み重なっていくノートにまとめることです。これが /{reduce} の実践です。」

実行：

トラックに合わせたプロンプトで AskUserQuestion を使用します：

トラック	プロンプト
研究者	「元となる資料の短い段落を貼り付けてください。論文のメモ、記事の抜粋、研究上の観察などが該当します。2〜5文で十分です。」
マネージャー	「元となる資料の短い段落を貼り付けてください。議事録、戦略の抜粋、プロジェクトに関する観察などが該当します。2〜5文で十分です。」
個人	「元となる資料の短い段落を貼り付けてください。日記、会話のメモ、日々の観察などが該当します。2〜5文で十分です。」

原子的な洞察を1〜2個抽出します：

1. 残す価値のある命題を特定します（要約や事務的な情報ではありません）
2. 選別します。会話だけの内容、一時的な事務情報、曖昧な観察は省きます
3. 既存のチュートリアル用 {vocabulary.note_plural} とのつながりを確認します
4. 適切なスキーマで {vocabulary.note} を作成します
5. 実際につながりがある場合はリンクします

確認：

  Extracted [N] insight(s) from your material:

  1. [title of extracted note]
     [connection status: linked to [[note]] | standalone]

  Raw material -> atomic {vocabulary.note_plural} -> connected graph.
  This is what /{reduce} does. It finds the
  propositions worth keeping and turns each into
  a composable {vocabulary.note}.

抽出する価値のあるものがない場合：

  No atomic insights found in this material.
  That happens — not everything contains
  extractable propositions. The selectivity
  gate is working: better to skip than to
  create low-value {vocabulary.note_plural}.

状態を更新してから、ステップ 4 に進みます。

---

ステップ 4：維持 — Vault の健全性を確認する

WHY：

--=={ ars contexta : tutorial }==--
  [====> ] Step 4 of 5 -- Maintain

  A knowledge system that is not maintained
  decays. Health checks catch problems before
  they compound.

トラックに合わせて調整します。

トラック	WHY の説明
researcher	「引用が切れ、主張が古くなり、ノート同士のつながりが失われると、リサーチグラフは劣化します。健全性チェックにより、孤立した主張、説明のないノート、壊れたリンクを、リサーチの信頼性が損なわれる前に見つけられます。」
manager	「意思決定が孤立し、リンクが切れ、ノートの文脈が失われると、組織のナレッジは劣化します。健全性チェックにより、組織の記憶が損なわれる前にこれらを見つけられます。」
personal	「振り返りが切り離され、説明が曖昧になり、パターンが見落とされると、個人のナレッジは劣化します。健全性チェックにより、洞察が失われる前にこれらを見つけられます。」

DO：

AskUserQuestion は使いません。チュートリアルの {vocabulary.note_plural} に対して、自動で簡易健全性チェックを実行します。

1. 説明のチェック： すべての {vocabulary.note} に説明フィールドがありますか？ その説明にはタイトル以外の情報が含まれていますか？
2. リンクのチェック： すべての Wiki リンクが既存のファイルを参照していますか？
3. {vocabulary.topic_map} のチェック： すべての {vocabulary.note} が、少なくとも 1 つの {vocabulary.topic_map} の Topics フッターに記載されていますか？
4. 孤立のチェック： 被リンクが 0 件の {vocabulary.note} はありますか？
5. 接続密度： {vocabulary.note} あたりの Wiki リンク数はいくつですか？

各チェックについて、具体的な内容とともに PASS または WARN を報告します。

SEE：

  Health check on your [N] tutorial {vocabulary.note_plural}:

  | Check              | Status | Detail              |
  |--------------------|--------|---------------------|
  | Descriptions       | PASS   | All notes described |
  | Links              | PASS   | No broken links     |
  | {vocabulary.topic_map} membership | WARN   | [note] not in MOC   |
  | Orphan risk        | PASS   | All notes connected |
  | Connection density | PASS   | Avg [N] links/note  |

  This is what /health does at scale. It catches
  problems automatically so the graph stays
  healthy as it grows.

警告が見つかった場合は、自動で修正し（不足している {vocabulary.topic_map} へのリンクを追加する、説明を改善するなど）、修正内容を説明します。

状態を更新してから、ステップ 5 に進みます。

---

ステップ 5：振り返る — 作成したものを確認する

WHY：

--=={ ars contexta : tutorial }==--
  [=====>] Step 5 of 5 -- Reflect

  Step back and see the system you started
  building. A few notes are a beginning.
  The question is what comes next.

トラックに合わせて調整します。

トラック	WHY の説明
researcher	「リサーチグラフの基盤ができました。処理する論文、抽出する主張、見つけるつながりが増えるたびに、グラフの価値も高まります。蓄積効果により、100 件目のノートは 1 件目よりも価値があります。99 件のつながりが生まれる可能性があるからです。」
manager	「組織の記憶の基盤ができました。処理する会議、記録する意思決定、見つけるつながりが増えるたびに、システムの価値も高まります。組織のナレッジは人々の頭の中だけにとどまらず、グラフの中に蓄積されるようになります。」
personal	「自己理解システムの基盤ができました。記録する観察、名付けるパターン、見つけるつながりが増えるたびに、システムの価値も高まります。今日の気分だけではなく、積み重ねられた証拠を通して自分自身を捉えられるようになります。」

DO：

Vault の状態の概要を表示します。

  What you built:

  {vocabulary.note_plural}: [N]
  Connections: [M] wiki links
  {vocabulary.topic_map_plural}: linked to [[index]]

  Your graph so far:
    [[note 1]] ----> [[note 2]]
         \               |
          '-> [[note 3]] -'

（チュートリアルの {vocabulary.note_plural} 間の実際のつながりを示す、シンプルな ASCII グラフです。）

次に、方法論への理解を示します。

Your system also knows about itself:
  ops/methodology/   Your system's self-knowledge
  /ask [question]    Ask the research behind your
                     system's design

Try: /ask "why does my system use [relevant feature]?"

その後、AskUserQuestion を使います。

「次に何に取り組みますか？ たとえば、次のことができます。\n\n (a) さらに考えを記録する（そのまま伝えてください）\n (b) 未加工の素材を処理する（/{reduce} [貼り付けまたはファイル]）\n (c) システムを探索する（/next）\n (d) 特定のコマンドについて詳しく学ぶ（/help [command]）」

ここから実際の利用に移行します。返答を処理せず、選択を確認して適切な方法を案内するだけにします。

SEE：

--=={ ars contexta : tutorial }==--

  [======] Complete

  You built a working knowledge graph in five
  steps. Every {vocabulary.note} you add from here
  compounds the value of what already exists.

  Quick reference:
    /ask [question]     Query your graph
    /learn [topic]      Research and grow
    /{reduce} [source]  Extract insights
    /{reflect}          Find connections
    /health             Check system health
    /next               What to do next
    /help               Full command guide

---

完了

ステップ 5 の後、最終状態を書き込みます。

track: [track]
current_step: 6
completed_steps: [1, 2, 3, 4, 5]
started: [original timestamp]
last_activity: [now]
completed: [now]

状態の永続化

各ステップの後、必ず ops/tutorial-state.yaml に書き込みます。これは必須です。チュートリアルをセッションをまたいで再開できるようにする必要があります。

形式：

track: [researcher|manager|personal]
current_step: [1-6, where 6 = complete]
completed_steps: [array of completed step numbers]
started: [ISO 8601 UTC]
last_activity: [ISO 8601 UTC]
completed: [ISO 8601 UTC, only when done]

セッション開始時の連携： 状態が存在し、未完了の場合、セッション開始フックで次のメッセージを表示します。「未完了のチュートリアルがあります（5 ステップ中 N ステップ目）。/tutorial で再開してください。」

品質原則

実践しながら学びます。 どのステップでも、ボルトに実際のコンテンツが作成されます。仮定上の例はありません。チュートリアル中に作成される {vocabulary.note_plural} は、今後のコンテンツとともに蓄積される実際の {vocabulary.note_plural} です。

方法よりも理由を先に説明します。 どのステップでも、ユーザーに何かをしてもらう前に、なぜそれが重要なのかを説明します。動機を理解すれば、チュートリアルが単なるチェックリストのように感じられるのを防げます。

無理に作らず、誠実に。 ユーザーの入力から意味のあるつながりが生まれない場合は、そのように伝えます。チュートリアルを成功したように見せるために、つながりをでっち上げてはいけません。つながりがあるときと、ないときについて誠実に伝えることで、適切なメンタルモデルを身につけられます。

トラックに合わせて調整し、トラックに縛られない。 トラックによって変わるのは例や表現であり、構成ではありません。研究者も個人ユーザーも、異なる枠組みで同じ5つのステップを進めます。

段階的に複雑さを高めます。 ステップ1はとても簡単です（考えを共有する）。ステップ5ではシステムを理解している必要があります。各ステップは前のステップを土台に進みます。チュートリアルでまだ説明されていない知識が必要なステップはありません。

エッジケース

ステップ3でユーザーが何も貼り付けない場合： ユーザーのトラックに合った、あらかじめ用意した例文を提示します。「抽出の仕組みを確認できるよう、サンプルをご用意しました。」

ユーザーがステップをスキップしたい場合： スキップを許可します。ステップを完了ではなくスキップとして記録するよう、状態を更新します。チュートリアルを関門のように感じさせてはいけません。

完了後にユーザーが /tutorial を再実行した場合： 完了状況を表示し、リセットを提案します。「チュートリアルは完了しています。最初からやり直すには /tutorial reset を実行してください。」

ユーザーの入力が短すぎる場合（単語1つなど）： やさしく内容を膨らませるよう促します。「完全な文になるよう、もう少し詳しく説明してもらえますか？システムは具体的な考えを表す文があると、より適切に動作します。たとえば、「会議」ではなく、「アクションアイテムを記録しないと、週次会議の価値が薄れてしまう」のように書いてみてください。」