| 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: 期限・法令・予算・技術的制約
実行前チェック
{docs_root}/teams/{team}/{project}/{feature}/_approval-status.yaml が存在しない場合は新規作成する_approval-status.yaml の discovery.status が changes_requested の場合は修正モードで実行discovery.status == in_review の場合はドキュメント生成をスキップし、構造バリデーションのみ再実行して承認確認メッセージに直接進む- 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 パターンが必要。
参照
