bugs-to-stories

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bugs to Stories Converter

Bug转用户故事转换器

Takes bug reports from the test-and-break skill and converts them into properly formatted user stories that can be added to prd.json for Ralph to fix autonomously.

接收来自test-and-break技能的Bug报告，并将其转换为格式规范的用户故事，添加至prd.json中，供Ralph自动修复。

The Job

工作内容

Read the bug report from
```
tasks/bug-report-*.md
```
Convert each bug into a user story
Add stories to prd.json (or create new one)
Ensure proper prioritization (critical bugs first)

读取
```
tasks/bug-report-*.md
```
中的Bug报告
将每个Bug转换为用户故事
将故事添加至prd.json（或创建新文件）
确保合理的优先级排序（严重Bug优先）

Conversion Rules

转换规则

Bug → User Story Mapping

Bug → 用户故事映射

Bug Field	Story Field
BUG-XXX	id: "FIX-XXX"
Title	title: "Fix: [title]"
Steps to Reproduce	Goes into notes
Expected Behavior	Part of description
Actual Behavior	Part of description
Severity	Determines priority

Bug字段	故事字段
BUG-XXX	id: "FIX-XXX"
Title	title: "Fix: [title]"
Steps to Reproduce	归入notes字段
Expected Behavior	作为description的一部分
Actual Behavior	作为description的一部分
Severity	决定优先级

Priority Mapping

优先级映射

Bug Severity	Story Priority Range
Critical	1-3 (fix immediately)
High	4-7
Medium	8-12
Low	13+

Bug Severity	故事优先级范围
Critical	1-3（立即修复）
High	4-7
Medium	8-12
Low	13+

Story Format

故事格式

json

{
  "id": "FIX-001",
  "title": "Fix: [Descriptive bug title]",
  "description": "As a user, I expect [expected behavior] but currently [actual behavior occurs].",
  "acceptanceCriteria": [
    "[Specific technical fix needed]",
    "[Another fix criterion if needed]",
    "Regression test: Following original bug steps no longer reproduces the issue",
    "Typecheck passes"
  ],
  "priority": 1,
  "passes": false,
  "notes": "Bug reproduction: [steps from bug report]"
}

json

{
  "id": "FIX-001",
  "title": "Fix: [Descriptive bug title]",
  "description": "As a user, I expect [expected behavior] but currently [actual behavior occurs].",
  "acceptanceCriteria": [
    "[Specific technical fix needed]",
    "[Another fix criterion if needed]",
    "Regression test: Following original bug steps no longer reproduces the issue",
    "Typecheck passes"
  ],
  "priority": 1,
  "passes": false,
  "notes": "Bug reproduction: [steps from bug report]"
}

Process

操作流程

Step 1: Read Bug Report

bash

undefined

bash

undefined

Find the latest bug report

ls -t tasks/bug-report-*.md | head -1


Read the bug report and parse each bug entry.

ls -t tasks/bug-report-*.md | head -1


读取Bug报告并解析每个Bug条目。

Step 2: Check Existing prd.json

bash

undefined

bash

undefined

Check if prd.json exists and get current state

if [ -f prd.json ]; then cat prd.json | jq '{ project: .project, totalStories: (.userStories | length), maxPriority: ([.userStories[].priority] | max), incompleteStories: ([.userStories[] | select(.passes == false)] | length) }' fi

undefined

undefined

Step 3: Decide Integration Strategy

Option A: Add to existing prd.json (recommended if original build incomplete)

Append bug fix stories after existing stories
Set priorities to come after current highest priority
Keep original project name and branchName

Option B: Create bug-fix-only prd.json (if original build complete)

Create new prd.json with only bug fix stories
Use branchName:
```
ralph/bugfix-[date]
```
Start priorities at 1

Ask user which approach if unclear.

Option A: Add to existing prd.json (recommended if original build incomplete)

Append bug fix stories after existing stories
Set priorities to come after current highest priority
Keep original project name and branchName

Option B: Create bug-fix-only prd.json (if original build complete)

Create new prd.json with only bug fix stories
Use branchName:
```
ralph/bugfix-[date]
```
Start priorities at 1

若情况不明确，询问用户选择哪种方式。

Step 4: Generate Stories

For each bug in the report:

javascript

// Example conversion
const bugToStory = (bug, priorityOffset) => ({
  id: bug.id.replace('BUG', 'FIX'),
  title: `Fix: ${bug.title}`,
  description: `As a user, I expect ${bug.expected} but currently ${bug.actual}.`,
  acceptanceCriteria: [
    ...generateFixCriteria(bug),
    `Regression test: ${bug.steps.join(' → ')} no longer reproduces the issue`,
    "Typecheck passes"
  ],
  priority: severityToPriority(bug.severity) + priorityOffset,
  passes: false,
  notes: `Original bug steps: ${bug.steps.join('; ')}`
});

