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 迭代（一个上下文窗口）内完成。

Ralph 每次迭代都会启动一个全新的 Amp 实例，不会记得之前的工作。如果故事太大，大模型会在完成前耗尽上下文，导致生成的代码无法正常工作。

合适规模的故事：

• 添加数据库列和迁移
• 向现有页面添加 UI 组件
• 使用新逻辑更新服务端操作
• 向列表添加筛选下拉菜单

规模过大的故事（请拆分）：

• “构建整个仪表板”——拆分为：架构、查询、UI 组件、筛选器
• “添加身份验证”——拆分为：架构、中间件、登录 UI、会话处理
• “重构 API”——按端点或模式拆分，每个故事负责一个

**经验法则：**如果无法用 2–3 句话描述变更，说明规模太大。

---

故事排序：优先处理依赖项

故事按优先级顺序执行。较早的故事不能依赖较晚的故事。

正确顺序：

1. 架构／数据库变更（迁移）
2. 服务端操作／后端逻辑
3. 使用后端的 UI 组件
4. 汇总数据的仪表板／摘要视图

错误顺序：

1. UI 组件（依赖尚不存在的架构）
2. 架构变更

---

验收标准：必须可验证

每项标准都必须是 Ralph 可以检查的内容，而不是含糊的描述。

合适的标准（可验证）：

• “向 tasks 表添加 status 列，默认值为 'pending'”
• “筛选下拉菜单包含以下选项：全部、进行中、已完成”
• “点击删除后显示确认对话框”
• “类型检查通过”
• “测试通过”

不合适的标准（含糊）：

• “正常工作”
• “用户可以轻松地完成 X”
• “良好的用户体验”
• “处理边界情况”

始终将以下内容作为最后一项标准：

"Typecheck passes"

对于包含可测试逻辑的故事，还应包括：

"Tests pass"

对于会变更 UI 的故事，还应包括：

"Verify in browser using dev-browser skill"

前端故事只有在经过视觉验证后才算完成。Ralph 会使用 dev-browser 技能打开页面、与 UI 交互，并确认变更有效。

---

转换规则

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 不同，请先归档）
• 每个故事都可在一次迭代中完成（规模足够小）
• 故事已按依赖关系排序（从 schema 到后端再到 UI）
• 每个故事都将“Typecheck passes”列为验收标准
• UI 故事将“Verify in browser using dev-browser skill”列为验收标准
• 验收标准可验证（不含模糊表述）
• 没有故事依赖后续故事