ralph

Ralph PRD コンバーター

既存の PRD を、Ralph が自律実行に使用する prd.json 形式に変換します。

---

作業内容

PRD（Markdown ファイルまたはテキスト）を受け取り、ralph ディレクトリ内の prd.json に変換します。

---

出力形式

{
	"project": "[Project Name]",
	"branchName": "ralph/[feature-name-kebab-case]",
	"description": "[Feature description from PRD title/intro]",
	"userStories": [
		{
			"id": "US-001",
			"title": "[Story title]",
			"description": "As a [user], I want [feature] so that [benefit]",
			"acceptanceCriteria": ["Criterion 1", "Criterion 2", "Typecheck passes"],
			"priority": 1,
			"passes": false,
			"notes": ""
		}
	]
}

---

ストーリーのサイズ：最も重要なルール

各ストーリーは Ralph の 1 回のイテレーション（1 つのコンテキストウィンドウ）で完了できるサイズにしてください。

Ralph はイテレーションごとに新しい Amp インスタンスを起動し、前回の作業内容は引き継がれません。ストーリーが大きすぎると、LLM は完了前にコンテキストを使い切り、壊れたコードを生成します。

適切なサイズのストーリー：

• データベースのカラムとマイグレーションを追加する
• 既存のページに UI コンポーネントを追加する
• 新しいロジックでサーバーアクションを更新する
• 一覧にフィルターのドロップダウンを追加する

大きすぎるストーリー（分割してください）：

• 「ダッシュボード全体を構築する」— スキーマ、クエリ、UI コンポーネント、フィルターに分割します
• 「認証を追加する」— スキーマ、ミドルウェア、ログイン UI、セッション処理に分割します
• 「API をリファクタリングする」— エンドポイントまたはパターンごとに 1 つのストーリーに分割します

目安： 変更内容を 2～3 文で説明できない場合は、大きすぎます。

---

ストーリーの順序：依存関係を優先する

ストーリーは優先順位順に実行されます。先のストーリーが後のストーリーに依存しないようにしてください。

正しい順序：

1. スキーマ／データベースの変更（マイグレーション）
2. サーバーアクション／バックエンドロジック
3. バックエンドを使用する UI コンポーネント
4. データを集約するダッシュボード／サマリービュー

誤った順序：

1. UI コンポーネント（まだ存在しないスキーマに依存する）
2. スキーマの変更

---

受け入れ条件：検証可能であること

各条件は、曖昧なものではなく、Ralph が確認できるものでなければなりません。

良い条件（検証可能）：

• 「tasks テーブルに、デフォルト値が 'pending' の status カラムを追加する」
• 「フィルターのドロップダウンに、All、Active、Completed の選択肢がある」
• 「削除をクリックすると確認ダイアログが表示される」
• 「型チェックに合格する」
• 「テストに合格する」

悪い条件（曖昧）：

• 「正しく動作する」
• 「ユーザーが X を簡単にできる」
• 「優れた UX」
• 「エッジケースに対応する」

最後の条件として必ず含める：

"Typecheck passes"

テスト可能なロジックを含むストーリーには、次も含めます：

"Tests pass"

UI を変更するストーリーには、次も含めます：

"Verify in browser using dev-browser skill"

フロントエンドのストーリーは、視覚的に検証されるまで完了ではありません。Ralph は dev-browser スキルを使用してページに移動し、UI を操作して、変更が正しく動作することを確認します。

---

変換ルール

1. 各ユーザーストーリーを 1 つの JSON エントリにする
2. ID：連番（US-001、US-002 など）
3. 優先順位：依存関係の順、その後はドキュメントの順
4. すべてのストーリー：passes: false と空の notes
5. branchName：機能名から導出し、kebab-case にして、ralph/ を先頭に付ける
6. 必ず追加する項目：各ストーリーの受け入れ条件に「型チェックに合格する」を追加する

---

大きな PRD の分割

