draft-docs

ドラフトドキュメント

レビュー後に公開するため、チュートリアル、ハウツー、リファレンス、または解説のドキュメントのドラフトを docs/drafts/ に生成します。これらは Diataxis の4つのタイプです。タイプの選択手順については、docs-style/references/diataxis-compass.md を参照してください。

引数

• トピックのプロンプト： ドキュメント化する内容の説明（例：「WebSocket APIをドキュメント化する」）
• --publish [file]： レビュー済みのドラフトを最終的な配置先に移動し、ナビゲーションを更新します

モード 1：ドラフトを生成する

トピックのプロンプトを指定して、draft-docs スキルを呼び出します。例：draft-docs "Document the authentication middleware"。

ステップ 0：コンテキストを収集する

入力を解析する前に、プロジェクトのコンテキストを収集します。

# Check for existing docs structure
ls -la docs/ 2>/dev/null || echo "No docs/ directory found"

# Identify documentation framework
ls docs/navigation.json docs/mint.json docs/docusaurus.config.js docs/mkdocs.yml 2>/dev/null | head -1

# Check for existing drafts
ls docs/drafts/*.md 2>/dev/null || echo "No existing drafts"

# Get recent code changes for context
git diff --name-only $(git merge-base HEAD main)..HEAD 2>/dev/null | head -20

記録する内容：

• ドキュメント構成：docs/ 内に存在するサブディレクトリ
• ナビゲーションシステム：navigation.json、mint.json、またはその他の設定ファイル
• 技術スタックの手がかり：変更されたファイルの拡張子とインポートから確認します
• 既存のドラフト：重複を避けるために確認します

ステップ 1：入力を解析する

プロンプトから次の情報を抽出します。

1. トピック： ドキュメント化する内容（例：「認証ミドルウェア」）
2. コンテンツのタイプ： キーワードから判定します。

キーワード	タイプ	スキル
"tutorial", "learn", "getting started", "first", "onboarding", "introduction", "build a/your"	チュートリアル	tutorial-docs
"how to", "guide", "steps", "configure", "set up"	ハウツー	howto-docs
"API", "reference", "parameters", "function", "endpoint"	リファレンス	reference-docs
"why", "how does it work", "concept", "background", "rationale", "design decision", "architecture", "trade-offs"	解説	explanation-docs

この4つのタイプは、Diátaxis フレームワークの4象限、すなわちチュートリアル（学習）、ハウツー（タスク）、リファレンス（情報）、解説（理解）に相当します。2つのコンパス質問、行動か認知か？習得か応用か？ を使って判断してください。詳細は docs-style/references/diataxis-compass.md を参照してください。次の2つの違いを理解すると、ほとんどの曖昧さを解消できます。

• チュートリアルとハウツーはいずれも行動の手順を示しますが、チュートリアルは必ず成功するレッスンを通じて初心者に教えるもの（学習）であるのに対し、ハウツーは知識のあるユーザーが実際の目標を達成できるよう導くもの（作業）です。読者が初めて製品を学んでいる場合はチュートリアル、すでに製品を知っていてタスクを完了したい場合はハウツーです。
• リファレンスと解説はいずれも理論的な知識を提供しますが、リファレンスはキーボードの前で参照する中立的な事実を記載し、解説はその場を離れて読むための理由や背景を論じます。意見、歴史、トレードオフを求める依頼は解説、権威ある仕様を求める依頼はリファレンスです。

曖昧な場合は、「実際に手を動かして学ぶチュートリアル、タスクを完了するためのハウツーガイド、技術情報を調べるリファレンスドキュメント、または概念の背景にある理由を理解するための解説の、どれを作成しますか？」と尋ねてください。

ステップ 2：スキルを読み込む

次の両方を必ず読み込みます。

1. docs-style - 基本的な執筆原則
2. 判定したタイプのスキル：
   • チュートリアルの場合は tutorial-docs
   • ハウツーの場合は howto-docs
   • リファレンスの場合は reference-docs
   • 解説の場合は explanation-docs

ステップ 3：コードを分析する

関連するコードをコードベースから検索します。

1. シンボル検索： トピックに一致する関数、クラス、型を探します
2. ファイル検索： 名前のパターンから関連ファイルを特定します
3. 参照検索： 使用例を探します

次の情報を収集します。

• 関数／メソッドのシグネチャ
• 型定義
• 既存のコメント／docstring
• テストやサンプルにおける使用パターン

ステップ 4：ドラフトを生成する

読み込んだスキルを適用して、ドキュメントを生成します。

チュートリアルドキュメントの場合：

• tutorial-docs テンプレートの構成に従います
• タイトルには読者が作成するものを記載します（「初めての X を作成する」）。学ぶ内容にはしません
• 一人称複数を使い、「このチュートリアルでは、〜します」のように、教師と学習者の語り口を保ちます
• 選択肢や代替案を設けず、明確な手順を 1 つ提示します
• 各ステップの後に、読者に見える内容を記載します（「〜が表示されます」）
• 説明は徹底的に最小限にし、「なぜ」については解説ドキュメントへのリンクを提示します

リファレンスドキュメントの場合：

• reference-docs テンプレートの構成に従います
• すべてのパラメーターを型とともに記載します
• 実際のコードを使った、完全で実行可能な例を含めます
• 関連するシンボルへのリンクを含む「関連項目」セクションを追加します

ハウツードキュメントの場合：

• howto-docs テンプレートの構成に従います
• タイトルは「方法」で始めます
• 具体的な前提条件を列挙します
• 1 つの操作ごとに手順を分けます
• 検証セクションを含めます

解説ドキュメントの場合：

• explanation-docs テンプレートの構成に従います
• タイトルはタスクではなく、概念の理解を軸にします（「X を理解する」）
• 読了後に読者が理解できる内容を冒頭で述べます
• 存在するものだけでなく、設計上の判断の「理由」を説明します
• トレードオフを率直に論じ、検討した代替案にも触れます
• キーボードから離れて読むことを想定し、読みやすい文章で記述します。実行する手順は含めません

ステップ 5：ドラフトを作成する

1. 出力先を作成します：

   • docs/drafts/{slug}.md
   • トピックからスラッグを作成します：「WebSocket API」→ websocket-api.md

2. ディレクトリが存在することを確認します：

   mkdir -p docs/drafts
   

3. ドラフトファイルを作成します（次のステップに進む前に、ファイルがディスク上にあることを確認する「ハードゲート」→「書き込みゲート」を参照してください）

4. ユーザーに報告します：

   ## Draft Created
   
   **File:** `docs/drafts/{slug}.md`
   **Type:** Tutorial | How-To | Reference | Explanation
   **Based on:** [list of analyzed symbols/files]
   
   ### Next Steps
   
   1. Review the draft for accuracy
   2. Add any missing context or examples
   3. When ready, publish by invoking the **draft-docs** skill with `--publish docs/drafts/{slug}.md`
   

ステップ 6：実行終了時の検証

ドラフトの生成が正常に完了したことを確認します。

# Confirm draft file exists
ls -la docs/drafts/{slug}.md

# Validate frontmatter (YAML header)
head -10 docs/drafts/{slug}.md | grep -E "^---$|^title:|^description:"

# Check markdown syntax (if markdownlint available)
markdownlint docs/drafts/{slug}.md 2>/dev/null || echo "markdownlint not available"

検証チェックリスト：

• ドラフトファイルが docs/drafts/{slug}.md に作成されている
• フロントマターに title と description が含まれている
• コンテンツの種類が検出された種類（チュートリアル、ハウツー、リファレンス、解説）と一致している
• コード例が完全で実行可能である（チュートリアル／ハウツー／リファレンス）。概念が実際の設計上の判断に基づいている（解説）
• チュートリアルのドラフトに単一の手順が示され、各ステップで目に見える「〜が表示されます」という結果が記載されている
• 分析したすべてのシンボルがドラフト内で参照されている

いずれかの検証に失敗した場合は、具体的な問題を報告し、再生成を提案します。

モード 2：ドラフトを公開する

--publish フラグを指定して draft-docs スキルを実行します。例：draft-docs --publish docs/drafts/websocket-api.md

ステップ 1：ドラフトを読む

ドラフトファイルを読み、次の情報を抽出します。

• タイトル
• コンテンツの種類（フロントマターまたは構成から判定）

ステップ 2：公開先を決定する

ユーザーにセクションを尋ねます。

Where should this document go?

1. **Tutorials** → `docs/tutorials/{slug}.md`
2. **API Reference** → `docs/api/{slug}.md`
3. **Guides** → `docs/guides/{slug}.md`
4. **How-To** → `docs/how-to/{slug}.md`
5. **Concepts / Explanation** → `docs/concepts/{slug}.md`
6. **Other** → Specify path

ステップ 3：ファイルを移動する

mv docs/drafts/{slug}.md {destination}/{slug}.md

ステップ 4：ナビゲーションを更新する

docs/navigation.json があるか確認し、ナビゲーションを更新します。

1. 現在の navigation.json を読み込みます
2. 適切なナビゲーショングループを探します
3. 新しいページ項目を追加します
4. 更新した navigation.json を書き込みます

更新例：

{
  "navigation": [
    {
      "group": "API Reference",
      "pages": [
        "api/existing-page",
        "api/websocket-api"
      ]
    }
  ]
}

ステップ 5：報告する

## Published

**From:** `docs/drafts/{slug}.md`
**To:** `{destination}/{slug}.md`
**Navigation:** Updated `docs/navigation.json`

The document is now live in your docs.

ステップ 6：実行終了時の検証

公開が正常に完了したことを確認します。

# Confirm file moved to destination
ls -la {destination}/{slug}.md

# Confirm draft removed
ls docs/drafts/{slug}.md 2>/dev/null && echo "WARNING: Draft still exists" || echo "Draft cleaned up"

# Verify navigation updated
grep -q "{slug}" docs/navigation.json && echo "Navigation includes new page" || echo "WARNING: Navigation may need manual update"

# Check markdown syntax at final location
markdownlint {destination}/{slug}.md 2>/dev/null || echo "markdownlint not available"

検証チェックリスト：

• ドキュメントが {destination}/{slug}.md に移動されている
• docs/drafts/ からドラフトが削除されている
• ナビゲーションファイルに新しいページ項目が追加されている
• ナビゲーション構造にリンク切れがない
• ドキュメントに想定される URL パスからアクセスできる

いずれかの検証に失敗した場合は、具体的な問題を報告し、解決手順を提案します。

コンテンツの種類の判定

チュートリアルの指標

• プロンプトに次の語句が含まれる：チュートリアル、学ぶ、利用開始、初めて、オンボーディング、入門、「〜を作成する」
• 対象は、その製品を初めて使う人が最初に成功体験を得ることです
• ユーザーが求めているのは、タスクの実行方法や情報の検索ではなく、手順に沿って実践しながら学ぶレッスンです

リファレンスの指標

• プロンプトに次の語句が含まれる：API、エンドポイント、関数、メソッド、クラス、型、パラメーター、戻り値
• 対象は、特定のシンボルまたはシンボルの集合です
• ユーザーが求めているのは、技術仕様です

ハウツーを示す指標

• プロンプトに、方法、ガイド、手順、設定、セットアップ、統合などが含まれている
• 対象がタスクまたはワークフローである
• ユーザーが手順に沿った説明を求めている

解説を示す指標

• プロンプトに、理由、仕組み、概念、背景、根拠、設計上の判断、アーキテクチャ、トレードオフなどが含まれている
• 対象が、読者が操作するものではなく、理解したい概念またはシステムである
• ユーザーが実行手順ではなく、キーボードから離れて読める背景や理由を求めている

ルール

• ドラフトごとに、必ず docs-style スキルを読み込んでください
• docs/drafts/ に生成してください。最終保存先に直接生成してはいけません
• タイトルと説明を含むフロントマターを追加してください
• 実際のコードベースに基づく現実的な例を使ってください
• 分析したシンボルをドラフトのメタデータに記載してください
• 公開時には既存のナビゲーション構造を維持してください
• 既存ファイルを上書きする前に確認してください

ハードゲート（順番に実行）

先に進まないでください。次のステップに進むには、それぞれの Pass を満たす必要があります。コマンドまたは明示的な成果物を使って確認してください。内部で確認しただけでは不十分です。

ドラフトを生成する（モード 1）

1. コンテキストゲート — Pass： ステップ 0 のコマンドを実行し（または同等の確認を行い）、具体的な結果を少なくとも 1 つ記録しています。例：docs/ の一覧の一部、または docs/ が存在せず作成する旨の明示的な記録。
2. 種類ゲート — Pass： キーワード表と 2 つの判断質問を使って、チュートリアル、ハウツー、リファレンス、解説のいずれかを決定しています。または、ユーザーが明示的に選択しています（引用または「ユーザーは……を選択した」という言い換え）。これが確定するまで、ステップ 3：コードを分析するに進んではいけません。
3. スキルゲート — Pass： 分析の前に、docs-style と種類別スキル（tutorial-docs、howto-docs、reference-docs、または explanation-docs）の両方を有効にしています。実行時には、「執筆ガイドラインを確認しました」ではなく、読み込んだ 2 つのスキルのパスを明記してください。
4. 書き込みゲート — Pass： ドラフトを書いた後、test -f docs/drafts/{slug}.md が成功する（または ls でファイルが表示される）必要があります。その後に限り、Draft Created ブロックを出力してください。

ドラフトを公開する（モード 2）

1. 保存先ゲート — Pass： ユーザーが保存先を選択しています（メニューから、または特定のパスを指定）。{destination} を完全なパスに解決してください。親ディレクトリが存在し（test -d "$(dirname "$path")" またはプロジェクトに適した確認）、かつユーザーの明示的な承認なしに既存ファイルを上書きしない場合に Pass となります。
2. 移動ゲート — Pass： mv の実行後、{destination}/{slug}.md にファイルが存在し（test -f）、該当する場合はナビゲーションの更新も適用済みです。これらが完了する前に Published と報告してはいけません。