prd-to-tasks

prd-to-tasks — PRD.md → executable task list

This skill turns a PRD into a flat, ordered list of tasks small enough to be picked up by a developer or an AI executor. The output is .workflow/tasks.md — Markdown with - [ ] checkboxes — designed to be:

• Readable by humans as a project punch-list.
• Importable into beads (the gstack convention), GitHub Issues (one task per issue), or fed to ralph-tui as the task source.
• Pushable to the project's tracker (Linear, Jira or GitHub) via the scrum skill (Setup mode), which creates one issue per task — not a CSV import.
• Atomic enough that each line items represents 2–8 hours of work for a typical developer (or one focused session for an AI agent).

When this skill applies

• A .workflow/PRD.md exists and phase is prd_drafted.
• The user asks to "make the issues", "split the PRD", "create the task list", "ticket this".
• The orchestrator routes here from prd_drafted (optional next step before scaffolding).

If .workflow/tasks.md already exists, enter revise mode: read the existing tasks and propose specific edits (add, remove, re-order, re-size) rather than overwriting. A new task cites the PRD story it serves, the ## Scope changes row that let it in, or the debt-audit finding it fixes (debt:<id>, from .workflow/debt/findings.json — debt is work on what was already promised, not new scope) — a task that serves none is a scope change and passes prd-from-idea/references/scope-check.md first. A cut task is not deleted: it stays, struck through, ~~…~~ cut <date>: <reason>, so what was planned remains readable.

Contract

This skill follows the dev-flow contract — see references/contracts.md for the canonical schema. Key facts:

• Reads <root>/.workflow/PRD.md (mandatory) and .workflow/PROJECT.md (for stack/audience context).
• Writes <root>/.workflow/tasks.md.
• Sets phase = "tasks_split" on success (only if current phase is earlier in the enum).

Workflow

Step 1 — Read inputs and decide structure

Read .workflow/PRD.md. Extract:

• The list of user stories (As a … I want … so that …).
• The acceptance criteria for each story.
• Any non-goals (these become negative tasks: explicit "do NOT do X" notes, not work items).
• Technical constraints (e.g., "must use Postgres" → tasks like "set up Drizzle + Neon" go on the list early).

Group tasks into epics when there are 3+ user stories. With fewer stories, keep a flat list.

Step 2 — Decompose each user story into tasks

For each user story, ask: "What must exist for the acceptance criteria to be true?" Walk down from there:

1. Data layer — DB schemas, migrations, seed data.
2. API / server logic — endpoints, server actions, validation, auth checks.
3. UI — pages/routes, components, states (loading/empty/error).
4. Auth & permissions — who can access this, what guards exist.
5. Telemetry & error handling — logging, error boundaries, user-visible errors.
6. Tests — unit + integration where applicable; explicit task even if "smoke test only".

Skip layers the story doesn't actually need. A purely UI story doesn't need a DB task.

Sizing target: each task ≈ 2–8 hours of focused work. If a task feels bigger, split. If a task is < 1 hour, merge with a sibling.

Title convention: imperative verb first ("Add user-settings page", "Wire login flow", "Set up Drizzle schema for posts"). Avoid "Implement X" — too vague.

Step 3 — Write tasks.md

Use this exact format:

# <Project Name> — Tasks

> Generated by `prd-to-tasks` from PRD.md on <ISO date>. Compatible with beads, GitHub Issues import, `scrum` (Linear, Jira or GitHub), ralph-tui task source.

## Setup

- [ ] **Set up Next.js + shadcn scaffold** *(addressed by `design-md-to-app`)*
- [ ] **Configure Drizzle + Neon** *(addressed by `module-add db`)*
- [ ] **Wire better-auth + email/password** *(addressed by `module-add auth`)*

## Epic: <user-story name or epic title>

### US-1: As a <persona>, I want <action>, so that <outcome>

- [ ] **<Imperative title>** — <one-sentence body>
  - Acceptance: <bulleted criteria pulled from PRD>
  - Files likely touched: `<best-guess paths>`
  - Estimated: <2-8h>
  - Priority: <P1|P2|P3>
- [ ] **<Imperative title>** — …

### US-2: ...

…

## Non-goals (do NOT do)

- <Item from PRD non-goals>
- <Item from PRD non-goals>

## Open questions

- <Question pulled from PRD's "Open questions" section>

Rules:

• One ## Epic: heading per epic, one ### US-N: per user story.
• One - [ ] per concrete task. Sub-bullets under it are details, not separate tasks.
• The *(addressed by …)* annotation marks tasks that are owned by another dev-flow skill — the user (or orchestrator) doesn't have to write code for these, just invoke the right skill. Always tag scaffolding/setup tasks with which skill owns them.
• Order: Setup first (foundation), then epics in priority order from the PRD.
• Priority: on every task — P1 what the first release cannot ship without (Setup and the MVP's must-have stories), P2 the rest of the MVP, P3 what can slip past it. scrum turns it into the tracker's priority (on GitHub the priority: Pn label, the user's rule) and packs the sprints by it.
• Don't enumerate [ ] checkboxes for sub-bullets — they're details, not actionable items.
• The - [ ] <Title> — <body> format (with the em-dash — separator) is load-bearing. scrum/scripts/task_key.py parses each task line with split(" — ")[0] to derive the title it hashes for dedup (meta.json#tracker.issue_map). Do not swap the em-dash for a hyphen, colon, or any other separator — doing so breaks re-run idempotency in scrum.

Step 4 — Update state and report

Update .workflow/meta.json:

• if current phase is earlier than tasks_split, set phase = "tasks_split"
• bump updated_at
• append history:

  {
    "skill": "prd-to-tasks",
    "ran_at": "<now>",
    "outputs": ["tasks.md"],
    "phase_before": "<prev>",
    "phase_after": "tasks_split"
  }
  

Tell the user:

• Number of epics + tasks generated.
• Any open questions still flagged.
• Next-step proposal: usually figma-to-design-md (if not yet run and Figma exists) or design-md-to-app (if DESIGN.md is in place), or scrum (Setup) to run the project as agile scrum on the tracker chosen in the PRD (Linear, Jira or GitHub).

If the user wants to move tasks into beads/GitHub Issues/Linear, point at the file — it's already in the right shape. They can use gh issue create per task, ralph-tui-create-beads / ralph-tui-create-json skills if installed, or invoke scrum (Setup mode) to push tasks.md to the chosen tracker (Linear, Jira or GitHub) — not a CSV import.

Important constraints

• Don't invent acceptance criteria. If the PRD doesn't specify them for a story, ask the user before writing tasks for that story. A task with vague acceptance is worse than no task.
• Don't generate a 100-task list from a 3-story MVP. If the math gives you more than ~15 tasks, you're over-decomposing. Merge.
• Don't include tasks for non-goals. They're explicitly out of scope. List them under ## Non-goals so they stay visible but not actionable.
• Tag setup tasks with the owning skill. "Set up auth" should always say *(addressed by module-add auth)* — this is the bridge between the task list and the skill ecosystem.
• One file, one project. Don't shard tasks.md across multiple files.