yodogawa 2.1.3 → 2.2.0

package/skills/a-002b-define-user-stories/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: a-002b-define-user-stories
+description: Product Brief と MVP スコープ確定後に、Must 機能を起点としたユーザーストーリー（役割・目的・価値）を作成し、要約レベルの受け入れ基準と優先度を付与する。a-002a（MVP スコープ）の後、a-003（シナリオ）の前に実行。
+disable-model-invocation: true
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# DefineUserStories (a-002b)
+
+## 目的
+
+- MVP スコープで Must と判定した機能を、ユーザー視点のストーリー（[役割]として[目的]がしたい、なぜなら[価値]だから）に翻訳する。
+- 各ストーリーに要約レベルの受け入れ基準（AC）と優先度を付与し、後続の Core Scenarios（a-003）の入力にする。
+- 実行順は a-002a（MVP スコープ）の後、a-003（シナリオ）の前。
+
+## 前提
+
+- `docs/project/01-requirements/01-product-brief.md` と `02-mvp-scope.md` が作成されていること（なければ先に `/a-002-initialize-project` → `/a-002a-slice-mvp-scope` を実行）。
+- Must 機能が `02-mvp-scope.md` に確定していること。
+
+## 手順
+
+### 1. 前提の確認
+
+```bash
+ls -l docs/project/01-requirements/01-product-brief.md docs/project/01-requirements/02-mvp-scope.md 2>/dev/null \
+  || echo "MISSING: 01-product-brief.md または 02-mvp-scope.md"
+```
+
+不足時: 「先に `/a-002-initialize-project`（Product Brief）→ `/a-002a-slice-mvp-scope`（MVP スコープ）を実行してください。」と促して中断。
+
+### 2. テンプレートの準備
+
+このスキルの配置ディレクトリ（`skills/a-002b-define-user-stories/`）を起点に、`../../templates/project/01-requirements/05-user-stories.md` を Read→Write で `docs/project/01-requirements/05-user-stories.md` へコピーする。出力先に既に存在する場合は上書きせずスキップして報告する（冪等）。
+
+### 3. ストーリーの抽出と記入
+
+`01-product-brief.md`（ターゲットユーザー・価値提案）と `02-mvp-scope.md`（Must 機能）を読み込み、Must 機能ごとに主要ユーザージャーニーを抽出する。
+
+FOR EACH 主要ジャーニー: `05-user-stories.md` のテーブルに記入する。
+
+- テンプレート: 「[役割]として、[〇〇機能]を使いたい、なぜなら[価値]だから」
+- **ペルソナ列を必ず埋める**: `01-product-brief.md` の「ターゲットユーザー / 主要ペルソナ」表の ID（P-XXX）を「ペルソナ」列に記入し、ストーリーの `[役割]` を**その ID のペルソナと一致**させる（役割が宙に浮かないようにする）。
+- **役割が既存ペルソナに無い場合**: 勝手に新しい役割を増やさず、`01-product-brief.md` のペルソナ表に追加してから参照する（ペルソナの SSoT は Product Brief）。
+- ヒアリング: 「他に主要なユーザージャーニーがあれば教えてください」「各ストーリーの優先度・受け入れ基準は？」
+- **Must 機能に紐づかないストーリーは作らない**（スコープ外。Parking Lot / Won't に倒す）。
+
+> ストーリーの書き方・INVEST・受け入れ基準（AC）・優先度付け・3C の詳細は [reference/user-stories-guide.md](reference/user-stories-guide.md) を参照。
+
+### 4. SSoT の住み分け確認
+
+User Story は**要約レベルの受け入れ基準（AC）**を担い、実行時の主要行動は次スキル `/a-003-create-scenarios` の Core Scenario が担う。同じ振る舞いを二重に Gherkin 化しない。
+
+### 5. レビューと構造チェック
+
+ユーザーにストーリー一覧を提示し、INVEST（独立・交渉可能・価値・見積可能・小さい・テスト可能）の観点で確認する。
+
+```bash
+grep "| ストーリーID | ペルソナ | ストーリー |" docs/project/01-requirements/05-user-stories.md \
+  && echo "OK" || echo "MISSING: Table Header"
+```
+
+## 完了条件
+
+- `docs/project/01-requirements/05-user-stories.md` が作成され、各ストーリーに役割・目的・価値・優先度・受け入れ基準が記入されている。
+- 各ストーリーの「ペルソナ」列が `01-product-brief.md` のペルソナ表の ID（P-XXX）を参照し、`[役割]` がその記載と一致している（役割が宙に浮いていない）。
+- すべてのストーリーが `02-mvp-scope.md` の Must 機能に紐づいている。
+- ユーザーがストーリー内容を確認し、承認またはフィードバックを提供している。
+
+## エスカレーション
+
+- **Must に紐づかないストーリーが出る**: 「このストーリーは MVP の Must 機能に対応しません。Parking Lot へ回すか、スコープを見直しますか？」と確認。
+- **役割に対応するペルソナが Product Brief に無い**: 「この役割は `01-product-brief.md` のペルソナ表にありません。新しいペルソナとして追加しますか？それとも既存ペルソナに寄せますか？」と確認し、ストーリー側で役割を勝手に増やさない。
+- **AC が曖昧**: 「『正しく動く』では検証できません。観測可能な条件（〜が表示される / 〜が保存される）で書けますか？」と促す。
+
+## 参考
+
+- [reference/user-stories-guide.md](reference/user-stories-guide.md) — INVEST・受け入れ基準・優先度付け・3C の詳しい考え方
+- `01-product-brief.md` — ターゲットユーザー・価値提案の参照元
+- `02-mvp-scope.md` — Must 機能の参照元

