bugs-to-stories

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)

---

Bug → User Story Mapping

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

Priority Mapping

| Bug Severity | Story Priority Range |

|--------------|---------------------|

| Critical | 1-3 (fix immediately) |

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

}

```

---

Step 1: Read Bug Report

```bash

# Find the latest bug report

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

```

Read the bug report and parse each bug entry.

Step 2: Check Existing prd.json

```bash

# 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

```

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.

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

});

```

Step 5: Update prd.json

If adding to existing:

```bash

# 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

]

}

```

Step 6: Verify

```bash

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

}'

```

---

Input Bug:

```markdown

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"

}

```

---

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.