Task Breakdown Skill

When to Use This Skill

Use this skill when:

• You have a story file in docs/stories/
• The story is complex enough to warrant multiple tasks
• User asks to "create tasks" or "break down story {ID}"
• Want to work in small, incremental commits

What This Skill Does

Reads a story file and generates individual task files in docs/tasks/ directory. Each task represents an atomic unit of work that results in a single commit (typically a few hundred lines of code).

Task vs. Story Decision

When to create tasks:

• Story has multiple distinct implementation phases
• Story involves both backend and frontend work
• Story requires database changes + API + UI
• Story is estimated at >1 day of work

When to skip task breakdown:

• Story is simple (<4 hours of work)
• Story is a single file change
• Story has only one clear implementation step

If skipping task breakdown, implement the story directly using @agent-implementation-agent.

Workflow

Step 1: Read Story & Context

1. Read the story file (e.g., docs/stories/story-e1-s001-2025-11-02.md)
2. Read parent epic file
3. Read docs/system-architecture.md
4. Understand story scope and implementation steps

Step 2: Identify Tasks

Tasks should:
- Be completable in <4 hours
- Result in a single commit
- Be independently testable
- Have clear input/output
- Be ordered sequentially (dependencies matter)

Typical task breakdown pattern:
1. Database schema / migrations
2. Backend logic / API endpoints
3. Frontend components
4. Integration / testing
5. Polish / error handling

Step 3: Create Task Files

For each task, create file: docs/tasks/task-{story-id}-t{num}.md

Example filenames:
- docs/tasks/task-e1-s001-t001.md (Database schema)
- docs/tasks/task-e1-s001-t002.md (API endpoint)
- docs/tasks/task-e1-s001-t003.md (Frontend component)

Step 4: Task File Structure

Each task file should be completely self-contained - implementation agent should only need to read this file:

# Task {Story-ID}-T{Num} — {Task Name}

**Story:** {Story ID and Name with link}
**Status:** Not Started
**Estimated Time:** {X hours}
**Date:** {YYYY-MM-DD}

---

## What to Build

{1-2 sentence summary of exactly what this task implements}

**This task creates:**
- {Specific deliverable 1}
- {Specific deliverable 2}

**This task modifies:**
- {Specific file 1}
- {Specific file 2}

---

## Context (Self-Contained)

> Everything implementation agent needs to know without reading PRD/Epic/Story

**Background:**
{Brief context: why this task exists, how it fits in the story}

**Assumptions:**
- {Assumption 1 from architecture/story}
- {Assumption 2 from previous tasks}

**Dependencies:**
- **Requires:** {Previous task ID if any}
- **Blocks:** {Next task ID if any}

---

## 🛑 STOP - USER VERIFICATION REQUIRED

**⚠️ IMPLEMENTATION AGENT: Ask user these questions BEFORE coding:**

1. **{Specific configuration/credential question}**
   - If unclear: {What user should check}
   - Wait for: {Expected answer format}

2. **{Specific technical decision question}**
   - Option A: {Pros/Cons}
   - Option B: {Pros/Cons}
   - Wait for: User to choose

---

## Implementation Steps

### Step 1: {Phase Name}
{Detailed instructions}

```typescript
// Example code structure (not full implementation)
{Pseudocode or interface definition}

Acceptance:

• ✅ {Criterion 1}
• ✅ {Criterion 2}

Step 2: {Phase Name}

{Detailed instructions}

Acceptance:

• ✅ {Criterion 1}
• ✅ {Criterion 2}

Files to Create/Modify

Create:

path/to/new-file.ts  - {Purpose}
path/to/test-file.test.ts - {Purpose}

Modify:

path/to/existing-file.ts - {What changes}
  - Add: {Function/import}
  - Update: {Section}

Testing

How to test:

# Command to run tests
npm test path/to/test-file.test.ts

# Command to verify build
npm run build

Manual verification:

1. {Step 1}
2. {Step 2}

Expected outcome:

• ✅ {Result 1}
• ✅ {Result 2}

Definition of Done

• All implementation steps completed
• File created/modified as specified
• Tests pass
• Build succeeds
• No console errors
• German language for user-facing text (if applicable)
• Code follows patterns from handoff doc (if exists)
• Ready for QA validation

Notes

From Architecture: {Relevant architecture decisions for this task}

From Previous Task: {Reference handoff doc if exists: docs/handoffs/task-{prev-id}-handoff.md}

Gotchas:

• {Known issue 1}
• {Known issue 2}

## Self-Contained Task Principle

**CRITICAL:** Each task file must be completely self-contained because:
- Implementation agent only has access to the task file (not PRD/Epic/Story)
- Prevents context pollution
- Forces clarity in requirements
- Makes tasks independently implementable

**Include in task file:**
- ✅ All context needed from architecture
- ✅ All assumptions from story/epic
- ✅ All prerequisites from previous tasks
- ✅ Specific file paths and code structure
- ✅ Exact acceptance criteria

**Do NOT include:**
- ❌ References like "see architecture doc for details"
- ❌ Vague requirements like "implement as discussed"
- ❌ Assumptions that "agent knows the broader context"

## Task Sequencing

Order tasks by dependency:

```markdown
## Task Dependency Chain

1. **task-e1-s001-t001** - Database Schema
   - No dependencies
   - Creates: Tables, types, migrations

2. **task-e1-s001-t002** - API Endpoint
   - Depends on: t001
   - Uses: Database schema from t001

3. **task-e1-s001-t003** - Frontend Component
   - Depends on: t002
   - Calls: API endpoint from t002

4. **task-e1-s001-t004** - Integration Testing
   - Depends on: t001, t002, t003
   - Tests: Complete flow

Update Story File

After creating tasks, update story file:

## Task Breakdown

- [ ] [T001: Database Schema](../tasks/task-e1-s001-t001.md) - Not Started
- [ ] [T002: API Endpoint](../tasks/task-e1-s001-t002.md) - Not Started
- [ ] [T003: Frontend Component](../tasks/task-e1-s001-t003.md) - Not Started
- [ ] [T004: Integration Testing](../tasks/task-e1-s001-t004.md) - Not Started

**Estimated Total:** 12 hours

Important Task Guidelines

DO:

• ✅ Make tasks completely self-contained
• ✅ Include ALL necessary context in task file
• ✅ Define clear acceptance criteria
• ✅ Specify exact files to create/modify
• ✅ Order tasks by dependency
• ✅ Keep tasks small (<4 hours, few hundred lines)
• ✅ Include 🛑 STOP checkpoints for user verification

DON'T:

• ❌ Reference external docs without copying relevant details
• ❌ Make tasks too large (>1 day)
• ❌ Leave requirements ambiguous
• ❌ Assume implementation agent has broader context
• ❌ Create tasks that depend on multiple other tasks

Output

After running this skill, you should have:

• ✅ Multiple task files in docs/tasks/
• ✅ Each task is self-contained and implementable
• ✅ Tasks are ordered by dependency
• ✅ Story file updated with task links
• ✅ Clear path for incremental implementation

Next Step

After creating tasks, user should:

1. Select first task (task-{id}-t001.md)
2. Tell implementation agent: "implement this task"
3. Implementation agent implements task using ONLY task file context
4. After task complete, QA agents run automatically
5. After QA passes, onboarding agent creates handoff doc
6. Move to next task with clean context