planning-stories

ストーリーの計画

ユーザーストーリーを、個別にテスト可能なタスクに分割します。各タスクは小さく、検証可能な作業単位であり、完了するとストーリー全体の完了に貢献します。

---

⚠️ 2 つのモード — まずお読みください

このスキルは2 つのモードで動作します。作業を始める前に、どちらのモードか確認してください。

1. デフォルト — ストーリーの計画（通常はこちら）

STORY.<name>.md 計画ファイル（および任意で STORY.<name>.TECH-SPEC.md）を作成します。これは人間が読む計画成果物です。自律的には実行されません。ユーザーがストーリーの計画、分割、または細分化を依頼した場合は、常にこのモードを使用します。

2. 明示的な依頼があった場合のみ — Ralph タスクの生成

Ralph ループ用ファイル（<task-name>.TASK.md + <task-name>.progress.txt）を作成します。ralph.sh スクリプトが、各イテレーションで 1 つのストーリーを自律的に実行します。

重要なルール

ユーザーから明示的な依頼がない限り、Ralph タスクファイルを生成してはいけません。 次のような直接的な依頼があった場合にのみ実行します。

• 「これを Ralph タスクに分割して」
• 「.TASK.md ファイルを生成して」
• 「Ralph で実行できるようにして」／「これを ralph に通して」
• 「ralph ループ用のタスク分解を作成して」

通常のストーリー作成時に、.TASK.md／.progress.txt ファイルを出力してはいけません。STORY.<name>.md の計画タスク（以下のステップ 1〜5）を作成することは問題なく、想定どおりです。これは計画であり、Ralph による実行ではありません。

モード 2 が明示的に依頼された場合は、ralph-tasks.md の完全なワークフローに従ってください。

---

作業内容

デフォルトモード（ストーリーの計画）：

1. ユーザーからストーリーの説明を受け取る
2. 必要に応じて確認の質問をする
3. ストーリーを小さく、テスト可能なタスクに分割する
4. STORY.<name>.md に保存する
5. writing-tech-specs サブエージェントを起動して STORY.<name>.TECH-SPEC.md を作成する

Ralph モード（明示的な依頼があった場合のみ）： ralph-tasks.md に従い、ストーリーファイルと同じ場所に <task-name>.TASK.md + <task-name>.progress.txt を生成します。明示的な依頼がない限り、このモードに入ってはいけません（上記の重要なルールを参照）。

---

基本原則

タスクの独立性

各タスクは、次の条件を満たす必要があります。

• 単独で完了できる — 未完了のタスクに依存しない
• テスト可能である — 明確な検証基準がある
• 既存機能を壊さない — 各タスクの完了後もアプリが動作する
• 小さい — 1 つのコンテキストウィンドウ内（AI の作業時間で約 10 分）に完了できる

タスクの順序（重要）

変更による不具合を避けるため、必ず依存関係の順に並べてください。

1. データベース／スキーマの変更 — マイグレーション、新しいカラム、新しいテーブル
2. バックエンド／リポジトリ層 — データアクセス、クエリ、変更処理
3. API／サービス層 — エンドポイント、ビジネスロジック
4. フロントエンド／UI — コンポーネント、画面、フォーム

順序を誤るとビルドが壊れます！

---

ステップ 1：ストーリーを分析する

ユーザーが何を求めているかを把握します。

• 新機能：新しい機能を追加する
• 更新／変更：既存の動作を変更する
• バグ修正：誤った動作を修正する
• リファクタリング：動作を変えずにコードを改善する

次の場合は確認の質問をする

• スコープが不明確
• 複数の解釈が可能
• 破壊的変更のリスクがある
• テスト戦略が曖昧

確認の質問の例

- "What should happen when [edge case]?"
- "Is this a breaking change, or should existing behavior still work?"
- "Are there any constraints on [field/feature]?"
- "Should this work for all users or just [specific role]?"
- "What's the rollback strategy if something goes wrong?"

---

ステップ 2：タスクに分割する

詳細な分割パターンについては、examples.md を参照してください。

クイックリファレンス

ストーリーの種類	タスクの順序
新しいフィールド	DB → Repository → API → Frontend
フィールドの更新	並行して追加 → バックエンド → フロントエンド → 古いものを削除
新しいエンティティ	DB → Repository → API → 一覧 UI → 詳細 UI
バグ修正	原因を特定 → テストを追加 → 修正 → 検証

---

ステップ 3：検証基準を定義する

各タスクには、テスト可能な検証基準を必ず設定してください。

良い基準（検証可能）

- [ ] Migration runs successfully
- [ ] Unit test: new column exists with correct type
- [ ] Typecheck passes
- [ ] App starts without errors

悪い基準（曖昧）

- [ ] Works correctly
- [ ] User can see the change
- [ ] Good UX

すべてのタスクに必須の基準

- [ ] Typecheck passes
- [ ] All tests pass
- [ ] App runs without errors

BDD 形式（任意、複雑なフロー向け）

Given [context]
When [action]
Then [expected result]

---

ステップ 4：STORY..md を生成する

ファイル命名規則

