ralph

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ralph PRD Converter

Ralph PRD 转换器

Converts existing PRDs to

prd.json

for Ralph's autonomous execution loop.

将现有PRD转换为供Ralph自治执行循环使用的

prd.json

文件。

The Job

任务内容

Run Pre-flight Setup, then convert a PRD (markdown or text) into

scripts/ralph/prd.json

先运行前置准备步骤，再将PRD（markdown或文本格式）转换为

scripts/ralph/prd.json

文件。

Pre-flight Setup

前置准备

Project name — read
```
package.json
```
```
name
```
field; fall back to directory basename.
Copy runtime files — if missing in target project, copy from this skill's
```
ralph/
```
subdirectory to
```
scripts/ralph/
```
:
- ```
ralph.sh
```
  ,
```
ralph-tree.sh
```
  →
```
chmod +x
```
- ```
CLAUDE.md
```
- ```
ralph-audit.ts
```
Set NTFY_TOPIC — in
```
scripts/ralph/ralph.sh
```
, replace
```
<project-name>
```
placeholder with actual project name. Skip if already customized.

Add package.json scripts — if

package.json

exists, add missing entries:

"ralph-tree": "bash scripts/ralph/ralph-tree.sh"

"ralph-audit": "bun scripts/ralph/ralph-audit.ts"

Verify curl — required by ralph.sh for ntfy.sh notifications.
Confirm setup — print summary: file status, NTFY_TOPIC, curl availability.

项目名称 — 读取
```
package.json
```
的
```
name
```
字段；若不存在则使用目录的基础名称。
复制运行时文件 — 如果目标项目中缺少以下文件，从本skill的
```
ralph/
```
子目录复制到
```
scripts/ralph/
```
目录：
- ```
ralph.sh
```
  、
```
ralph-tree.sh
```
  → 执行
```
chmod +x
```
  赋予执行权限
- ```
CLAUDE.md
```
- ```
ralph-audit.ts
```
设置NTFY_TOPIC — 在
```
scripts/ralph/ralph.sh
```
文件中，将
```
<project-name>
```
占位符替换为实际的项目名称。如果已经自定义过则跳过该步骤。

添加package.json脚本 — 如果存在

package.json

文件，添加缺失的脚本条目：

"ralph-tree": "bash scripts/ralph/ralph-tree.sh"

"ralph-audit": "bun scripts/ralph/ralph-audit.ts"

验证curl — ralph.sh需要依赖curl来发送ntfy.sh通知，请确保curl已安装。
确认设置完成 — 打印汇总信息：文件状态、NTFY_TOPIC配置、curl可用性。

Output Format

输出格式

json

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

json

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

Story Size — The Number One Rule

用户故事规模 — 首要规则

Each story must be completable in ONE Ralph iteration (one context window). Ralph spawns a fresh instance per iteration with no memory of previous work.

Right-sized: add a DB column, add a UI component, update a server action, add a filter. Too big (split): "build the dashboard", "add auth", "refactor the API".

Rule of thumb: if you can't describe the change in 2-3 sentences, split it.

每个用户故事必须能在**一次Ralph迭代（一个上下文窗口）**内完成。Ralph每次迭代都会生成全新的实例，不会保留之前工作的记忆。

合理规模： 新增一个数据库列、添加一个UI组件、更新一个服务端动作、新增一个过滤器。 规模过大（需要拆分）： "构建仪表盘"、"添加认证功能"、"重构API"。

经验法则：如果你无法用2-3句话描述清楚改动，就需要拆分。

Story Ordering

故事排序

Dependencies first: schema/migrations → backend logic → UI components → aggregation views.

优先处理依赖项：schema/数据库迁移 → 后端逻辑 → UI组件 → 聚合视图。

Acceptance Criteria

验收标准

Must be verifiable — something Ralph can CHECK.

Good: "Add

status

column with default 'pending'", "Filter has options: All, Active, Done", "Typecheck passes" Bad: "Works correctly", "Good UX", "Handles edge cases"

Always include

"Typecheck passes"

as final criterion. Add

"Tests pass"

for testable logic. Add

"Verify in browser using dev-browser skill"

for UI changes.

必须是可验证的 — 是Ralph能够检查的内容。

正面示例： "新增

status

列，默认值为'pending'"、"过滤器包含选项：全部、活跃、已完成"、"类型检查通过" 反面示例： "运行正常"、"用户体验良好"、"处理边界情况"

必须始终将

"Typecheck passes"

作为最终验收标准。可测试逻辑需添加

"Tests pass"

标准。 UI改动需添加

"Verify in browser using dev-browser skill"

标准。

Conversion Rules

转换规则

Each user story → one JSON entry
IDs: sequential
```
US-001
```
,
```
US-002
```
, ...
Priority: dependency order, then document order
All stories:
```
passes: false
```
, empty
```
notes
```
branchName: kebab-case from feature name, prefixed
```
ralph/
```
Every story gets
```
"Typecheck passes"
```
criterion

每个用户故事对应一条JSON条目
ID：按顺序编号为
```
US-001
```
、
```
US-002
```
……
优先级：先按依赖顺序排列，再按文档原顺序排列
所有故事的
```
passes
```
字段均设为
```
false
```
，
```
notes
```
字段为空
branchName：由功能名转换为kebab-case格式，前缀为
```
ralph/
```
每个故事都必须包含
```
"Typecheck passes"
```
验收标准

Splitting Large PRDs

大型PRD拆分

Break big features into focused, independent stories. Example: "Add notification system" becomes: 1) notifications table, 2) notification service, 3) bell icon, 4) dropdown panel, 5) mark-as-read, 6) preferences page.

See

references/example.md

for a full input/output conversion example.

将大型功能拆分为聚焦、独立的用户故事。示例："新增通知系统"可拆分为：1) 通知表结构、2) 通知服务、3) 铃铛图标、4) 下拉面板、5) 标记已读功能、6) 偏好设置页面。

可查看

references/example.md

获取完整的输入/输出转换示例。

Archiving Previous Runs

历史运行记录归档

Before writing new

prd.json

, check for an existing one with a different

branchName

. If different and

progress.txt

has content beyond the header: archive to

archive/YYYY-MM-DD-feature-name/

, then reset

progress.txt

写入新的

prd.json

之前，检查是否存在旧的

prd.json

且其

branchName

与当前不同。如果分支名不同，且

progress.txt

除了头部外还有其他内容：将其归档到

archive/YYYY-MM-DD-feature-name/

目录，然后重置

progress.txt

。