start-teams-doc

name	start-teams-doc
argument-hint	[team/project/feature]
description	Unified entry point for generating feature documentation in the teams/ directory. Automatically detects the current phase (Discovery, Design, QA, Operations) and delegates to the appropriate skill. Use when creating new feature docs, continuing existing feature docs, or when user says /start-teams-doc.

start-teams-doc スキル

トリガー条件

• /start-teams-doc スキルが呼ばれたとき
• ユーザーが「teams のドキュメントを作りたい」「どこから始めればいい？」「フィーチャードキュメントを作りたい」と言ったとき

Step 0: 既存フィーチャーの検出と再開フロー

パラメータ収集の前に、既存フィーチャーを検出して再開オプションを提示する。 docs_root の解決（実行手順 0）を先に行ってから本ステップを実行すること。

パス A: 引数による直接指定

/start-teams-doc {team}/{project}/{feature} の形式で引数が渡された場合、パスを解析して即再開する。

1. 引数を / で分割し team, project, feature を取得
2. {docs_root}/teams/{team}/{project}/{feature}/ の存在を確認
3. 以下の分岐表に従いパラメータを取得し、バッチ wizard をスキップして実行手順 1 へ進む

パス B: 既存フィーチャー一覧から選択

引数なしで実行された場合:

1. {docs_root}/teams/ 配下を 3 階層（{team}/{project}/{feature}/）までスキャンする
2. フェーズディレクトリ（discovery, design, qa, operation）は除外し、フィーチャーディレクトリのみ収集する
3. 既存フィーチャーが 0 件 の場合はこのステップをスキップし、バッチ 1 から開始する
4. 既存フィーチャーが 1 件以上 の場合、以下の形式で 1 回の AskUserQuestion で提示する:

既存のフィーチャーが見つかりました。続きから再開するか、新規作成を選んでください:

  1. {feature_name} ({team}/{project}) {status_hint}
  2. {feature_name} ({team}/{project}) {status_hint}
  ...
  0. 新しいフィーチャーを作成する

番号を入力してください:

status_hint の決定:

• _approval-status.yaml が存在する場合: フェーズ進捗アイコンを表示（例: [✅Discovery → ⏳Design]）
• _approval-status.yaml が存在しない場合: 既存サブディレクトリ名を表示（例: [design/operation]）

5. フィーチャーが 15 件を超える場合は、最終更新日が新しい順に 15 件を表示し、残りは「他に {N} 件あります。チーム名を入力すると絞り込めます」と表示する

ユーザーが 0 を選択した場合は従来のバッチ 1 → バッチ 2 wizard を実行する。 既存フィーチャーを選択した場合は以下の分岐表に従う。

選択後の分岐表（パス A・B 共通）

条件	バッチ 1	バッチ 2
_approval-status.yaml あり + _interview-notes.yaml あり	スキップ（yaml から読み取り）	スキップ
_approval-status.yaml あり + _interview-notes.yaml なし	スキップ（yaml から読み取り）	実行
_approval-status.yaml なし + _interview-notes.yaml あり	スキップ（パスから推定、feature_id 自動生成）	スキップ
_approval-status.yaml なし + _interview-notes.yaml なし	スキップ（パスから推定、feature_id 自動生成）	実行

パスから推定する場合: ディレクトリパスの各階層から team（第1階層）、project（第2階層）、feature（第3階層）を取得し、feature_id は既存の自動生成ルールで生成する。

入力パラメータ収集（バッチ wizard 形式）

Step 0 で既存フィーチャーが選択された場合は、上記の分岐表に従いスキップ可能なバッチを省略する。 新規フィーチャーが選択された場合、または Step 0 がスキップされた場合（既存フィーチャー 0 件）は、以下をバッチ形式で収集する。

パラメータ一覧

パラメータ	説明	必須
team	チーム名。.sdd-config.yaml に teams: があればその中から選択、なければ任意	✅
project	プロジェクト名（日本語可）	✅
feature	フィーチャー名（日本語可）	✅
feature_id	feature 名から自動生成（kebab-case）	自動
goal	このフィーチャーで達成したい価値	✅
scope_in	スコープ内の事項	✅
scope_out	スコープ外の事項	✅
constraints	期限・法令・予算・技術的制約	任意

収集方法（バッチ提示）

