teams-docs-discovery

name	teams-docs-discovery
description	Generate Discovery phase documents (PRD and user stories) in the teams/ directory. Phase 1 of the /start-teams-doc workflow. Use when creating PRDs, user stories, or requirements definitions under teams/.

Teams Docs — Discovery スキル

トリガー条件

• /teams-docs-discovery コマンドが呼ばれたとき
• /start-teams-doc の第1フェーズ（discovery フェーズ）として呼ばれたとき
• ユーザーが「PRD を作りたい」「ユーザーストーリーを作りたい」「Discovery ドキュメントを作りたい」と言ったとき

入力パラメータ

必須:

• docs_root: ドキュメントルートパス（sdd-docs または .）。/start-teams-doc から自動検出・引き渡しされる
• team: チーム名。.sdd-config.yaml に teams: があればその中から選択、なければ任意
• project: プロジェクト名（日本語可）
• feature: フィーチャー名（日本語可）
• feature_id: IDプレフィックス用の英語エイリアス（kebab-case、例: shohin-kensaku）
• goal: このフィーチャーで達成したい価値
• scope_in: スコープ内の事項
• scope_out: スコープ外の事項

任意:

• constraints: 期限・法令・予算・技術的制約

実行前チェック

1. {docs_root}/teams/{team}/{project}/{feature}/_approval-status.yaml が存在しない場合は新規作成する
2. _approval-status.yaml の discovery.status が changes_requested の場合は修正モードで実行
3. discovery.status == in_review の場合はドキュメント生成をスキップし、構造バリデーションのみ再実行して承認確認メッセージに直接進む
4. discovery は前フェーズなし（常に実行可）

手順

1. ディレクトリ準備

{docs_root}/teams/{team}/{project}/{feature}/
├── _approval-status.yaml  （新規作成または更新）
└── discovery/
    ├── prd.md
    └── ユーザーストーリー/

_approval-status.yaml を作成・初期化する。

2. prd.md 生成

• テンプレート: assets/prd-template.md
• {feature_id} を _approval-status.yaml の feature_id で置換
• 入力パラメータを各セクションに展開
• 要件は最低3件（REQ-{feature_id}-001〜）を作成し Given/When/Then を付与
• 曖昧語（「適切に」「必要に応じて」など）は使用しない

3. ユーザーストーリー生成

• テンプレート: assets/ユーザーストーリー-template.md
• 各 REQ に対して最低1件のユーザーストーリーファイルを作成
• ファイル名: {ストーリータイトル}.md（日本語可）
• US ID を US-{feature_id}-NNN 形式で採番
• Related: [REQ-{feature_id}-NNN] を各ファイルに記入

4. Traceability Matrix 更新

• prd.md 末尾の Traceability Matrix に REQ→US の対応を記入

品質ゲート（承認前チェック）

references/quality-checklist.md の全項目を確認する。 未通過項目がある場合は修正してから承認確認を行う。

バリデーションスクリプトを実行して自動チェックを行う:

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

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

エラーが出た場合は修正してから承認確認を行う。

承認確認メッセージ

品質ゲート通過後、承認確認メッセージを表示する前に _approval-status.yaml の discovery.status を in_review に更新する。 これにより、ユーザーが承認確認中にセッションを中断しても、次回再開時にドキュメント生成をスキップできる。

以下を表示する:

✅ [discovery] フェーズの品質ゲートを通過しました。

承認しますか？
  1. Approve & Continue（_approval-status.yaml を更新して完了）
  2. Request Changes（修正点を確認して停止）
  3. Pause Review（レビューを中断して後で再開）

承認時: _approval-status.yaml の discovery.status を approved、approved_at を本日付で更新する。 修正要求時: _approval-status.yaml の discovery.status を changes_requested に更新し、ユーザーが指摘した修正点の一覧を表示して停止する。 レビュー中断時: status は in_review のまま維持。以下を表示して停止する:

⏸️ [discovery] フェーズのレビューを中断しました。
`/start-teams-doc` で再開できます。

出力ファイル一覧

ファイル	必須
{docs_root}/teams/{team}/{project}/{feature}/_approval-status.yaml	✅
{docs_root}/teams/{team}/{project}/{feature}/discovery/prd.md	✅
{docs_root}/teams/{team}/{project}/{feature}/discovery/ユーザーストーリー/{タイトル}.md	✅（最低1件）

Troubleshooting

• validate.py が孤立 ID を報告する → REQ と US の対応関係を確認する。各 US ファイルに Related: [REQ-xxx-NNN] が記載されているか、各 REQ に対応する US が存在するかを確認する。
• 曖昧な表現が検出される → references/quality-checklist.md の禁止ワード一覧（「適切に」「必要に応じて」等）を確認し、具体的な条件・数値に書き換える。
• Given/When/Then が不足している → 各要件（REQ）に受け入れ基準を追加する。最低1つの Given/When/Then パターンが必要。

参照

• references/quality-checklist.md