package/skills/a-002b-define-user-stories/reference/user-stories-guide.md

@@ -0,0 +1,78 @@
+# ユーザーストーリー作成ガイド
+
+`05-user-stories.md` を書くときの原則・フォーマット・ベストプラクティス集。テンプレートは記入欄中心に保ち、
+詳しい考え方が必要なときに本ガイドを参照する。
+
+## ユーザーストーリーとは
+
+ユーザー視点の機能要求を物語形式で記述したバックログ。詳細仕様ではなく**議論の出発点（会話のきっかけ）**として機能する。
+
+- **目的**: ユーザーの課題とニーズの明確化 / 開発チームとステークホルダーの共通理解 / 開発優先度の判断材料 / スプリント計画の基礎資料。
+- **特徴**: 実装方法ではなくユーザーの「なぜ」に焦点。継続的に追加・更新・削除される Living Document。
+
+## INVEST 原則
+
+良いストーリーの 6 条件。
+
+- **Independent（独立）**: 他ストーリーへの依存が少ない
+- **Negotiable（交渉可能）**: 詳細は会話で詰められる余地がある
+- **Valuable（価値）**: ユーザー/ビジネスに価値がある
+- **Estimable（見積可能）**: 規模を見積もれる
+- **Small（小さい）**: 1〜2 週間のスプリントで完了できるサイズ
+- **Testable（テスト可能）**: 完了を検証できる
+
+記載粒度: 大きすぎる場合は Epic として分割、小さすぎる場合は他ストーリーと統合を検討する。
+
+## ストーリーのフォーマット
+
+標準: 「**[役割]として、[目的]がしたい、なぜなら[理由]**」（英: "As a [role], I want [goal] so that [benefit]"）。
+
+- **役割（Who）**: ユーザーの種類やペルソナ（例: 新入社員 / 管理者 / エンドユーザー）。`01-product-brief.md` のペルソナ表の ID（P-XXX）を「ペルソナ」列で参照し、役割名をその記載と一致させる（役割を宙に浮かせない）。該当ペルソナが無ければ Product Brief 側に追加する。
+- **目的（What）**: 実現したい機能や行動（例: プロフィールを編集したい）
+- **理由（Why）**: その機能が必要な理由・得られる価値（例: 自分の情報を最新に保つため）
+
+書き方のコツ: 技術用語を避けユーザーの言葉で書く / 実装方法（How）ではなく目的（What・Why）に集中 / 1 ストーリー 1 価値 / 曖昧さを避け具体的に。
+
+## 受け入れ基準（Acceptance Criteria）
+
+ストーリーが「完了」と判断できる明確な基準。測定可能・テスト可能・Yes/No で判定可能であること。
+
+**フォーマット1: Given-When-Then（BDD 形式）**
+
+```
+Given [前提条件]
+When  [アクション]
+Then  [期待される結果]
+```
+
+例: `Given ログイン済みユーザーが自分のプロフィールページにいる時 / When 「編集」して保存すると / Then 変更後の名前が表示される`
+
+**フォーマット2: チェックリスト形式**
+
+- [ ] ユーザーは名前・メール・画像を編集できる
+- [ ] 保存時にバリデーションエラーが表示される
+
+書き方のベストプラクティス: 最低 1 個、通常 3〜7 個 / UI の細かい仕様ではなくビジネス価値の検証に焦点 / 「意図」を書き「実装方法」は書かない / 開発者とテスターが明確にテストできる内容にする。
+
+## 優先度
+
+開発順序の判断材料。一般的な分類:
+
+- **High**: 必須機能、ビジネス価値が高い、依存が多い
+- **Medium**: 重要だが緊急ではない、代替手段がある
+- **Low**: あると良い、将来検討
+
+考慮要素: ビジネス価値 / 緊急性 / リスク / 工数（ROI）/ 依存関係。
+
+注意: 優先度は変動する（定期見直し）。すべてが High になる状況を避け、真の優先順位をつける。最終決定権はプロダクトオーナー。
+
+> MVP の取捨選択（Must / Not Now / Won't）と検証仮説への紐づけは `/a-002a-slice-mvp-scope`（`02-mvp-scope.md`）が担う。
+> 本ガイドの「優先度」は実装順の目安であり、MVP スコープ判断とは役割を分ける。
+
+## 全体のベストプラクティス
+
+- **3C 原則**: Card（カード）/ Conversation（会話）/ Confirmation（確認）。
+- ストーリーはチーム全員（PO・開発・デザイナー・QA）で作成する。
+- 定期的なリファインメントで詳細化・分割・統合する。
+- 完了の定義（DoD）を明確にする。実装後のフィードバックを次のストーリーに反映する。
+- テクニカルストーリー（リファクタリング・技術的負債解消）も含めてよい。

