@unlaxer/dde-toolkit 0.1.3 → 0.1.5

package/flows/quick.yaml

@@ -5,10 +5,17 @@ trigger_keywords: ["DDE して", "DDE", "ドキュメントレビュー", "用
 
 defaults:
   exclude_dirs: ["dde", "dge", "node_modules", ".git", ".claude"]
-  article_intent: educational   # educational / reference / deep-dive
+  article_intent: match_existing   # match_existing / educational / reference / deep-dive
+  # match_existing: 既存 glossary 記事が 1 件以上あればそのスタイルを踏襲。なければ educational にフォールバック
 
 workflow:
   steps:
+    - id: resume_check
+      display_name: "前回セッションの確認"
+      note: "dde/sessions/ の最新ファイルを読んで未完了の作業を検出。新規なら skip"
+    - id: scan_glossary
+      display_name: "既存 glossary をスキャン"
+      note: "docs/glossary/ の既存記事一覧を収集。相互リンク候補 + 抽出除外リストに使う"
     - id: select_docs
       display_name: "対象ドキュメント群を選択"
       mode: confirm
@@ -23,7 +30,7 @@ workflow:
     - id: article_intent
       display_name: "記事のインテント設定"
       mode: confirm
-      note: "educational / reference / deep-dive、または自由記述"
+      note: "match_existing（推奨）/ educational / reference / deep-dive、または自由記述"
     - id: extract
       display_name: "用語抽出（LLM）— 全レベル対象"
       actor: llm
@@ -46,6 +53,10 @@ must_rules:
     text: "抽出した用語を一覧テーブルで出力してからユーザーに確認"
   - id: choices
     text: "記事生成後に番号付き選択肢を提示（省略しない）"
+  - id: crosslink_existing_only
+    text: "「さらに学ぶために」は docs/glossary/ に実在するファイル + 同一バッチ生成記事のみリンク可。存在しないファイルへのリンク禁止"
+  - id: scan_glossary_first
+    text: "セッション開始時に docs/glossary/ をスキャンして既存記事リストを作る（抽出除外 + 相互リンク候補に使用）"
 
 extract:
   actor: llm
@@ -64,6 +75,7 @@ articleize:
     ja:   "<slug>.ja.md"
     both: "両ファイル生成。dictionary.yaml に en/ja キーで用語マッピングを追加"
   intents:
+    match_existing: "既存 glossary 記事を 1〜3 件サンプリングしてスタイル（構成・文体・分量・例え話の有無）を推定し、新規記事に踏襲。既存記事がなければ educational にフォールバック"
     educational: "読んだ人が背景・動機・仕組みごと理解できる記事。例え話・図・なぜ？を含む。分量は目的に従って自然に決める"
     reference:   "定義・使い方・例を簡潔に。調べたい人向けのクイックリファレンス"
     deep-dive:   "実装詳細・コード例・エッジケース・トレードオフまで網羅"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unlaxer/dde-toolkit",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Document Deficit Extraction — find what's not understood in your docs",
   "license": "MIT",
   "type": "module",

package/skills/dde-session.md

@@ -47,9 +47,44 @@ DDE toolkit v0.1.3 — Document Deficit Extraction
 
 ## 手順
 
-### Step 0: flow 読み込み
+### Step 0: 前回セッション確認 + 既存 glossary スキャン
+
+**0-A: flow 読み込み**
 `dde/flows/` の YAML、なければ `kit/flows/` の YAML を読む。
 
+**0-B: 前回セッション確認**
+`dde/sessions/` の最新ファイルを読む。未完了の作業（未生成の用語リスト等）があれば:
+
+```
+前回セッションが見つかりました（dde/sessions/2024-01-15_session.md）。
+未生成の用語: OAuth 2.0, リフレッシュトークン
+
+前回の続きから再開しますか？
+1. はい（前回の続きから）
+2. いいえ（最初から）
+```
+
+新規セッションの場合は skip。
+
+**0-C: 既存 glossary スキャン（MUST）**
+`docs/glossary/` の `.md` ファイル一覧を収集する。これを 2 つの目的に使う:
+
+1. **抽出除外リスト** — 既存記事がある用語は抽出対象から除外（Step 6）
+2. **相互リンク候補リスト** — 「さらに学ぶために」で使えるリンク一覧（Step 7）
+
+```
+既存 glossary: 12 記事
+  jwt.md, oauth2.md, session-management.md, ...
+→ これらの用語は抽出対象から除外
+→ 「さらに学ぶために」のリンク候補として使用
+```
+
+ファイルが存在しない場合は空リストで OK（新規プロジェクト）。
+
+**CRITICAL RULE — 相互リンク**:
+「さらに学ぶために」に書くリンクは、**記事生成時点で `docs/glossary/` に実在するファイルのみ**。
+存在しないファイルへのリンクは絶対に書かない。同一バッチで新規生成する記事同士は相互リンク可。
+
 ### Step 1: 対象ドキュメント群の選択（MUST: ユーザーに確認）
 
 プロジェクト内の `.md` ファイルを列挙する。
@@ -107,6 +142,25 @@ DDE toolkit v0.1.3 — Document Deficit Extraction
 
 **文字数ではなく「読んだ人にどうなってほしいか」で指定する。**
 
+Step 0-C で既存 glossary 記事が見つかった場合は、まずそのスタイルを分析して選択肢に追加する。
+
+**既存記事がある場合の表示例:**
+```
+既存 glossary のスタイルを分析しました:
+  → educational narrative（例え話・ASCIIダイアグラム・相互リンクあり）
+
+記事のインテントを選んでください:
+1. 既存に合わせる（推奨）— 既存記事のスタイル・分量・構成を踏襲
+2. educational — 背景・動機・仕組みごと理解できる記事
+                 例え話・図・なぜ？を含む。分量は目的に従って自然に決まる
+3. reference   — 定義と使い方を簡潔に。調べたい人向け
+4. deep-dive   — 実装詳細・コード例・エッジケースまで網羅
+5. 自由記述    — 例: 「新入社員が読んで業務背景ごと理解できるように」
+
+デフォルト: 1（既存に合わせる）
+```
+
+**既存記事がない場合の表示例:**
 ```
 記事のインテントを選んでください:
 1. educational — 背景・動機・仕組みごと理解できる記事
@@ -118,6 +172,13 @@ DDE toolkit v0.1.3 — Document Deficit Extraction
 デフォルト: educational
 ```
 
+**「既存に合わせる」を選んだ場合:**
+既存記事を 1〜3 件サンプリングして以下を推定し、新規記事に適用する:
+- セクション構成（見出しの種類・順序）
+- 文体（ですます / だ・である、日本語 / 英語混在度）
+- 分量感（短め / 中程度 / 詳細）
+- 例え話・図の有無
+
 ### Step 6: 用語抽出（LLM）
 
 **レベルで絞らず、誰かが分からない可能性がある用語を全て抽出する。**
@@ -125,7 +186,7 @@ DDE toolkit v0.1.3 — Document Deficit Extraction
 対象ドキュメント群を読んで用語を一括抽出する。
 
 **抽出ルール:**
-- `docs/glossary/` に既存記事があるものは除外
+- `docs/glossary/` に既存記事があるものは除外（Step 0-C で収集したリストを使う）
 - 固有名詞（プロダクト名・企業名）は除外
 - コードブロック内の識別子は除外
 - 重要度: その用語なしでは内容が理解できない → 🔴 High / 補足があると助かる → 🟡 Medium
@@ -187,6 +248,12 @@ N 件抽出しました。記事を生成しますか？
 - [関連用語B](<相対パス>) — この文脈でなぜ関連するか1行で
 ```
 
+**「さらに学ぶために」のリンクルール（CRITICAL）:**
+- Step 0-C で収集した既存 glossary ファイル一覧のみを使う
+- 同一バッチで今回新たに生成する記事同士も相互リンク可（生成後に存在するため）
+- 存在しないファイルへのリンクは絶対に書かない（dead link 防止）
+- 候補がない場合はセクションを省略するか「（現在リンク先なし）」と明記する
+
 **reference intent の場合:**
 ```markdown
 # <用語>

package/version.txt

@@ -1 +1 @@
-0.1.3
+0.1.5