write-feature-docs

write-feature-docs

新しい Warp 機能のドキュメントページを作成します。機能仕様を読み、コードベースを自分で調査して技術的な主張を検証し、エンジニアとコンテンツ設計プランを確認してから、アウトラインを確認し、その後に完全な MDX ドラフトを作成して、warpdotdev/docs でドラフト PR を開き、レビュー担当としてドキュメントチームをタグ付けします。

エンジニアの役割は、仕様とコードから確認できなかった内容を確認することです。正確性を全面的にレビューしたり、文章を推敲したり、ドキュメントの慣例を把握したりすることではありません。

ワークフロー

1. 仕様ファイルを見つけて読む
2. コードベースを調査して技術的な主張を検証する — エンジニアに確認してもらう内容を最小限にする
3. コンテンツ設計プランを提示し、確認を待つ — ページの対象読者
4. アウトラインを提示し、確認を待つ — ページに含める内容
5. 完全な MDX ドラフトを生成する 5.5. （利用可能な場合）コンピューター操作でスクリーンショットの撮影を試みる
6. warpdotdev/docs でドラフト PR を開き、ドキュメントチームをタグ付けする

ステップ 3 と 4 は、順番に行う別々の確認です。アウトラインはプランから導き出されます。プランによってコンテンツの種類が決まり、コンテンツの種類によってアウトラインのセクションが決まります。両方を同時に提示すると、エンジニアが合意していない対象読者を前提に作られたアウトラインを見せることになり、その上位の問いを考え直す代わりに、具体的なアウトラインに意識が引き寄せられてしまいます。まずページの対象読者を決めてから、ページに含める内容を決めてください。

---

ステップ 1：仕様を見つけて読む

エンジニアが仕様 ID を提示していない場合は、確認してください。仕様 ID は次のいずれかです。

• Linear チケット番号：APP-1234、REMOTE-1234、QUALITY-408
• GitHub issue（gh- を接頭辞として付ける）：gh-4567
• 短いケバブケースの機能名：vertical-tabs-hover-sidecar

仕様ファイルは次の場所を確認してください。

• specs/<id>/PRODUCT.md — 主な情報源：ユーザー向けの動作、その内容と理由
• specs/<id>/TECH.md — 副次的な情報源：実装、データモデル

両方のファイルがある場合は、両方を読んでください。ドキュメントの内容を作成する際は、PRODUCT.md を主な指針とします。

TECH.md を読む場合： その内容を取り入れる前に、データベーススキーマ、内部サービス名、非公開 API エンドポイント、機密性の高いサーバーアーキテクチャなど、内部実装の詳細と思われる内容を特定してください。これらの項目をエンジニアに提示し、公開ドキュメントに含めても安全なものと、内部情報として扱うべきものを確認してください。機密と明記された内容はドラフトに含めないでください。

この確認が必要なため、このスキルではエンジニアの参加が必須です。無人で進める方法はありません。公開しても安全だと判断する担当者がいない場合、TECH.md の内容をドラフトに含めることはできません。

どちらのファイルも存在しない場合は、仕様なしの場合の代替手順 に進んでください。

---

ステップ 2：コードベースを調査する

プランやアウトラインを提示する前に、GitHub CLI を使って技術的な内容をできる限り自分で検証してください。これにより、エンジニアへの確認事項を、コードから本当に判断できない内容だけに絞れます。 コードで確認する項目：