package/skills/a-003-create-scenarios/SKILL.md

@@ -1,96 +1,97 @@
----
-name: a-003-create-scenarios
-description: ユーザーストーリーから Gherkin 形式のシナリオを生成し、BDD で振る舞いを定義する。要件定義後、ドメインモデル設計前の振る舞い明確化に使用。
-disable-model-invocation: true
-allowed-tools: Read, Write, Edit, Bash, Grep, Glob
----
-
-# CreateScenarios (a-003)
-
-## 目的
-
-- ユーザーストーリーから具体的なシナリオ（振る舞い）を抽出し、Gherkin 形式で記述する。
-- Given-When-Then 構造で、開発者・QA・ステークホルダーが共通理解できる実行可能なドキュメントを作成する。
-- ハッピーパス（正常系）からエラーケース、境界値テストまでを網羅的に定義する。
-
-## 前提
-
-- `docs/project/01-requirements/05-user-stories.md` が作成されていること（`/a-002-initialize-project` 実行済み）。
-- `docs/project/02-behavior/` ディレクトリが存在すること（未作成なら `/a-001-setup-doc-structure`）。
-- ユーザーが各機能の具体的な動作例を説明できること。
-
-## 手順
-
-### 1. ディレクトリと前提条件の確認
-
-```bash
-ls -la docs/project/02-behavior/ 2>/dev/null || echo "ディレクトリが存在しません"
-```
-
-`docs/project/01-requirements/05-user-stories.md` を読み込み、シナリオ化対象を把握する。
-
-### 2. テンプレートの準備
-
-このスキルの配置ディレクトリ（`skills/a-003-create-scenarios/`）を起点に、相対パス `../../templates/project/02-behavior/01-scenarios.md` を Read で読み込み、その内容を `docs/project/02-behavior/01-scenarios.md` へ Write する。出力先が既に存在する場合は上書きせずスキップして報告する（冪等）。出力先ディレクトリ（`docs/project/02-behavior/`）が無ければ作成する。
-
-### 3. 分析と提案
-
-ユーザーストーリーを機能（Feature）単位にグルーピングし、ハッピーパスと代表的なエラーケースの案を提示。
-
-- 「機能: [機能名] (US-XXX)」
-- 「シナリオ案1: [ハッピーパス] / シナリオ案2: [エラーケース]」
-
-### 4. ヒアリングと記入
-
-機能ごとに以下を詰めて `docs/project/02-behavior/01-scenarios.md` を更新する。Gherkin 記述例は [examples/gherkin-templates.md](examples/gherkin-templates.md) を参照。
-
-- **Feature 情報**: 機能名、As a/I want/So that、Background（共通前提）
-- **ハッピーパス**: Given-When-Then で最も基本的な成功シナリオ
-- **エラーケース・境界値**: 必要に応じて Scenario Outline（Examples テーブル）を使用
-- **タグ付け**: `@SC-XXX` ID 採番、`@smoke` `@happy-path` `@error-handling` 等
-
-UI 操作の詳細ではなく、ユーザーの意図を記述するよう注意する。
-
-### 5. シナリオ一覧テーブルの更新
-
-ドキュメント冒頭の一覧テーブルに、全シナリオの ID・機能・シナリオ名・優先度を記載する。テーブル例は [examples/gherkin-templates.md](examples/gherkin-templates.md#シナリオ一覧テーブル例) を参照。
-
-### 6. レビューと確認
-
-ユーザーに提示し、実際の動作の正確性、抜け漏れ、非技術者への理解可能性を確認する。質問例は [reference/structure-check.md](reference/structure-check.md#レビュー確認質問) を参照。
-
-### 7. 構造チェック
-
-```bash
-grep "Feature:" docs/project/02-behavior/01-scenarios.md \
-  && grep "Scenario:" docs/project/02-behavior/01-scenarios.md \
-  && echo "OK" || echo "MISSING SECTION"
-```
-
-詳細なチェックリストは [reference/structure-check.md](reference/structure-check.md#チェックリスト) を参照。
-
-### 8. Git への追加（任意）
-
-```bash
-git add docs/project/02-behavior/
-git commit -m "docs: 振る舞い仕様（シナリオ）の作成"
-```
-
-詳細は [reference/structure-check.md](reference/structure-check.md#git-への追加任意) を参照。
-
-## 完了条件
-
-- `docs/project/02-behavior/01-scenarios.md` が作成されている。
-- ユーザーストーリーに対応する具体的なシナリオ（Given-When-Then）が記述されている。
-- シナリオ一覧テーブルがメンテナンスされている。
-- ユーザーが内容を承認している。
-
-## エスカレーション
-
-- **ユーザーストーリーが不明確でシナリオ化できない**: 「`/a-002-initialize-project` に戻って要件を明確にしましょう。」
-- **実装詳細への依存が強すぎる**: 「UI 操作（ボタンクリック等）ではなく、ユーザーの意図（登録する等）に焦点を当てた記述に変更しましょう。」
-
-## 参考
-
-- [examples/gherkin-templates.md](examples/gherkin-templates.md) — Feature / Scenario / Scenario Outline の記述例、タグ付けガイド、一覧テーブル例
-- [reference/structure-check.md](reference/structure-check.md) — 構造確認コマンド、チェックリスト、レビュー観点、Git 追加例
+---
+name: a-003-create-scenarios
+description: MVP Scope の Must 機能から「価値提供が成立する最小行動（Core Scenarios）」を定義する。Day 1 の成功体験・価値を壊す重大失敗・MVP で対応しない範囲を固定する。詳細な Gherkin は任意。要件定義後、ドメイン設計前の振る舞い明確化に使用。
+disable-model-invocation: true
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# CreateScenarios (a-003)
+
+## 目的
+
+- MVP Scope の Must 機能から、価値提供が成立する**最小の主要行動**を Core Scenarios として定義する。
+- Day 1 に必ず通る成功体験（Happy Path 1〜3 本）と、価値を壊す重大失敗（Critical Failure）を固定する。
+- MVP で対応しない行動・エラー（Not Covered in MVP）を明示し、スコープ膨張を防ぐ。
+- 全ケース網羅の BDD（ハッピー / エラー / 境界値）は目的としない。詳細 Gherkin は実装直前・テスト設計時の任意作業に降格する。
+
+## 前提
+
+- `docs/project/01-requirements/01-product-brief.md` / `02-mvp-scope.md` / `05-user-stories.md` が作成されていること（`/a-002-initialize-project` → `/a-002a-slice-mvp-scope` → `/a-002b-define-user-stories` 実行済み）。
+- `docs/project/02-behavior/` ディレクトリが存在すること（未作成なら本スキルが作成する）。
+- ユーザーが Must 機能の主要な利用シーンを説明できること。
+
+## 手順
+
+### 1. 前提ドキュメントの確認
+
+```bash
+ls -la docs/project/02-behavior/ 2>/dev/null || echo "ディレクトリが存在しません"
+```
+
+`02-mvp-scope.md` の **Must 機能**と `01-product-brief.md` の成功指標・クリティカル制約を読み込み、Core Scenario 化の対象（Must のみ）を把握する。Not Now / Won't は対象にしない。
+
+### 2. テンプレートの準備
+
+このスキルの配置ディレクトリ（`skills/a-003-create-scenarios/`）を起点に、相対パス `../../templates/project/02-behavior/01-core-scenarios.md` を Read で読み込み、その内容を `docs/project/02-behavior/01-core-scenarios.md` へ Write する。出力先が既に存在する場合は上書きせずスキップして報告する（冪等）。出力先ディレクトリ（`docs/project/02-behavior/`）が無ければ作成する。
+
+### 3. Core Flow の抽出と提案
+
+Must 機能から、価値が成立する中核行動の流れ（Core Flow）を 1〜3 本提案する。各フローは「主アクター / 提供価値（So that）/ 対応 Must」で一覧化する。
+
+- 「フロー: [フロー名]（対応 Must: FN-XXX）」
+- 「主アクター: [誰] / 提供価値: [So that ...]」
+
+### 4. Day 1 Happy Path と Critical Failure の記入
+
+`01-core-scenarios.md` を更新する。ユーザーの意図を Given-When-Then で簡潔に書き、UI 操作の詳細には踏み込まない。
+
+- **Day 1 Happy Path**（CS-XXX, 1〜3 本）: リリース初日に必ず通る成功シナリオ。
+- **Critical Failure**（CF-XXX）: 起きると MVP の価値が崩れる失敗だけ（法務・課金・権限・データ消失など）。各失敗に「MVP での扱い」を書く。
+- 網羅したくなったら止める。詳細な境界値・エラー網羅は任意で [reference/detailed-gherkin-template.md](reference/detailed-gherkin-template.md) を使う。
+
+### 5. Not Covered in MVP と SSoT の整合
+
+- **Not Covered in MVP**: MVP で対応しない行動・エラーを明示し、`02-mvp-scope.md` の Not Now / Won't と整合させる。
+- **SSoT の住み分け**: User Story（`05-user-stories.md`）は要約レベルの受け入れ基準（AC）、Core Scenario は実行時の主要行動。同じ振る舞いを二重に詳細化しない。
+
+### 6. レビューと確認
+
+ユーザーに提示し、(1) Day 1 の成功体験が正しいか、(2) Critical Failure に漏れがないか、(3) Not Covered が MVP Scope と矛盾しないかを確認する。質問例は [reference/structure-check.md](reference/structure-check.md#レビュー確認質問) を参照。
+
+### 7. 構造チェック
+
+```bash
+grep "## Day 1 Happy Path" docs/project/02-behavior/01-core-scenarios.md \
+  && grep "## Critical Failure" docs/project/02-behavior/01-core-scenarios.md \
+  && grep "## Not Covered in MVP" docs/project/02-behavior/01-core-scenarios.md \
+  && echo "OK" || echo "MISSING SECTION"
+```
+
+詳細なチェックリストは [reference/structure-check.md](reference/structure-check.md#チェックリスト) を参照。
+
+### 8. Git への追加（任意）
+
+```bash
+git add docs/project/02-behavior/
+git commit -m "docs: Core Scenarios（MVP 主要行動）の作成"
+```
+
+## 完了条件
+
+- `docs/project/02-behavior/01-core-scenarios.md` が作成されている。
+- Must 機能に対する Day 1 Happy Path（1〜3 本）と Critical Failure が記述されている。
+- Not Covered in MVP が明示され、`02-mvp-scope.md` の Not Now / Won't と整合している。
+- User Story と Core Scenario の二重管理が避けられている（要約 AC ↔ 実行時主要行動）。
+- ユーザーが内容を承認している。
+
+## エスカレーション
+
+- **MVP Scope が未確定でシナリオ化できない**: 「`/a-002a-slice-mvp-scope` に戻って Must 機能を確定しましょう。」
+- **全ケースを網羅したくなる**: 「MVP 初期は網羅不要です。価値を壊す Critical Failure に限定し、残りは Not Covered in MVP へ逃がしましょう。詳細 Gherkin はテスト設計時に任意で作成できます。」
+- **実装詳細への依存が強すぎる**: 「UI 操作（ボタンクリック等）ではなくユーザーの意図（登録する等）に焦点を当てた記述に変更しましょう。」
+
+## 参考
+
+- [reference/structure-check.md](reference/structure-check.md) — 構造確認コマンド、チェックリスト、レビュー観点、Git 追加例
+- [reference/detailed-gherkin-template.md](reference/detailed-gherkin-template.md) — （任意）詳細な Gherkin / Scenario Outline / タグ運用テンプレート。実装直前・テスト設計時に使用
+- [examples/gherkin-templates.md](examples/gherkin-templates.md) — （任意）Feature / Scenario / Scenario Outline の記述例、タグ付けガイド