ralph

Ralph PRD Converter

既存の 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：通知設定ページを追加する

各ストーリーは焦点を絞った変更 1 つであり、個別に完了して検証できます。

---

例

入力 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」が基準として含まれている
• 受け入れ基準が検証可能である（曖昧ではない）
• 後続のストーリーに依存するストーリーがない