Takes a PRD (markdown file or text) and creates a Linear project with properly structured issues.

SKILL.md

name	description
ralph-linear	Convert PRDs into Linear tasks for Ralph autonomous agent system. Use when you have an existing PRD and need to convert it to Linear tasks. Triggers on: turn this into linear tasks, create linear tasks from this, convert to linear, linear issues

PRD to Linear Converter

Takes a PRD (markdown file or text) and creates a Linear project with properly structured issues.

---

What Gets Created

1. A Linear Project — with name, description, icon, and target date from the PRD
2. Issues in that project — one per user story, with title, description, estimate, priority, and dependency links (blocks/blockedBy)

---

Step 1: Ask for Team

Before creating anything, ask which Linear team to use. List available teams with list_teams.

---

Step 2: Create the Project

Use create_project with:

• name: PRD title
• description: 1-2 sentence summary from the PRD
• icon: Pick a relevant emoji (e.g. :chart_with_upwards_trend:, :lock:, :bell:)
• team: The selected team
• priority: Map from PRD priority if present (1=Urgent, 2=High, 3=Medium, 4=Low), default 3
• targetDate: From PRD if specified, otherwise omit
• state: "planned"

---

Step 3: Create Issues

For each user story, use create_issue with:

Field	Value
title	Short, imperative (e.g. "Add status column to tasks table")
description	Markdown body with context + acceptance criteria as a checklist
team	Same team as project
project	The project just created
priority	1-4 based on dependency order (earlier = higher priority)
estimate	Story points: 1 (trivial), 2 (small), 3 (medium), 5 (large)

Description Template

## Context
[1-2 sentences about what this story does and why]

## Acceptance Criteria
- [ ] [Specific, verifiable criterion]
- [ ] [Another criterion]
- [ ] Typecheck passes

For UI stories, also add:

- [ ] Verify in browser using `agent-browser` OR `dev-browser` skill (whichever is available)

---

Step 4: Link Dependencies

After all issues are created, use update_issue to set dependency links:

• blocks: Issue IDs that cannot start until this one is done
• blockedBy: Issue IDs that must complete before this one starts

Example: Schema issue blocks the API issue. API issue blocks the UI issue.

---

Story Size: The Number One Rule

Each story must be completable in ONE Ralph iteration (one context window).

Ralph spawns a fresh LLM instance per story with no memory of previous work. Too-big stories cause broken output.

Right-sized:

• Add a database column and migration
• Add a UI component to an existing page
• Update a server action with new logic
• Add a filter dropdown to a list

Too big (split these):

• "Build the entire dashboard" → schema, queries, UI components, filters
• "Add authentication" → schema, middleware, login UI, session handling
• "Refactor the API" → one story per endpoint or pattern

Rule of thumb: If you cannot describe the change in 2-3 sentences, split it.

---

Story Ordering: Dependencies First

Stories execute in priority order. Earlier stories must not depend on later ones.

Correct order:

1. Schema/database changes (migrations)
2. Server actions / backend logic
3. UI components that use the backend
4. Dashboard/summary views that aggregate data

---

Acceptance Criteria: Must Be Verifiable

Good (verifiable):

• "Add status column to tasks table with default 'pending'"
• "Filter dropdown has options: All, Active, Completed"
• "Clicking delete shows confirmation dialog"
• "Typecheck passes"

Bad (vague):

• "Works correctly"
• "User can do X easily"
• "Good UX"

Always include:

• Typecheck passes on every story
• Tests pass on stories with testable logic
• Verify in browser using dev-browser skill on UI stories

---

Splitting Large PRDs

Original: "Add user notification system"

Split into:

1. Add notifications table to database
2. Create notification service for sending notifications
3. Add notification bell icon to header
4. Create notification dropdown panel
5. Add mark-as-read functionality
6. Add notification preferences page

Each is one focused change, completable and verifiable independently.

---

Estimation Guide

Points	Scope
1	Config change, add a column, rename something
2	Single component, single endpoint, single migration with logic
3	Component + server action, endpoint with validation
5	Multi-file feature slice (but still one coherent change)

If a story feels like an 8, split it.

---

Example

Input 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

Output: Linear Project + Issues

Project: "Task Status Feature" with description "Track task progress with status indicators" and icon :traffic_light:

Issues created:

1. Add status field to tasks table (priority: 2/High, estimate: 2)

   • Acceptance: Add status column enum, generate migration, typecheck passes
   • Blocks: issues 2, 3, 4

2. Display status badge on task cards (priority: 3/Normal, estimate: 2)

   • Acceptance: Colored badge per status, typecheck passes, verify in browser
   • Blocked by: issue 1

3. Add status toggle to task list rows (priority: 3/Normal, estimate: 3)

   • Acceptance: Dropdown on each row, saves immediately, no page refresh, typecheck passes, verify in browser
   • Blocked by: issue 1

4. Filter tasks by status (priority: 3/Normal, estimate: 3)

   • Acceptance: Filter dropdown with all options, persists in URL params, typecheck passes, verify in browser
   • Blocked by: issue 1

---

Checklist Before Creating

• Asked user which team to use
• Each story is completable in one iteration
• Stories ordered by dependency (schema → backend → UI)
• Every story has "Typecheck passes"
• UI stories have "Verify in browser using dev-browser skill"
• Acceptance criteria are verifiable (not vague)
• No story depends on a later story
• Estimates assigned (1, 2, 3, or 5)
• Dependencies will be linked after creation