• 機能フラグ名：仕様書のタイトルまたはチケットから安全な機能トークンを検索します。シェルを使用する前に、^[A-Za-z0-9][A-Za-z0-9_-]*$ に一致する許可リスト対象のトークンに変換してください。安全に生成できない場合はシェルでの検索をスキップし、その後、FEATURE_TOKEN="<validated-token>" && gh search code "${FEATURE_TOKEN}" --repo warpdotdev/warp-internal を実行します。
• UI 文字列：仕様書に記載された、ユーザーに表示されるボタンのラベル、メニュー項目名、設定名を検索します
• 設定パス：設定メニューの正確なパスを確認します（例：**Settings** > **AI** > **Knowledge**）
• 仕様書に記載された CLI コマンドまたはキーボードショートカット
• 関連機能：「関連ページ」で相互参照している他の機能を特定します
• タグ付けするエンジニア：仕様書の担当エンジニアの GitHub ハンドルを特定します。
  • 対話モード：gh api user --jq .login を実行して、このスキルを現在実行しているユーザーのハンドルを取得します。スキルが仕様書の作成者によって直接呼び出されている場合に限り使用してください。ドキュメントチームのメンバーまたは作成者以外が実行している場合は、代わりに以下の特定手順を使用します。
  • 作成者以外による実行（ドキュメントチームのメンバー、または仕様書を作成していないユーザー）：検索コマンドを実行する前に、仕様書 ID に英数字とハイフンのみが含まれていること（^[A-Za-z0-9][A-Za-z0-9-]*$ に一致すること）を確認します。仕様書 ID にそれ以外の文字が含まれている場合は、検索をすべてスキップし、プレースホルダーとして [TODO: tag spec author] を使用します。仕様書 ID が有効な場合は SPEC_ID に代入し、ハンドルが見つかった時点で終了して、以下の手順を順番に進めます。
    1. コミットメッセージの Co-authored-by: トレーラーを確認する — warp-internal のようにプライベートなソースからミラーしているリポジトリでは、同期ボットがコミット作成者になっていますが、実際の作成者は Co-authored-by: トレーラーに記載されています。ボット以外の最初のエントリーを抽出します。

       git log --follow -1 --format="%B" -- "specs/${SPEC_ID}/PRODUCT.md" \
         | grep -i "^Co-authored-by:" \
         | grep -v "\[bot\]" \
         | head -1 \
         | grep -oP '<[^>]+>' | tr -d '<>'
       

       これによりメールアドレスが返されます（GitHub の noreply アドレスの場合があります）。メールアドレスが <userid>+<username>@users.noreply.github.com の形式に一致する場合は、ハンドルを直接抽出します：echo "$EMAIL" | grep -oP '\+\K[^@]+'。実際のメールアドレスの場合は、gh api "search/users?q=${EMAIL}+in:email" --jq '.items[0].login' で検索します。
    2. 同期元の PR URL を解析する — 同期ボットによって、コミット本文に元の PR URL が埋め込まれることがあります（例：Synced from warp: https://github.com/warpdotdev/warp/pull/11901）。URL を抽出して、PR の作成者を取得します。

       ORIG_PR=$(git log --follow -1 --format="%B" -- "specs/${SPEC_ID}/PRODUCT.md" \
         | grep -oP 'https://github\.com/[^/]+/[^/]+/pull/\d+' | head -1)
       # owner/repo と PR 番号を抽出し、次を実行します：gh pr view <N> --repo <owner/repo> --json author --jq '.author.login'
       

    3. 同期元リポジトリの PR を検索する — 実際にコードを管理しているリポジトリを検索します（アクセス可能な場合は、公開ミラーとプライベートソースの両方を確認します）。

       gh pr list --search "specs/${SPEC_ID}" --repo warpdotdev/warp-internal --state merged --json author --limit 1 --jq '.[0].author.login'
       # 次も試します：gh pr list --search "specs/${SPEC_ID}" --repo warpdotdev/warp --state merged --json author --limit 1 --jq '.[0].author.login'
       

       ログイン名に [bot] が含まれる結果はスキップします。
    4. コミット作成者のメールアドレスをフォールバックとして使用する — メールアドレスに [bot] が含まれない場合に限ります。

       EMAIL=$(git log --follow -1 --pretty=format:"%ae" -- "specs/${SPEC_ID}/PRODUCT.md")
       

       ${EMAIL} が空でなく、ボットのアドレスでない場合は、gh api "search/users?q=${EMAIL}+in:email" --jq '.items[0].login' でハンドルを検索します。
    5. すべての手順でハンドルが見つからなかった場合は、PR 本文のプレースホルダーとして [TODO: tag spec author] を使用します。 コードから検証した各主張には、確認済みのマークを付けてください。検証できない主張（コードに含まれない UI の挙動、製品の意図、未リリース機能の挙動）については、アウトライン内で [UNVERIFIED] としてフラグを立ててください。エンジニアが注目すべきなのは、これらの項目だけです。

---

ステップ 3: コンテンツデザインプランを提示して待つ

これは 2 回ある確認のうちの 1 回目であり、アウトラインより前に来ます。 何を載せるかを決める前に、まずそのページが誰に向けたものかを確定させてください。

docs リポジトリの .agents/templates/content-design-plan.md に記入し、各フィールドが何を求めているかについては .agents/references/content-design-plan.md を参照してください。対象読者と JTBD、課題、目標、目的と価値、コンテンツタイプ、スキルとテンプレート、そして高インパクトなシナリオと明示的な除外項目です。

