issue-to-tasks

name	issue-to-tasks
description	Break an issue file into concrete, ordered, AI-executable tasks. Use when the user wants to implement an issue, start work on a ticket, or break down an issue into smaller steps.

Issues to Tasks

Break a single vertical-slice issue into concrete, ordered tasks that can each be completed in one focused AI session.

Process

1. Locate the issue

Ask the user for the issue. If not provided, ask for the issue number or URL or file. Read the parent PRD issue referenced in the "Parent PRD" field.

2. Explore the codebase

Explore the parts of the codebase touched by this issue. Focus on:

• Files and modules that will be created or modified
• Existing patterns to follow (naming conventions, error handling, test structure)
• Any interfaces or contracts this issue must respect

3. Draft the task list

Break the issue into ordered tasks. Each task must:

• Be completable in a single AI session (one focused prompt exchange)
• Have a clear, verifiable output (a file, a passing test, a working endpoint)
• Follow the dependency order: schema before logic, logic before API, API before UI, tests alongside or immediately after each layer

Label each task with its type:

• WRITE: create or modify production code
• TEST: write or update tests
• MIGRATE: schema or data migration
• CONFIG: environment, tooling, or infrastructure change
• REVIEW: human decision required before proceeding

Prefer WRITE and TEST tasks interleaved over a block of WRITE followed by a block of TEST.

4. Quiz the user

Present the proposed task list as a numbered list. For each task show:

• Title: short imperative description (e.g. "Add user_id column to sessions table")
• Type: WRITE / TEST / MIGRATE / CONFIG / REVIEW
• Output: what exists or passes when this task is done
• Depends on: task numbers that must complete first

Ask the user:

• Does the order feel right?
• Are any tasks too large to complete in one session?
• Are any tasks so small they should be merged?
• Are all REVIEW tasks correctly identified?

Iterate until the user approves the list.

5. Write the task file

Save the approved task list to a file in the format and location specified by the user.

Use the task file template below.

--- artifact: tasks id: -tasks title: Tasks for : status: not-started # not-started | in-progress | done created: ---

Tasks for #:

Parent issue: # Parent PRD: #

Tasks

. [ ]

Type: WRITE / TEST / MIGRATE / CONFIG / REVIEW
Output:
Depends on: <task numbers or "none">

<A short paragraph describing exactly what to do. Written as an instruction to the AI that will execute it. Include: which files to touch, which pattern to follow, which existing code to use as reference. Do NOT include code snippets — describe intent, not implementation.>

---

Status Frontmatter Contract

All planning artifacts (features, issues, tasks) share one minimal frontmatter: exactly artifact, id, title, status, created — nothing more. Relationships (parent issue, parent PRD) and task progress live in the document body. Rules:

• status uses exactly not-started, in-progress, or done — no other vocabulary.
• New task files start at status: not-started.
• Whoever completes a task marks its heading checkbox (### <n>. [ ] → ### <n>. [x]) and moves the frontmatter status to in-progress (first task) or done (last task) in the same change.
• Reporting skills read only the frontmatter to determine status; they fall back to reading the whole file only when the frontmatter is missing or lacks status. Keep it accurate.

Do NOT modify the parent issue or the parent PRD.