AskUserQuestion の呼び出しは 2回（バッチ1 + バッチ2）に収める。 各バッチは 1回の AskUserQuestion で全項目をまとめて提示すること。項目ごとに個別の AskUserQuestion を発行してはならない。

バッチ1: 基本情報（1回の AskUserQuestion で以下を全て聞く）

以下の基本情報を教えてください:

1. チーム名: （`.sdd-config.yaml` に `teams:` が定義されている場合はその中から選択、なければ任意）
2. プロジェクト名: （日本語可）
3. フィーチャー名: （日本語可）

feature_id 自動生成ルール: バッチ1でフィーチャー名を受け取った後、以下のルールで feature_id を自動生成する:

• フィーチャー名が英語の場合: そのまま kebab-case に変換（例: Product Search → product-search）
• フィーチャー名が日本語の場合: ローマ字に変換して kebab-case（例: 商品検索 → shohin-kensaku）
• スペース・記号はハイフンに置換、小文字化

バッチ2: スコープ・制約（1回の AskUserQuestion で以下を全て聞く）

フィーチャーの詳細を教えてください（番号に対応する形で回答してください）:

1. 達成したい価値（goal）: このフィーチャーで実現したいこと
2. スコープ内の事項: このフィーチャーに含まれる機能・対応範囲
3. スコープ外の事項: 今回のスコープに含めないもの
4. 制約事項（任意）: 期限・法令・予算・技術的制約があれば

未回答の必須項目がある場合のみ、不足分をまとめて1回の AskUserQuestion で再確認する。

実行手順

0. docs_root の解決（サブモジュール対応）と設定ファイルの読み込み

ドキュメントリポジトリがサブモジュールとして利用されている場合、ドキュメントの生成先はサブモジュール内の teams/ ディレクトリになる。以下のロジックで docs_root を自動検出する:

1. ワークスペースルートに sdd-docs/teams/ ディレクトリが存在するか確認
2. 存在する場合 → docs_root = sdd-docs（サブモジュールモード）
3. 存在しない場合 → docs_root = .（スタンドアロンモード — 本リポジトリ単体で利用）

サブモジュールのディレクトリ名は sdd-docs を既定とする。別名を使っている場合は、その名前に読み替えること。

以降の全てのパスは {docs_root}/teams/... の形式で解決する。docs_root は全てのスキル・エージェントへの委譲時にパラメータとして引き渡す。

続いて {docs_root}/.sdd-config.yaml の存在を確認する:

• 存在する場合 → teams: に列挙されたチーム名を読み込み、バッチ1のチーム名質問ではその中から選択させる
• 存在しない場合 → チーム名は自由入力とする

1. フィーチャーパスの特定

{docs_root}/teams/{team}/{project}/{feature}/_approval-status.yaml

2. 現在のフェーズ状態を読み込む

_approval-status.yaml が存在する場合は読み込み、存在しない場合は全フェーズ pending として扱う。

3. 進捗インジケーターを表示する

フェーズ開始前に必ず以下の形式で現在の進捗を表示する:

📋 start-teams-doc: {feature}

[✅ Discovery] → [✅ Design] → [⏳ QA] → [⬜ Operations]

凡例:

• ✅ — status: approved
• ⏳ — 実行中（これから着手するフェーズ）
• ⬜ — 未着手
• 👀 — status: in_review（レビュー待ち）
• 🔄 — status: changes_requested（修正待ち）

3.5. インタビュー実行

次に実行するフェーズを特定した後、フェーズスキルへ委譲する前にインタビューを実施する。

条件	アクション
_interview-notes.yaml が存在しない	interviewer スキルを mode: initial で呼び出す（共通質問 + フェーズ固有質問）
_interview-notes.yaml が存在する	interviewer スキルを mode: phase-followup で呼び出す（フェーズ固有質問のみ）

インタビュー呼び出し時のパラメータ:

target_skill: teams-docs-{次のフェーズ名}
output_dir: {docs_root}/teams/{team}/{project}/{feature}
mode: initial または phase-followup
existing_notes: （存在する場合）_interview-notes.yaml の内容
context_params: { team, project, feature, feature_id, goal, scope_in, scope_out, constraints, docs_root }

インタビュー結果（_interview-notes.yaml）はフェーズスキルへのコンテキストとして引き渡す。フェーズスキルは _interview-notes.yaml が存在する場合、その内容を参照してドキュメントの質を向上させる。