PRD に大きな機能が含まれている場合は、分割します。

元の記述：

「ユーザー通知システムを追加する」

分割後：

1. US-001：データベースに通知テーブルを追加する
2. US-002：通知を送信する通知サービスを作成する
3. US-003：ヘッダーに通知ベルのアイコンを追加する
4. US-004：通知のドロップダウンパネルを作成する
5. US-005：既読にする機能を追加する
6. US-006：通知設定ページを追加する

それぞれが、個別に完了および検証できる、目的を絞った変更です。

---

例

入力 PRD：

# Task Status Feature

Add ability to mark tasks with different statuses.

## Requirements

- Toggle between pending/in-progress/done on task list
- Filter list by status
- Show status badge on each task
- Persist status in database

出力 prd.json：

{
	"project": "TaskApp",
	"branchName": "ralph/task-status",
	"description": "Task Status Feature - Track task progress with status indicators",
	"userStories": [
		{
			"id": "US-001",
			"title": "Add status field to tasks table",
			"description": "As a developer, I need to store task status in the database.",
			"acceptanceCriteria": [
				"Add status column: 'pending' | 'in_progress' | 'done' (default 'pending')",
				"Generate and run migration successfully",
				"Typecheck passes"
			],
			"priority": 1,
			"passes": false,
			"notes": ""
		},
		{
			"id": "US-002",
			"title": "Display status badge on task cards",
			"description": "As a user, I want to see task status at a glance.",
			"acceptanceCriteria": [
				"Each task card shows colored status badge",
				"Badge colors: gray=pending, blue=in_progress, green=done",
				"Typecheck passes",
				"Verify in browser using dev-browser skill"
			],
			"priority": 2,
			"passes": false,
			"notes": ""
		},
		{
			"id": "US-003",
			"title": "Add status toggle to task list rows",
			"description": "As a user, I want to change task status directly from the list.",
			"acceptanceCriteria": [
				"Each row has status dropdown or toggle",
				"Changing status saves immediately",
				"UI updates without page refresh",
				"Typecheck passes",
				"Verify in browser using dev-browser skill"
			],
			"priority": 3,
			"passes": false,
			"notes": ""
		},
		{
			"id": "US-004",
			"title": "Filter tasks by status",
			"description": "As a user, I want to filter the list to see only certain statuses.",
			"acceptanceCriteria": [
				"Filter dropdown: All | Pending | In Progress | Done",
				"Filter persists in URL params",
				"Typecheck passes",
				"Verify in browser using dev-browser skill"
			],
			"priority": 4,
			"passes": false,
			"notes": ""
		}
	]
}

---

前回の実行結果のアーカイブ

新しい prd.json を書き込む前に、別の機能の既存ファイルがないか確認してください。

1. 現在の prd.json があれば読み込みます
2. branchName が新しい機能のブランチ名と異なるか確認します
3. 異なり、かつ progress.txt にヘッダー以外の内容がある場合：
   • アーカイブフォルダーを作成します：archive/YYYY-MM-DD-feature-name/
   • 現在の prd.json と progress.txt をアーカイブにコピーします
   • progress.txt を新しいヘッダーでリセットします

ralph.sh スクリプトは、実行時にこれを自動で処理しますが、実行の合間に手動で prd.json を更新する場合は、先にアーカイブしてください。

---

保存前のチェックリスト

prd.json を書き込む前に、次の項目を確認してください。

• 前回の実行がアーカイブ済み（prd.json が存在し、branchName が異なる場合は、先にアーカイブします）
• 各ストーリーが1回のイテレーションで完了できる（十分に小さい）
• ストーリーが依存関係の順に並んでいる（スキーマからバックエンド、UI の順）
• すべてのストーリーに「Typecheck passes」が基準として含まれている
• UI ストーリーに「Verify in browser using dev-browser skill」が基準として含まれている
• 受け入れ基準が検証可能である（曖昧ではない）
• 後続のストーリーに依存するストーリーがない