これをターミナルに出力し、次のように伝えます:

「ページのアウトラインを作成する前に、これが正しい読者であり、正しいジョブであることを確認してください。ずれている点があれば修正するか、『問題ありません』と言っていただければ、アウトラインの下書きを作成します。」

エンジニアの返信を待ちます。 同じメッセージでアウトラインを出さないでください。プランがコンテンツタイプを決め、コンテンツタイプがアウトラインのセクション構成を決めます。確定していないプランと一緒にアウトラインを見せると、エンジニアは目の前にある具体的なセクションに引きずられ、その上にある読者の妥当性を疑わなくなってしまいます。

対象読者、コンテンツタイプ、スコープが変更された場合は、プランを修正し、先に進む前に再確認してください。確定したプランはステップ 6 の PR 本文に引き継いでください。

---

ステップ 4: アウトラインを提示して待つ

ステップ 3 で確定したプランに基づいて、簡潔なアウトラインを生成します（文章は不要）。アウトラインには、リサーチから確認できたことと、エンジニアの入力がまだ必要な項目を正確に示します。

アウトラインを次の形式でターミナルに出力します:

📄 Docs outline for [Feature name]

PROPOSED PLACEMENT
  Section:  src/content/docs/<section>/   (e.g., agent-platform/cloud-agents/)
  File:     <feature-name>.mdx
  URL:      docs.warp.dev/<path>/<feature-name>