4. 次に実行すべきフェーズを自動判定して委譲する

条件	実行するスキル
discovery.status が pending または yaml なし	teams-docs-discovery
discovery.status == approved かつ design.status != approved	teams-docs-design
design.status == approved かつ qa.status != approved	teams-docs-qa
qa.status == approved かつ operation.status != approved	teams-docs-operations
全フェーズ approved	完了メッセージを表示して終了

優先順位（上が最優先）:

1. changes_requested のフェーズがある場合は、そのフェーズを最優先で修正モードで実行する
2. in_review のフェーズがある場合は、インタビュー・ドキュメント生成をスキップし、構造バリデーション（手順5）のみ実行して承認確認に直接進む
3. 上記テーブルに従い、次の pending フェーズを実行する

5. 構造バリデーション（フェーズ実行前）

フェーズスキルへ委譲する前に、構造バリデーションスクリプトを実行する。 新規フィーチャー（ディレクトリ未作成）の場合はスキップしてよい。

python <this_skill_dir>/scripts/validate-structure.py <feature_dir>

<this_skill_dir> は、この SKILL.md が配置されているディレクトリの実際のパスに解決すること。

既存のディレクトリ構成・ファイル命名・ID採番・_approval-status.yaml の整合性をチェックし、問題があれば修正してからフェーズを開始する。 承認ルール・トレーサビリティルールの詳細は references/rules.md を参照。 ID整合ルールについても references/rules.md を参照。

6. スキルへの委譲

決定したスキルを読み込み、収集済みのパラメータ（docs_root を含む）をそのまま引き渡して実行する。 委譲先スキルで再度パラメータの入力を求めない。

6.5. ソースコード参照ガイダンス

サブモジュールモード（docs_root = sdd-docs）の場合、ワークスペースルートにはメインリポジトリのソースコードが存在する。各フェーズスキルは必要に応じてソースコードを参照し、ドキュメントの精度を高めること:

• Design: 既存のコードベース構造・DB スキーマ・API 定義を参照してモデリング・spec を作成
• QA: 既存テストコードのパターン・テストフレームワーク設定を参照してテスト計画を作成
• Operations: インフラ構成（Dockerfile, k8s manifests 等）・CI/CD 設定・監視設定を参照して運用ドキュメントを作成

7. 構造バリデーション（フェーズ実行後）

フェーズスキル完了後・承認確認前に、再度構造バリデーションスクリプトを実行する。

python <this_skill_dir>/scripts/validate-structure.py <feature_dir>

バリデーションエラーがある場合は承認前に修正を行う。

全フェーズ完了時のメッセージ

🎉 {feature} のドキュメントが全フェーズ完了しました。

生成されたドキュメント:
  {docs_root}/teams/{team}/{project}/{feature}/
  ├── _approval-status.yaml
  ├── discovery/
  │   ├── prd.md
  │   └── ユーザーストーリー/
  ├── design/
  │   ├── 非機能要件.md
  │   ├── モデリング.md
  │   ├── spec/
  │   └── adr/（該当する場合）
  ├── qa/
  │   ├── テスト計画書.md
  │   ├── 非機能要件のテスト.md
  │   └── ユーザーストーリー/*.feature
  └── operation/
      ├── slo-sla.md
      └── ...

Troubleshooting

• _approval-status.yaml が見つからない → 新規フィーチャーとして扱い、Discovery フェーズから開始する。_approval-status.yaml は Discovery フェーズ実行時に自動生成される。
• フェーズ自動判定が正しくない → ユーザーに確認し、手動でフェーズを指定する。_approval-status.yaml の各フェーズの status 値を確認する。
• validate-structure.py がエラーを返す → エラーメッセージに従いディレクトリ構造・必須ファイル・ID 採番を修正する。詳細は references/rules.md を参照。
• サブモジュールモードで docs_root が解決できない → sdd-docs ディレクトリの存在を確認する。存在しない場合は docs_root = . として実行する。

参照スキル・エージェント

• references/rules.md（承認ルール・トレーサビリティルール）
• scripts/validate-structure.py（構造バリデーション）
• interviewer
• teams-docs-discovery
• teams-docs-design
• teams-docs-qa
• teams-docs-operations