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": ""
    }
  ]
}

---

ストーリーサイズ: 最重要ルール

各ストーリーはONEのRalph iteration(1つのコンテキストウィンドウ)で完了できる必要があります。

Ralphは反復ごとに新しいAmpインスタンスを生成し、以前の作業についてメモリを保持しません。ストーリーが大きすぎる場合、LLMが完了する前にコンテキストを使い果たし、壊れたコードが生成されます。

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

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

大きすぎる(分割すること):

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

経験則: 変更を2～3文で説明できない場合、それは大きすぎます。

---

ストーリー順序: 依存関係を最初に

ストーリーは優先度順に実行されます。初期のストーリーは後のストーリーに依存しない必要があります。

正しい順序:

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

間違った順序:

1. UIコンポーネント(まだ存在しないスキーマに依存)
2. スキーマ変更

---

受け入れ基準: 検証可能である必要があります

各基準はRalphが「確認」できるもので、曖昧でないものである必要があります。

良い基準(検証可能):

• 「tasksテーブルにstatusカラムを追加、デフォルト'pending'」
• 「フィルタドロップダウンにオプション: All、Active、Completed」
• 「削除をクリックすると確認ダイアログが表示される」
• 「Typecheck passes」
• 「Tests pass」

悪い基準(曖昧):

• 「正しく動作する」
• 「ユーザーが簡単に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. 常に追加: 各ストーリーの受け入れ基準に「Typecheck passes」を追加

---

大規模なPRDの分割

PRDに大きな機能がある場合は分割します:

元々:

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

分割後:

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

各々は、独立して完了し、検証できるフォーカスされた変更です。

---

例

入力PRD:

# Task Status Feature

タスクに異なるステータスをマークする機能を追加。

## Requirements
- タスクリストでpending/in-progress/doneを切り替え
- ステータスでリストをフィルタ
- 各タスクに状態バッジを表示
- ステータスをデータベースに保存

出力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. 異なる AND 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」を基準として持っている
• 受け入れ基準が検証可能である(曖昧でない)
• ストーリーが後のストーリーに依存していない