---
name: scorpio-task-plan
description: The exclusive task-file writer. Consumes TASK-PLAN-HANDOFF.json or plan docs to generate detailed, actionable development tasks with acceptance criteria. Use when you have a design/investigation handoff or plan document and need to generate task files.
---

# Task Plan Generator (alias: PM Task Breakdown)

The **exclusive task-file writer** in the Scorpio skill ecosystem. No other skill writes task files — all planning and investigation skills produce `TASK-PLAN-HANDOFF.json` which this skill consumes to generate task files.

Convert handoff JSON, implementation plans, and scope documents into detailed, actionable development tasks. Each task should be small enough to complete in a focused session and include clear acceptance criteria.

> **Model role — plan.** This skill runs the pipeline's **plan** phase, so it targets the configured `{models.plan}` (model + optional `effort`) when `scorpio.config.json` sets it — falling back to `{models.default}` → the harness's main-session model. Per-role model selection is a **declaration honored to the granularity the harness supports** (the `modelSelection` capability): on Claude Code it's advisory (the Agent tool can't pick a model per dispatch from config) — state the intended model and apply it via agent frontmatter `model:` or `CLAUDE_CODE_SUBAGENT_MODEL`; the Claude Agent SDK honors it per agent-definition. See [docs/CONFIG.md](../../docs/CONFIG.md#per-role-models).

## Input: Handoff JSON (Preferred)

Check for `{docs.planning}/TASK-PLAN-HANDOFF.json` first. This file is produced by upstream planning/investigation skills:
- **scorpio-feature-plan** (`scorpio-feature-plan`) — feature design handoffs
- **scorpio-bug-investigate** (`scorpio-bug-investigate`) — bug investigation handoffs
- **scorpio-project-artifacts** (`scorpio-project-artifacts`) — project plan handoffs

### TASK-PLAN-HANDOFF.json Schema

```json
{
  "source_skill": "<canonical skill name that produced this>",
  "source_artifact": "<path to design/investigation doc>",
  "feature_name": "<name>",
  "scope_summary": "<2-3 sentence overview>",
  "slices": [
    {
      "title": "<slice title>",
      "type": "Feature|Bug|Chore|Test",
      "estimate": "XS|S|M",
      "description": "<what this slice does>",
      "files_to_modify": ["path/to/file.ts"],
      "acceptance_criteria": ["criterion 1"],
      "depends_on": []
    }
  ],
  "constraints": [],
  "test_strategy": {}
}
```

When handoff JSON is present, use slices as the primary input for task generation. Read the `source_artifact` for additional context.

### Error Behavior

If `TASK-PLAN-HANDOFF.json` is present but invalid (missing required fields, malformed JSON):
- Report the specific validation error
- List the missing/invalid fields
- Do NOT attempt to generate tasks from invalid handoff data
- Suggest re-running the upstream skill

## Fallback Input: Plan Documents

If no handoff JSON exists, fall back to:
- An implementation plan with phases and high-level tasks, OR
- An MVP scope document with features defined, OR
- A PRD with user stories

If none exist, use **scorpio-project-artifacts** (`scorpio-project-artifacts`) first.

## Task Structure

Every task follows this format:

```markdown
## [TASK-ID] [Task Title]

**Type**: Feature | Bug | Chore | Spike
**Priority**: P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low)
**Estimate**: XS | S | M | L | XL
**Dependencies**: [TASK-ID] or None

### Description
[1-3 sentences describing what needs to be done and why]

### Acceptance Criteria
- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]

### Technical Notes
[Optional: Implementation hints, gotchas, or constraints]
```

## Size Guidelines

| Size | Scope | Max Files | Examples |
|------|-------|-----------|----------|
| **XS** | < 1 hour | 1-2 files | Config change, copy update, simple fix |
| **S** | 1-4 hours | 2-3 files | Single function, simple component, unit tests |
| **M** | 4-8 hours | 3-5 files | Feature slice, API endpoint + tests |
| **L** | 1-2 days | 5+ files | **MUST be split** into smaller tasks |
| **XL** | 2+ days | Many files | **MUST be split** into smaller tasks |

**Rules**:
- If a task is L or XL, it **must** be broken down further — no exceptions.
- A task should modify **no more than 5 files**. If it needs more, split it.
- Each task should be completable by a focused agent in a single session. Tasks that require reading many files for context or touching many files for implementation will fail due to context limits.

## Breaking Down Features

For each feature in the implementation plan:

### 1. Identify the Vertical Slice
A vertical slice delivers user-visible value end-to-end:
```
UI Component → API Route → Business Logic → Data Layer → Tests
```

### 2. Split by Layer (if needed)
For larger features, create tasks per layer:
```
[TASK-001] Create database schema for [feature]
[TASK-002] Implement API endpoints for [feature]
[TASK-003] Build UI components for [feature]
[TASK-004] Add integration tests for [feature]
```

### 3. Extract Setup/Foundation Tasks
Common foundational tasks to call out separately:
- Project scaffolding
- Database migrations
- Authentication/authorization setup
- CI/CD pipeline
- Environment configuration

## Acceptance Criteria Guidelines

Good acceptance criteria are:

| ✅ Good | ❌ Bad |
|---------|--------|
| "User can submit form and sees success message" | "Form works" |
| "API returns 400 with error message for invalid input" | "Handle errors" |
| "Page loads in under 2 seconds on 3G" | "Page is fast" |
| "Password must be 8+ chars with 1 number" | "Validate password" |

### Criteria Patterns

**For UI tasks:**
- [ ] Component renders without errors
- [ ] [User action] results in [expected outcome]
- [ ] Error states display [specific message]
- [ ] Loading states show [specific indicator]

**For API tasks:**
- [ ] Endpoint returns [status code] for [scenario]
- [ ] Response matches [schema/format]
- [ ] Invalid input returns [specific error]
- [ ] Endpoint is covered by integration tests

**For data tasks:**
- [ ] Migration runs without errors
- [ ] Rollback migration works correctly
- [ ] Existing data is preserved/migrated
- [ ] Indexes exist for [query patterns]

## Task Ordering

Generate tasks in dependency order:

```
Phase 1: Foundation (no dependencies)
├── TASK-001: Project setup
├── TASK-002: Database schema
└── TASK-003: Auth configuration

Phase 2: Core Features (depends on Phase 1)
├── TASK-004: User registration (depends: 002, 003)
├── TASK-005: User login (depends: 002, 003)
└── TASK-006: Dashboard layout (depends: 001)

Phase 3: Feature Work (depends on Phase 2)
├── TASK-007: Feature A (depends: 004, 006)
└── TASK-008: Feature B (depends: 005, 006)
```

## Output Formats

### Format 1: Detailed Task List (default)

```markdown
# [Project Name] - Task Breakdown

## Summary
- Total tasks: [N]
- By priority: P0=[N], P1=[N], P2=[N]
- By size: XS=[N], S=[N], M=[N], L=[N]

## Phase 1: [Phase Name]

### TASK-001: [Title]
**Type**: Feature | **Priority**: P0 | **Estimate**: M | **Depends**: None

[Description]

**Acceptance Criteria:**
- [ ] [Criterion]
- [ ] [Criterion]

---

### TASK-002: [Title]
...
```

### Format 2: Quick Task Table

For rapid planning or smaller projects:

```markdown
| ID | Task | Type | Priority | Size | Depends |
|----|------|------|----------|------|---------|
| 001 | Project setup | Chore | P0 | S | - |
| 002 | DB schema | Chore | P0 | M | - |
| 003 | User registration | Feature | P0 | M | 002 |
| 004 | User login | Feature | P0 | M | 002 |
| 005 | Dashboard UI | Feature | P1 | L | 001 |
```

### Format 3: Checklist Mode

For simple projects or personal use:

```markdown
# [Project] - Build Checklist

## Must Complete First
- [ ] [Task 1]
- [ ] [Task 2]

## Core Features
- [ ] [Task 3]
- [ ] [Task 4]

## Nice to Have
- [ ] [Task 5]
```

## Common Task Patterns

### New Feature Pattern
```
1. [Feature] - Database migration
2. [Feature] - API endpoint(s)
3. [Feature] - UI component(s)
4. [Feature] - Integration tests
5. [Feature] - E2E tests (optional)
```

### Bug Fix Pattern
```
1. Write failing test that reproduces bug
2. Implement fix
3. Verify test passes
4. Add regression test if not covered
```

### Refactor Pattern
```
1. Add tests for existing behavior (if missing)
2. Refactor implementation
3. Verify tests still pass
4. Update documentation if API changed
```

## Task ID Conventions

Use a consistent prefix based on area:

| Prefix | Area |
|--------|------|
| `CORE-` | Core business logic |
| `UI-` | Frontend/UI work |
| `API-` | Backend API work |
| `DB-` | Database/data work |
| `INFRA-` | Infrastructure/DevOps |
| `TEST-` | Testing-focused tasks |
| `DOC-` | Documentation |

Example: `UI-042`, `API-015`, `CORE-007`

## Exclusive Ownership Contract

This skill is the **only** skill that writes to `{docs.tasks}/**`. Other skills produce handoff JSON; this skill converts handoffs into task files.

If another skill has already written task files, flag this as a contract violation and report it.

## What NOT To Do

- ❌ Create vague tasks ("Implement feature X")
- ❌ Bundle unrelated work into one task
- ❌ Skip acceptance criteria
- ❌ Create XL tasks without splitting
- ❌ Forget to identify dependencies
- ❌ Mix feature work with refactoring in same task
- ❌ Ignore handoff JSON when it exists

## Quick Reference: From Story to Tasks

```
User Story:
"As a user, I want to reset my password so I can regain access"

Tasks Generated:
├── API-021: Add POST /auth/reset-request endpoint (M)
│   └── AC: Sends email, returns 200, rate limited
├── API-022: Add POST /auth/reset-confirm endpoint (M)
│   └── AC: Validates token, updates password, invalidates token
├── UI-045: Create password reset request form (S)
│   └── AC: Email input, submit, success/error states
├── UI-046: Create password reset confirmation form (S)
│   └── AC: New password inputs, validation, submit
└── TEST-018: Password reset E2E tests (S)
    └── AC: Happy path, expired token, invalid token
```

## Skill Chain

This skill is part of the PM planning workflow:

1. **scorpio-project-intake** (`scorpio-project-intake`) → Gather roles, stories, flows, decisions
2. **scorpio-project-artifacts** (`scorpio-project-artifacts`) → Create PRD, MVP scope, implementation plan
3. **scorpio-task-plan** (`scorpio-task-plan`) → Generate detailed tasks (you are here)
4. **scorpio-execute** (`scorpio-execute`) → Execute each task in focused subagent sessions (max 3 per session)
5. **scorpio-qa** (`scorpio-qa`) → Per-task code review and acceptance criteria validation
6. **task-review-final** (`scorpio-qa-final`) → Final-pass review: integration, UI, cross-task concerns
7. **task-triage-findings** (`scorpio-qa-rework`) → Triage findings, generate rework tasks, approve or loop back to step 4