name: aico-backend-task-breakdown description: | Break down PM story into organized tasks in a single file following LAYERED ARCHITECTURE order: Types → Database → Repository → Service → API → Tests.

UNIQUE VALUE: Creates single task file (story-{name}.md) containing all tasks for a story. Tasks are ordered by backend architecture layers.

Use this skill when:

• Running /backend.tasks command
• User asks to "break down story", "create backend tasks", "split into tasks"
• Have story at docs/reference/pm/stories/ and need organized task breakdown
• Need tasks ordered by backend architecture layers (not random order)
• Starting backend work and want organized task list

Task order is CRITICAL: Setup → Static UI → Dynamic → Interactions → Tests Output: Create single file docs/reference/backend/tasks/story-{name}.md with all tasks

Task Breakdown

⚠️ CRITICAL RULES - READ FIRST

BEFORE doing anything, you MUST:

1. CHECK EXISTING TASK FILE FIRST:

   • ALWAYS check if story-{story-name}.md already exists in docs/reference/backend/tasks/
   • If exists: READ it and continue from current progress (add new tasks or update existing ones)
   • If not exists: Create new task breakdown file
   • NEVER re-break down existing tasks

2. FILE NAMING:

   • Pattern: story-{story-name}.md (single file per story)
   • Example: story-user-profile.md
   • All tasks for this story go into this ONE file
   • Tasks are separated by --- dividers

3. MULTIPLE TASKS IN ONE FILE:

   • One file contains ALL tasks for the story
   • Each task = independently testable section
   • Clear scope and acceptance criteria per task
   • Tasks numbered sequentially (Task 1, Task 2, etc.)

4. ALWAYS SAVE TO CORRECT PATH:

   • Path: docs/reference/backend/tasks/story-{story-name}.md
   • NO exceptions, NO other locations

5. READ CONTEXT FIRST:

   • Read story from docs/reference/pm/stories/
   • Read design from docs/reference/backend/designs/ if exists
   • Read design system from docs/reference/backend/design-system.md
   • Read constraints from docs/reference/backend/constraints.md

Language Configuration

Before generating any content, check aico.json in project root for language field to determine the output language. If not set, default to English.

Process

1. Read story/PRD: Load from docs/reference/pm/stories/ or docs/reference/pm/versions/
2. Read design (if exists): Load from docs/reference/backend/designs/
3. Read constraints: Load design system and technical constraints
4. Identify components: What backend layers are needed
5. Identify interactions: What APIs and data flows are needed
6. Break into tasks: Independently testable, single responsibility, by architecture layer
7. Order by dependencies: Types → DB → Repository → Service → API → Tests
8. Generate single file: Create story-{story-name}.md with all tasks in sections
9. Update Story file: Add "Related Tasks" section to story file with link to task file
10. Summary: Show created file and next steps

Task File Format

See Task File Template for complete structure.

Key points:

• Single file contains all tasks for the story
• Tasks numbered sequentially (Task 1, Task 2, etc.)
• Each task has: Description, Context, Acceptance Criteria, Scope, Implementation Steps
• Progress section at the end tracks completion
• Both story-based and standalone use the same format (only filename differs)
• Backend tasks ordered by architecture layers: Types → DB → Repository → Service → API → Tests

Updating Story File

After generating the task file, ALWAYS update the story file to add the "Related Tasks" section:

## Related Tasks

### Backend Tasks

Task breakdown: [docs/reference/backend/tasks/story-user-profile.md](../backend/tasks/story-user-profile.md)

**Progress**: 0/6 tasks completed

- [ ] Task 1: Define Types
- [ ] Task 2: Database Schema
- [ ] Task 3: Repository Layer
- [ ] Task 4: Service Layer
- [ ] Task 5: API Endpoints
- [ ] Task 6: Add Tests

Key points:

• Add this section at the end of the story file (before any existing notes)
• Include link to the task file
• Use - [ ] checkboxes for each task (will be checked when task completes)
• List tasks in execution order (Types → DB → Repository → Service → API → Tests)
• Keep the section organized by frontend/backend if both exist
• Include progress counter (X/Y tasks completed)

Output Example

After breaking down "user-profile" story:

Created task file for story 'user-profile':

✓ docs/reference/backend/tasks/story-user-profile.md

Task breakdown includes:
- Task 1: Define Types (setup)
- Task 2: Database Schema (feature)
- Task 3: Repository Layer (feature)
- Task 4: Service Layer (feature)
- Task 5: API Endpoints (feature)
- Task 6: Add Tests (testing)

Total: 6 tasks

Next steps:
1. Review task breakdown in story-user-profile.md
2. Use /backend.plan to add detailed steps to specific tasks
3. Use /backend.implement to start executing tasks

Key Rules

• ALWAYS create a single file containing all tasks for the story
• MUST use story-{story-name}.md naming (NOT multiple files)
• ALWAYS include test tasks at the end
• MUST note dependencies between tasks (in each task's metadata)
• Keep tasks focused - not too big, not too small
• Each task section is self-contained with clear acceptance criteria
• Separate tasks with --- dividers
• Include Story Progress section at the end of file

Common Mistakes

• ❌ Tasks too large (full feature) → ✅ Break into layers
• ❌ Tasks too small (add one field) → ✅ Group related work
• ❌ Skip dependencies → ✅ Note which tasks depend on others
• ❌ Forget testing → ✅ Always include test tasks
• ❌ Create multiple files → ✅ Use single file with multiple task sections