CONTENT SECTIONS
  title:  <Feature name>   (frontmatter; Starlight renders it as the H1)
  Opening paragraph: [1-sentence description of what you'll write]
  ## Key features — [which 2-4 capabilities to highlight as bullets]
  ## How it works — [the conceptual model: what and why, no steps]
  ## <Usage section title> — [e.g., "Creating environments", "Configuring X"]
      Prerequisites: [any prerequisites to list]
      Steps:
        1. [Step description]
        2. [Step description]
        3. [Step description]
        ...
  ## Related pages — [cross-links to suggest]

上記のセクションはデフォルトです。アウトラインは機能に合わせて調整してください。機能に概念的な説明が不要であれば ## How it works を省略し、機能に異なるワークフローがあれば使用方法のセクションを複数追加し、機能が十分にシンプルであれば ## Key features を冒頭の段落にまとめてください。

VERIFIED FROM CODEBASE ✅
  - [e.g., "Feature flag: `my_feature_flag` confirmed in warp-internal"]
  - [e.g., "Settings path: confirmed as Settings > AI > Agents > Permissions"]

NEEDS YOUR CONFIRMATION ⚠️
  - [e.g., "Step 3 — does the sync trigger automatically or require a manual action?"]
  - [e.g., "Is the 'Export' button visible before the feature flag is enabled?"]

アウトラインを出力した後、次のように伝えます:

「コードベースから確認できる範囲は検証しました。上記の ⚠️ が付いた項目を確認し、修正があれば返信するか、『問題ありません』と言っていただければ続行します。」

続行する前にエンジニアの返信を待ちます。フィードバックを取り込んでから、下書きを作成します。

フィードバックがステップ 3 で確定したプランと矛盾する場合（異なる読者、異なるコンテンツタイプ）、両者がずれないようにプランも修正してください。プランは PR 本文に引き継がれるため、古いプランはレビュアーを誤導します。

---

ステップ 5: MDX ドラフトを生成する

確定したアウトラインに基づいて、完全な .mdx ファイルを生成します。出力は warpdotdev/docs にそのまま投入できる状態にします。

テンプレート構成

プランが選択したコンテンツタイプに対応する正規のテンプレートを、docs リポジトリの .agents/templates/ から使用してください — feature-doc.md、conceptual.md、procedural.md、reference.md、troubleshooting.md、quickstart.md、または guide-page.md です。これらが信頼できる情報源であり、フィールドごとのガイダンスも含まれています。以下のスケッチは、最も一般的なもの（機能ドキュメント）の形を示して、何を期待すべきかが分かるようにするためのものです。実際のテンプレートを読む代わりにはなりません。

テンプレートが徹底していて、記憶から書くと間違えやすい 2 つのルールがあります。ページタイトルは本文の H1 ではなく frontmatter に置くこと（Starlight は frontmatter のタイトルを H1 としてレンダリングするため、本文の H1 はそれを重複させます）、そして、角括弧で囲まれた指示はすべて、ページを公開する前に削除することです。

---
title: [Feature name — sentence case]
description: >-
  [1-2 sentence standalone summary. Lead with the user benefit. Include the
  feature name and a key term or two so it works as a search result snippet.]
---

[Opening paragraph: what the feature does and its primary benefit.
1-3 sentences. Lead with what the user can accomplish, not the implementation.]

:::note
[Optional: key context the reader needs upfront — a prerequisite, a limitation,
or when NOT to use this feature. Delete this callout if nothing applies.]
:::

## Key features

* **Feature A** - What it does and why it matters to the user.
* **Feature B** - What it does and why it matters to the user.

## How it works

[CONCEPTUAL section: explain system behavior, data flow, or architecture.
Answer "what" and "why" before "how." Define any new terms when they
first appear. Do NOT include step-by-step procedures in this section —
keep conceptual and procedural content clearly separated.]

## [Usage section title]

[PROCEDURAL section: motivate the task first, then give numbered steps.
Briefly explain why the user is doing this before telling them how.]

### Prerequisites

* **[Prerequisite]** - What it is and where to get it. See [full reference](link-here).

### [Task name — sentence case, e.g., "Create an environment with the CLI"]

1. First step. Expected outcome if not obvious.
2. Second step.
3. Third step.

## Related pages

* [Related feature](../path/to/page.md)
* [Deeper guide](../path/to/guide.md)

スタイルルール — 正確に適用する

これらの規約は Warp ドキュメントのスタイルガイドに由来し、必ず従う必要があります:

見出し

• すべての見出しはセンテンスケース: 最初の単語と固有名詞の機能名のみを大文字にする
• 固有名詞の機能名は大文字を維持する: 「Agent Mode」、「Warp Drive」、「Oz」、「Command Palette」
• ✅ ## How it works — ❌ ## How It Works
• ✅ ## Agent Mode settings — ❌ ## Agent mode settings

リスト

• 太字の用語 + ダッシュ + 説明: * **Term** - Description
• コロンは決して使わない: ❌ * **Term**: Description

UI 要素とパス

• ボタン、リンク、メニュー項目は太字: Click **Save**、Click `Save` ではない
• 設定パスの各セグメントは太字にし、> はプレーンなままにする: **Settings** > **AI** > **Knowledge**

ボイスとトーン

• 二人称: 「you can」、「allows you to」
• 能動態: 「Warp indexes your codebase」 — 「your codebase is indexed」ではない
• 「simple」、「easy」、「just」は避ける — これらは読者の体験を軽視します
• 仕組みの説明には現在形、指示には命令形

フロントマターの説明

• 検索結果のスニペットとして機能する、独立した要約として書く
• ユーザーのメリットを先頭に置き、機能名と主要な用語を含める
• ✅ Environments ensure your cloud agents run with a consistent toolchain. Learn when to use environments and how to configure them.
• ❌ This page describes environments.

コールアウト構文 (Astro Starlight)

• :::note — 補足的なコンテキスト、ヒント
• :::caution — 注意事項、制限
• :::danger — 破壊的または不可逆的な操作
• :::tip — 役立つヒントとベストプラクティス

[TODO: docs reviewer — ...] プレースホルダーのまま残すもの

• computer use が品質基準を満たさない、利用できない、または機能がまだ出荷されていない場合のスクリーンショット
• 動画/GIF の埋め込み
• 機能がまだ出荷されていない場合の正確な設定パス
• 最終的な URL パス (配置はドキュメントチームが確認)
• エンジニアの確認後も未検証のままだった動作

---

Step 5.5: computer use によるスクリーンショットのキャプチャ (利用可能な場合)

ドラフトを生成した後、computer use を使用して [TODO: docs reviewer — screenshot needed] プレースホルダーのスクリーンショットのキャプチャを試みます。このステップは 任意 です — computer_use ツールが利用可能な場合にのみ実行してください。computer use が利用できない場合は、すべてのプレースホルダーをそのままにしておきます。

どのスクリーンショットを試みるかを決める

以下の すべて に当てはまる場合にのみ、スクリーンショットを試みてください:

• 機能がすでに出荷されている (フィーチャーフラグの背後にない、または未リリースでない)
• UI の状態にプログラムで確実にナビゲートできる
• プレースホルダーが具体的な UI サーフェスを指定している (「機能が動作している様子を見せる」のような曖昧なものではない)

アカウント固有の状態、特定のデータ、または機密情報を露出するコンテンツを必要とするスクリーンショットはスキップしてください。

キャプチャ前のセットアップ

スクリーンショットを撮る前に:

1. 一貫したウィンドウサイズで Warp を起動します (起動のガイダンスには warp-internal-computer-use スキルを使用してください)
2. 該当する UI サーフェスにナビゲートするか、該当する機能の状態をトリガーします
3. すべてのアニメーションが完了し、UI が完全に落ち着くまで 待ちます
4. ドキュメント化する機能の一部ではない、無関係なポップアップ、通知、トーストを閉じます
5. このスクリーンショットに関係のないサイドバーパネルやペインを閉じます
6. 機密データが表示されていないことを確認します: トークン、API キー、プライベートリポジトリ名、顧客ワークスペースのデータ、メールアドレス、個人情報がないかチェックしてください。表示されている場合は、スクリーンショットを撮らないでください。

キャプチャの手順：予測 → キャプチャ → 検証 → 1 回だけ再試行

これは、構造化された自己検証ループです。省略しないでください。状態の誤り、切り抜き範囲の誤り、フレーミングの誤りを防ぐための主な対策です。

手順 1：キャプチャ前に期待する内容を明示する

スクリーンショットを撮る前に、何が表示されると予想するかを書き出します。

CAPTURE EXPECTATION
  Subject:            [The specific UI element or surface being documented]
  Expected elements:  [2-3 specific things that MUST be visible — e.g. a panel title, a button, a specific setting]
  Expected state:     [The UI state — e.g. "Settings panel open", "Modal visible", "Feature active and showing output"]
  Must not contain:   [Anything that must NOT be visible — e.g. sensitive data, unrelated popups, loading spinners]

手順 2：キャプチャする

スクリーンショットを撮ります。

手順 3：表示して、期待する内容と照合する

コンピューター操作を使ってキャプチャした画像を表示し、期待する内容と照合します。

• 記載した対象が表示され、明確に焦点になっていますか？
• 期待する要素がすべて表示されていますか？
• UI は期待する状態ですか（遷移中や読み込み中ではありませんか）？
• 含めてはならないものが表示されていませんか？
• 目標とする表示幅でテキストは読みやすいですか？

すべて問題なければ → 品質チェックに進みます。

いずれかに問題があれば → もう一度だけ試します。UI の状態に再度移動し、UI が落ち着くまで長めに待ってから再キャプチャし、もう一度検証します。

2 回目も問題があれば → スクリーンショットを破棄し、[TODO: docs reviewer — screenshot] のプレースホルダーを残します。検証できないスクリーンショットは含めないでください。

手順 4：品質チェック — 掲載前の最終確認

• スクリーンショット内のテキストは、目標とする表示サイズで読みやすい
• 説明対象の UI 要素が明確に焦点になっている — 埋もれていたり、切り取られていたり、隠れていたりしない
• 機密データ（トークン、非公開リポジトリ、個人情報、顧客データ）が表示されていない
• UI は安定した読み込み完了状態 — スピナー、スケルトンスクリーン、遷移中の状態がない
• スクリーンショットは、キャプチャ前に示した期待する内容と一致している
• 目標とする表示幅でレンダリングしたとき、ぼやけたり大きすぎたりせず、自然に見える

いずれかの項目に問題があれば、スクリーンショットを破棄し、[TODO: docs reviewer — screenshot] のプレースホルダーを残します。

スクリーンショットごとの試行回数の上限：2 回。 どちらも失敗した場合は、次に進みます。

サイズ — 最も近い標準幅を選ぶ

• 全幅（デフォルト） — ウィンドウ全体のキャプチャ、製品画面全体、周囲の文脈が重要なレイアウト
• 約 375px — ポップオーバー、コマンドメニュー、サイドペイン、ドロップダウン、操作に焦点を当てたフローなど、幅の狭い UI 画面
• 約 300～350px — 余分な部分をきつく切り抜いたコントロール、チップ、ボタン、ツールチップ、小さなメニュー

サイズを調整する前に、不要な余白を切り抜きます。同じセクション内にある一連のスクリーンショットは、同じ幅にそろえます。

配置 — MDX 内でスクリーンショットを挿入する場所

各スクリーンショットは、次の場所に挿入します。

• UI または表示される状態を紹介する段落の直後
• 設定手順の近く — ユーザーが選択する設定パネルやメニューを示します
• 状態や結果の説明の近く — 成功を認識するのに役立つ完了状態や出力を示します
• ビジュアル機能ページの冒頭 — 早い段階で全体像を示すスクリーンショットを使用します

手順の各ステップにスクリーンショットを追加しないでください。画像が理解を本当に助ける場合にのみ追加します。

MDX 形式

<figure>
  <img
    src="[relative path from this MDX file to src/assets/<section>/<feature-name>-<ui-state>.png — count the directory depth of the MDX file and use that many ../ levels; e.g. 3 levels deep → ../../../assets/<section>/...]"
    alt="[Descriptive alt text: what the image shows, not just 'screenshot']"
  />
  <figcaption>[Caption: complete sentence, ≤10 words, orient don’t instruct, no marketing language, sentence case, ends with period.]</figcaption>
</figure>

代替テキストのルール：

• 単に「スクリーンショット」とするのではなく、画像に何が表示されているかを説明します
• ✅ alt="Agent permissions settings with 'Always allow' selected for file reads"
• ❌ alt="screenshot" または alt=""

キャプションのルール：

• 読者が内容を把握できるように、操作方法ではなく、表示されているものを説明します
• 完全な文にします。できれば 10 語以内、最大でも約 20 語までにします
• マーケティング的な表現は使いません（「簡単に」「素早く」「強力な」「一目で」などは避けます）
• 本文の内容を繰り返さないでください。キャプションは内容を補足するものであり、繰り返すものではありません
• 表示されているすべてを列挙せず、対象を示します
• ✅ <figcaption>The Environments page in the Oz web app.</figcaption>
• ❌ <figcaption>Click the toast to jump to the agent’s session.</figcaption>（手順の説明です。本文に記載してください）

ファイル名： 小文字、ハイフン区切り、内容がわかる名前にします。例：agent-mode-permissions-panel.png

ファイルの場所： PNG は warpdotdev/docs 内の src/assets/<section>/ に保存します（Astro が自動的に最適化します）。

---

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

PR を作成する前に、ドキュメントリポジトリ独自の要件が満たされていることを確認してください。 warpdotdev/docs では、追加されるページに対して 2 つの条件を設けており、これらを満たさない PR は差し戻されます。

1. ドキュメントリポジトリの .agents/references/docs-worthiness-criteria.md にある ゲート 0：その機能はリリース済みで、一般提供されており、公開されているサーフェスにありますか？そうでない場合は、PR を作成せず、その理由をエンジニアに伝えて作業を中止してください。エンジニアからページの作成を依頼された場合でも、これは確認する価値があります。未リリースの機能についてドラフトを作成することが最もよくある失敗であり、作業に近いエンジニアは、ユーザーよりもリリースが一歩先に進んでいることが簡単にあるためです。

   このリファレンスにある残りのゲートは、変更がドキュメントに値するかどうかを判断するためのものです。これらは自動化されたパイプラインを対象としており、あなたに適用されるものではありません。自身がリリースした機能のドキュメントをエンジニアが求めている場合、そのエンジニアはゲートでは把握できない背景情報を持っています。これらの基準を理由に依頼を断らないでください。

2. ステップ 3 でエンジニアが確認した コンテンツ設計計画。PR の本文に ## Content design plan セクションとして含めてください。

既存のページが対象範囲をすでに扱っている場合は、新しいページを作成するより、既存のページを更新してください。

ドラフトの生成後、warpdotdev/docs に提出します。

1. warpdotdev/docs を一時ディレクトリにクローンします（または、利用可能であればローカルのクローンを使用します）。

2. MDX ファイルを src/content/docs/<proposed-section>/<filename>.mdx に書き込みます。

3. 適切なセクションの src/sidebar.ts に、プレースホルダーのエントリを追加します。例：

   // [TODO: docs reviewer — confirm placement]
   { label: '<Feature name>', link: '/<section>/<feature-name>/' },
   

4. docs/<spec-id>-feature-draft という名前の新しいブランチでコミットしてプッシュします。

5. PR の本文を一時ファイルに書き込んでから、--body-file を使ってドラフト PR を作成します。 PR の説明には次の内容を含めてください。

   • 機能名と spec ID
   • 元の spec PR へのリンク
   • レビュアーが確認できるよう、ドラフト内の [UNVERIFIED] と [TODO] の全項目の一覧

   利用可能な方法（ファイル作成ツール、Python の open() 呼び出し、または引用符で囲んだヒアドキュメントを使うシェルの cat）で本文を /tmp/pr-body.md に書き込み、その後 gh に渡してください。

   gh pr create --draft --body-file /tmp/pr-body.md ...
   

   PR の本文をインラインで渡さないでください（--body "..."、echo、または printf から直接 gh にパイプする方法）。シェルの文字列展開では、文字列が gh に渡される前にバッククォート、$vars、[ ] のグロブパターンが展開され、これらの文字を含むマークダウンが破損します。先にファイルに書き込めば、コンテンツがシェルに解釈されるのを防げます。

   PR 本文の「Docs outline」セクションでは、エージェントが確認した項目には - [x] のチェックボックスではなく、通常の箇条書き（-）を使ってください。- [ ] のチェックボックスは「Items needing review」セクションにのみ使用し、レビュアーが対応すべき項目を正確に把握できるようにしてください。

6. PR 本文で、ステップ 2 で取得したハンドルを使って spec の作成者に通知します。

   • 有効な GitHub ハンドルが見つかった場合：/cc @<engineer-handle> を含めてください。
   • 代替のプレースホルダーが出力された場合：[TODO: tag spec author] という文字列をそのまま含めてください。/cc @ で囲まないでください。正しくないメンションになってしまいます。 @rachaelrenk と @hongyi-chen にレビューを依頼してください。

---

仕様がない場合のフォールバック

specs/<id>/PRODUCT.md と specs/<id>/TECH.md が存在しない場合は、エンジニアに質問する前に、まずコードベースを調査してください。

調査手順：

1. warpdotdev/warp-internal（または状況に応じて warp-server）で、機能名と関連用語を検索します：gh search code "<feature-name>" --repo warpdotdev/warp-internal
2. 最も関連性の高いソースファイルを読み、機能の内容を把握します
3. 別の ID の仕様ファイルがないか確認します：gh api repos/warpdotdev/warp-internal/contents/specs
4. 機能に関連する最近マージされた PR を確認します：gh pr list --search "<feature-name>" --state merged --repo warpdotdev/warp-internal --limit 10

調査後、 可能な限り全体像を把握してから、コードから補えなかった具体的な情報だけを ask_user_question で尋ねてください。広範な聞き取りは避けてください。質問は具体的にまとめます：「この機能は app/src/ai/ にあることがわかりました。コードから、次のように理解しています：[概要]。次の 2 点は判断できませんでした：[具体的な質問]。」

調査結果とエンジニアから得た的を絞った回答をもとに計画とアウトラインを作成し、ドラフトを作成する前に、ステップ 3（計画の確認）とステップ 4（アウトラインの確認）を進めてください。

---

対話形式のみ — 無人モードはありません

このスキルには以前、scan-new-specs がヘッドレスで実行できる「アンビエントモード」があり、ステップ 3 と 4 の確認を省略して、アウトラインをチェックリストとして PR の説明に埋め込んでいました。このモードは削除され、scan-new-specs は廃止されました。

マージ済みの仕様はリリース済みの機能とは限らず、無人実行ではその違いを判別できなかったため、未リリース機能のドラフト PR が作成されていました。また、アウトラインの確認を省略したことで、文章の作成前に人がドラフトの方向性を修正できる唯一のチェックポイントもなくなっていました。

ここに無人実行の経路を再び追加しないでください。

• 自動化されたリリーストリガーのドキュメント作成には、warpdotdev/docs リポジトリの missing_docs を使用してください。ドラフト作成前に、すべての候補に対して .agents/references/docs-worthiness-criteria.md による判定を行い、新しい安定版がリリースされた場合にのみ実行されます。
• 自分の機能についてドキュメントを作成したいエンジニアには、このスキルが適しています。エンジニアが立ち会った状態で直接実行し、アウトラインと TECH.md の範囲を確認してもらってください。

対話セッションなしで実行している場合は、ドラフトを作成せず、このスキルには対話セッションが必要であることを報告して停止してください。

---

関連スキル

• write-product-spec — このスキルが読み込む PRODUCT.md を作成します
• write-tech-spec — このスキルが読み込む TECH.md を作成します
• missing_docs（warpdotdev/docs 内）— 新たにリリースされた機能のドキュメントを作成するための、リリーストリガー型で適格性判定を行うパイプラインです
• scan-new-specs — 廃止済みです。廃止に関するお知らせを参照してください