• 大文字の STORY プレフィックスとケバブケースの名前を使用します：STORY.add-user-profile-picture.md
• 冠詞「the」「a」「an」を削除します
• 説明的でありながら簡潔な名前にします

テンプレート構成

# Story: [Title]

## Overview

[Brief description of what this story accomplishes]

## Dependencies

- [List any existing features/systems this depends on]
- [None if standalone]

---

## Tasks

### Task 1: [Title]

**Layer:** database | backend | api | frontend | cleanup

**Description:**
[What this task does]

**Changes:**
- [Specific file/table/function being changed]

**Verification:**
- [ ] [Specific testable criterion]
- [ ] Typecheck passes
- [ ] All tests pass
- [ ] App runs without errors

---

### Task 2: [Title]

[Same structure as Task 1]

---

## Completion Criteria

The story is complete when:

- [ ] All tasks are verified complete
- [ ] End-to-end flow works as expected
- [ ] No breaking changes to existing functionality

## Rollback Plan

[If something goes wrong, how to revert]

---

## Notes

[Any additional context, assumptions, or decisions made]

---

ステップ 5：writing-tech-specs サブエージェントを起動する

STORY.<name>.md の作成後、サブエージェントを起動して技術仕様を作成します。

サブエージェントのプロンプトテンプレート

Read the file STORY.<name>.md and use the writing-tech-specs skill to create a detailed technical specification.

The tech-spec should include:
1. Model changes (database schema)
2. Flow diagrams (backend/frontend flows)
3. API endpoints
4. Happy path description
5. Backwards compatibility notes

Save the output to STORY.<name>.TECH-SPEC.md

注： 技術仕様ファイルにはストーリーファイルと同じ <name> を使用し、末尾に .TECH-SPEC.md を付けます。たとえば、ストーリーが STORY.add-user-auth.md の場合、技術仕様ファイルは STORY.add-user-auth.TECH-SPEC.md になります。

注： writing-tech-specs スキルが利用できない場合は、このステップを省略し、その旨をストーリーファイルに記載してください。

---

ステップ 6（任意 — 明示的に依頼された場合のみ）：Ralph タスクファイルを生成する

ユーザーが Ralph ループのタスクファイルを明示的に依頼した場合にのみ、このステップを実行してください。 依頼がなければ、ここで停止します。ストーリーの計画は完了です。

明示的に依頼された場合は、ralph-tasks.md に記載されている Ralph ワークフローに切り替え、次のファイルを生成します。

• <task-name>.TASK.md — タスクの分解ドキュメント
• <task-name>.progress.txt — 空の進捗追跡ファイル

デフォルトでは、どちらのファイルもストーリーファイルと同じ場所に作成します。また、<task-name> は task-<number>-<description> の命名規則に従う必要があります（例：task-1-add-currency-table.TASK.md）。その後、ユーザーが ralph.sh <task-name>.TASK.md を実行します。

注意： このステップはオプトインです。通常のストーリー計画では、これらのファイルを決して生成しないでください。

---

分解しない場合

次の条件を満たす場合、ストーリーは単一のタスクとして適切です。

• 変更対象が単一のファイルまたはコンポーネントである
• データベースの変更がない
• API の変更がない
• 30 分未満で完了できる
• 検証方法が 1 つだけである

この場合は、サブタスクに分解せず、ストーリーファイルを作成するだけにしてください。

---

避けるべきアンチパターン

アンチパターン	問題
細かすぎる	「ファイルを作成」「インポートを追加」などは実際のタスクではありません
範囲が広すぎる	「機能を実装」では、1 回の作業で検証できません
レイヤーの混在	1 つのタスクでデータベースとフロントエンドを扱っています
曖昧な検証	「正しく動作する」では、どう確認すればよいか分かりません
ロールバックの欠如	データベースのマイグレーションを元に戻す方法がありません
依存関係の逆転	タスク 2 がタスク 5 に依存しています

---

よくあるパターン

詳細なパターンについては、patterns.md を参照してください。

• 新しいフィールドの追加
• 既存フィールドの更新
• 新しいエンティティの追加
• 新しいリレーションシップの追加

---

トラブルシューティング

問題	解決策
ストーリーの規模が大きすぎる	小さなサブタスクに分解するか、複数のストーリーに分割します
破壊的変更が検出された	まず並行するフィールドまたはエンドポイントを追加し、フロントエンドを更新してから、古いものを削除します
テスト戦略が不明確	ユーザーに詳細を確認し、手動の検証手順を追加します

---

保存前のチェックリスト

• ストーリーが、小さくテスト可能なタスクに分解されている
• 各タスクに明確なレイヤー（database/backend/api/frontend）が指定されている
• タスクが依存関係の順に並んでいる（前方依存がない）
• 各タスクに具体的な検証基準がある
• すべてのタスクに、型チェック、テスト、アプリの実行確認が含まれている
• 破壊的変更には、並行フィールドまたは段階的なロールアウトを使用している
• 完了基準がストーリー全体を網羅している
• ロールバック計画がある
• ファイル名が STORY.<name>.md になっている
• Ralph の .TASK.md／.progress.txt ファイルを生成していない（ユーザーから明示的に依頼された場合を除く）