Back to Details

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

工作内容

  1. Read the bug report from 
    tasks/bug-report-*.md
  2. Convert each bug into a user story
  3. Add stories to prd.json (or create new one)
  4. Ensure proper prioritization (critical bugs first)
  1. 读取
    tasks/bug-report-*.md
    中的Bug报告
  2. 将每个Bug转换为用户故事
  3. 将故事添加至prd.json（或创建新文件）
  4. 确保合理的优先级排序（严重Bug优先）

Conversion Rules

转换规则

Bug → User Story Mapping

Bug → 用户故事映射

Bug FieldStory Field
BUG-XXXid: "FIX-XXX"
Titletitle: "Fix: [title]"
Steps to ReproduceGoes into notes
Expected BehaviorPart of description
Actual BehaviorPart of description
SeverityDetermines priority
Bug字段故事字段
BUG-XXXid: "FIX-XXX"
Titletitle: "Fix: [title]"
Steps to Reproduce归入notes字段
Expected Behavior作为description的一部分
Actual Behavior作为description的一部分
Severity决定优先级

Priority Mapping

优先级映射

Bug SeverityStory Priority Range
Critical1-3 (fix immediately)
High4-7
Medium8-12
Low13+
Bug Severity故事优先级范围
Critical1-3（立即修复）
High4-7
Medium8-12
Low13+

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

Step 1: Read Bug Report

bash
undefined
bash
undefined

Find the latest bug report

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

Step 2: Check Existing prd.json

bash
undefined
bash
undefined

Check if prd.json exists and get current state

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
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

Step 3: Decide Integration Strategy

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

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

Step 5: Update prd.json

If adding to existing:
bash
undefined
If adding to existing:
bash
undefined

Backup first

Backup first

cp prd.json prd.json.backup
cp prd.json prd.json.backup

Add new stories (Claude does this programmatically)

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

Step 6: Verify

bash
undefined
bash
undefined

Verify the updated prd.json

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) }'

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

---

Example Conversion

Example Conversion

Input Bug:
markdown
undefined
Input Bug:
markdown
undefined

BUG-003: Form submits with empty required fields

BUG-003: Form submits with empty required fields

Severity: High Type: Functional
Steps to Reproduce:
  1. Go to /signup
  2. Leave all fields empty
  3. 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:
  1. Go to /signup
  2. Leave all fields empty
  3. 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:
  1. Tell the user how many bug fix stories were added
  2. Show the priority distribution
  3. 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转换为故事后：
  1. 告知用户新增了多少个Bug修复故事
  2. 展示优先级分布情况
  3. 询问用户是否要启动Ralph进行修复：
"我已向prd.json中添加了X个Bug修复故事：
  • 严重修复：X个（优先级1-3）
  • 高优先级：X个（优先级4-7）
  • 中优先级：X个（优先级8-12）
  • 低优先级：X个（优先级13+）
是否准备启动Ralph自动修复这些Bug？"
若用户同意，可运行
./ralph.sh
开始修复。