针对报告中的每个Bug：

javascript

// Example conversion
const bugToStory = (bug, priorityOffset) => ({
  id: bug.id.replace('BUG', 'FIX'),
  title: `Fix: ${bug.title}`,
  description: `As a user, I expect ${bug.expected} but currently ${bug.actual}.`,
  acceptanceCriteria: [
    ...generateFixCriteria(bug),
    `Regression test: ${bug.steps.join(' → ')} no longer reproduces the issue`,
    "Typecheck passes"
  ],
  priority: severityToPriority(bug.severity) + priorityOffset,
  passes: false,
  notes: `Original bug steps: ${bug.steps.join('; ')}`
});

Step 5: Update prd.json

If adding to existing:

bash

undefined

If adding to existing:

bash

undefined

Backup first

cp prd.json prd.json.backup

Add new stories (Claude does this programmatically)


**If creating new:**
```json
{
  "project": "[Original Project] - Bug Fixes",
  "branchName": "ralph/bugfix-2024-01-15",
  "description": "Bug fixes from automated testing",
  "userStories": [
    // converted bug stories here
  ]
}


**If creating new:**
```json
{
  "project": "[Original Project] - Bug Fixes",
  "branchName": "ralph/bugfix-2024-01-15",
  "description": "Bug fixes from automated testing",
  "userStories": [
    // converted bug stories here
  ]
}

Step 6: Verify

bash

undefined

bash

undefined

Verify the updated prd.json

cat prd.json | jq '{ project: .project, totalStories: (.userStories | length), bugFixStories: ([.userStories[] | select(.id | startswith("FIX"))] | length), allPassesFalse: ([.userStories[] | select(.passes == false)] | length) }'

---

---

Example Conversion

Input Bug:

markdown

undefined

Input Bug:

markdown

undefined

BUG-003: Form submits with empty required fields

Severity: High Type: Functional

Steps to Reproduce:

Go to /signup
Leave all fields empty
Click "Create Account"

Expected Behavior: Form should show validation errors and prevent submission

Actual Behavior: Form submits and shows server error


**Output Story:**
```json
{
  "id": "FIX-003",
  "title": "Fix: Form submits with empty required fields",
  "description": "As a user, I expect the signup form to show validation errors when I leave required fields empty, but currently it submits and shows a server error.",
  "acceptanceCriteria": [
    "Add client-side validation for all required fields",
    "Show inline error messages for empty required fields",
    "Disable submit button until required fields are filled",
    "Regression test: Going to /signup → leaving fields empty → clicking Create Account shows validation errors instead of submitting",
    "Typecheck passes"
  ],
  "priority": 4,
  "passes": false,
  "notes": "Original bug steps: Go to /signup; Leave all fields empty; Click Create Account"
}

Severity: High Type: Functional

Steps to Reproduce:

Go to /signup
Leave all fields empty
Click "Create Account"

Expected Behavior: Form should show validation errors and prevent submission

Actual Behavior: Form submits and shows server error


**Output Story:**
```json
{
  "id": "FIX-003",
  "title": "Fix: Form submits with empty required fields",
  "description": "As a user, I expect the signup form to show validation errors when I leave required fields empty, but currently it submits and shows a server error.",
  "acceptanceCriteria": [
    "Add client-side validation for all required fields",
    "Show inline error messages for empty required fields",
    "Disable submit button until required fields are filled",
    "Regression test: Going to /signup → leaving fields empty → clicking Create Account shows validation errors instead of submitting",
    "Typecheck passes"
  ],
  "priority": 4,
  "passes": false,
  "notes": "Original bug steps: Go to /signup; Leave all fields empty; Click Create Account"
}

After Conversion

转换完成后

Once bugs are converted to stories:

Tell the user how many bug fix stories were added
Show the priority distribution
Ask if they want to start Ralph to fix them:

"I've added X bug fix stories to prd.json:

Critical fixes: X (priority 1-3)

High priority: X (priority 4-7)

Medium priority: X (priority 8-12)

Low priority: X (priority 13+)

Ready to run Ralph to fix these bugs automatically?"

If yes, they can run

./ralph.sh

to start fixing.

将Bug转换为故事后：

告知用户新增了多少个Bug修复故事
展示优先级分布情况
询问用户是否要启动Ralph进行修复：

"我已向prd.json中添加了X个Bug修复故事：

严重修复：X个（优先级1-3）

高优先级：X个（优先级4-7）

中优先级：X个（优先级8-12）

低优先级：X个（优先级13+）

是否准备启动Ralph自动修复这些Bug？"

若用户同意，可运行

./ralph.sh

开始修复。