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'”
• “筛选下拉菜单包含以下选项：All、Active、Completed”
• “点击删除时显示确认对话框”
• “类型检查通过”
• “测试通过”

不良标准（模糊）：

• “运行正常”
• “用户可以轻松完成 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. 始终添加：“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

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”列为验收标准
• 验收标准可验证（不含模糊表述）
• 没有故事依赖后续故事