name	ln-310-story-decomposer
description	Orchestrates task operations. Analyzes Story, builds optimal plan (1-6 tasks), delegates to ln-311-task-creator (CREATE) or ln-312-task-replanner (REPLAN). Auto-discovers team ID.

Linear Task Planner (Orchestrator)

Orchestrator for User Story task operations. Analyzes Story requirements, builds optimal task decomposition plan, and delegates execution to specialized workers.

Overview

What This Skill Does

Coordinates task creation and replanning for User Stories:

Auto-discovers Team ID from kanban_board.md
Loads Story from Linear (AC, Technical Notes, Context)
Analyzes Story complexity (simple/medium/complex)
Builds OPTIMAL task plan (1-6 tasks, Foundation-First execution order)
Extracts guide links from Story Technical Notes
Ignores and strips any Non-Functional Requirements (NFRs) – do not create tasks to formalize them
Checks existing tasks in Linear
Delegates to workers:
- No tasks (count = 0) → Invokes ln-311-task-creator (CREATE MODE)
- Has tasks (count ≥ 1) → Invokes ln-312-task-replanner (REPLAN MODE)

When to Use This Skill

This skill should be used when:

Create implementation tasks for a User Story
Replan tasks when Story requirements change (AC updated, technical approach changed)
Automatically decompose Story into optimal task count (1-6 based on complexity)

Prerequisites:

Story exists in Linear (e.g., US001, API-53)
Story has AC (Acceptance Criteria) and Technical Notes defined
Requirements are clear

NOT for test tasks - use ln-350-story-test-planner for Story's final test task after manual testing.

When NOT to Use

Do NOT use if:

Story doesn't exist → Use ln-220-story-coordinator first to create Story
Need to create test tasks → Use ln-350-story-test-planner after manual testing
Story is vague (no AC) → Refine Story first
Task is trivial (< 1 hour) → Create directly in Linear manually

Core Concepts

Orchestrator Pattern

ln-310-story-decomposer is a coordinator - it does NOT execute work directly:

✅ Analyzes Story and builds IDEAL task plan
✅ Makes routing decisions (CREATE or REPLAN mode)
✅ Delegates execution to workers via Skill tool
❌ Does NOT generate task documents (workers do this)
❌ Does NOT create/update in Linear (workers do this)
❌ Does NOT update kanban_board.md (workers do this)

Workers:

ln-311-task-creator: Creates new tasks from IDEAL plan (CREATE MODE)
ln-312-task-replanner: Updates existing tasks when requirements change (REPLAN MODE)

Decompose-First Pattern

Key Principle: ALWAYS analyze Story and build OPTIMAL task plan FIRST (Phase 2), independent of current state. Then check existing tasks (Phase 3) and delegate.

This ensures consistent decomposition logic regardless of whether tasks exist or not.

Flow:

Load Story metadata (AC, Technical Notes)
Build IDEAL task plan "in mind" (1-6 tasks)
THEN query Linear for existing tasks
Delegate: count = 0 → ln-311-task-creator, count ≥ 1 → ln-312-task-replanner

Task Order Strategy

Two separate concerns:

Analysis (Consumer-First): Start from consumer perspective to understand WHAT is needed (YAGNI)
- Think: API endpoint → Service → Repository → Database
- Purpose: Avoid building unnecessary components
Execution (Foundation-First): Build from foundation up for testability
- Order: Database → Repository → Service → API → Frontend
- Purpose: Each layer is testable when built (can't test API without DB)

Applied in Phase 2: Tasks created in Foundation-First order (execution order).

Task Structure (7 Sections)

Every implementation task follows this template:

Context: Current state + Desired state + Story link
Implementation Plan: 3 phases with checkboxes
Technical Approach: KISS/YAGNI principles + guide links + architecture patterns
Acceptance Criteria: 3-5 Given-When-Then scenarios from Story AC
Affected Components: Implementation files + Documentation files
Existing Code Impact: Refactoring needed + Tests to update + Docs to update
Definition of Done: Completion checklist

See task_template_implementation.md for detailed template (owned by ln-311-task-creator universal factory).

Auto-Discovery

Team ID: Auto-discovered from docs/tasks/kanban_board.md Linear Configuration table (see CLAUDE.md "Configuration Auto-Discovery").

Story ID: Parsed from request: "for US001" or "for API-53"

Guide Links: Extracted from Story Technical Notes "Related Guides:" section and passed to workers.

Workflow

[!NOTE] Checkpoint Sync (when invoked by ln-300-story-pipeline):

Start: Read checkpoint → verify Phase 2 not completed

Before delegating to worker: Record | timestamp | ln-310 | Acquired | worker-name |

After worker returns: Verify Released entry, update Current Owner: ln-310

End: Record | timestamp | ln-310 | Released | ln-300 |, mark Phase 2 completed

Phase 1: Discovery (Automated)

Auto-discovers Team ID from docs/tasks/kanban_board.md.

Parses request for:

Story ID: "for US001" or "for API-53"
Requirements: New or updated AC, technical approach changes

Phase 2: Analyze & Decompose (ALWAYS)

This phase runs BEFORE checking existing tasks.

Steps:

Load Story from Linear:
- Story statement (As a/I want/So that)
- Context (Current/Desired situation)
- Acceptance Criteria (all Given-When-Then scenarios)
- Technical Notes (integrations, patterns, guide links)
- Implementation Tasks list (existing task references)
Analyze Story Complexity:
- Count AC scenarios (1-2 → simple, 3-4 → medium, 5+ → complex)
- Identify technical components (API, Service, Repository, Database)
- Check integrations (external APIs, services)
- Review Technical Notes for constraints
Build OPTIMAL Task Plan "in mind":
- Simple Story (1-2 AC, single endpoint): 1 task (3-5 hours)
- Medium Story (3-4 AC, multiple layers): 2-3 tasks (6-15 hours)
- Complex Story (5+ AC, multiple integrations): 3-6 tasks (12-30 hours)
- Max 6 tasks per Story (enforced)
Apply Foundation-First Ordering (for execution):
- Database → Repository → Service → API → Frontend
- Each layer testable when built (foundation before consumers)
Extract Guide Links:
- Read Story Technical Notes "Related Guides:" section
- Parse guide links to pass to workers

Result: IDEAL Task Structure:

IDEAL TASK PLAN (N tasks):
1. Task Title (AC#, AC#) - Xh
2. Task Title (AC#, AC#) - Xh
3. Task Title (AC#) - Xh

Foundation-First order: ✓
Total estimate: Xh
Guide links: [path/to/guide.md, ...]

Phase 3: Check Existing Tasks & Detect Mode

Query Linear: list_issues(parentId=Story.id)

Mode Detection:

Analyze user request for keywords:
- ADD keywords: "add task", "one more", "additional task", "append"
- REPLAN keywords: "update plan", "revise", "AC changed", "requirements changed", "replan"
Decision matrix:

Condition	Mode	Delegate To
Count = 0	CREATE	Phase 4a: ln-311-task-creator
Count ≥ 1 AND ADD keywords	ADD	Phase 4c: ln-311-task-creator (appendMode)
Count ≥ 1 AND REPLAN keywords	REPLAN	Phase 4b: ln-312-task-replanner
Count ≥ 1 AND ambiguous	ASK USER	"Add new task or revise the plan?"

Phase 4a: Delegate to ln-311-task-creator (if Count = 0)

No existing tasks found. Delegate to ln-311-task-creator worker.

Invocation:

Skill(skill: "ln-311-task-creator", {
  taskType: "implementation",
  teamId: teamId,
  storyData: {
    id: Story.id,
    title: Story.title,
    description: Story.description,
    ac: Story.acceptanceCriteria,
    technicalNotes: Story.technicalNotes,
    context: Story.context
  },
  idealPlan: IDEAL_TASK_PLAN,
  guideLinks: extractedGuideLinks,
  autoApprove: true  // Skip user confirmation in automation mode
})

Worker responsibilities:

Input: taskType + storyData + idealPlan + guideLinks, autoApprove: true
Output: Task URLs + summary
Details: See ln-311-task-creator/SKILL.md

Phase 4b: Delegate to ln-312-task-replanner (if Count ≥ 1)

Existing tasks found. Delegate to ln-312-task-replanner worker.

Invocation:

Skill(skill: "ln-312-task-replanner", {
  taskType: "implementation",
  teamId: teamId,
  storyData: {
    id: Story.id,
    title: Story.title,
    description: Story.description,
    ac: Story.acceptanceCriteria,
    technicalNotes: Story.technicalNotes,
    context: Story.context
  },
  idealPlan: IDEAL_TASK_PLAN,
  guideLinks: extractedGuideLinks,
  existingTaskIds: existingTaskIds,
  autoApprove: true  // Skip user confirmation in automation mode
})

Worker responsibilities:

Input: taskType + storyData + idealPlan + guideLinks + existingTaskIds, autoApprove: true
Output: Operations summary + URLs + warnings
Details: See ln-312-task-replanner/SKILL.md

Phase 4c: Delegate to ln-311-task-creator (ADD MODE - append to existing)

User wants to add task(s) to Story that already has tasks, WITHOUT replanning existing ones.

Invocation:

Skill(skill: "ln-311-task-creator", {
  taskType: "implementation",
  appendMode: true,  // ADD to existing, don't replace
  teamId: teamId,
  storyData: {
    id: Story.id,
    title: Story.title,
    description: Story.description,
    ac: Story.acceptanceCriteria,
    technicalNotes: Story.technicalNotes,
    context: Story.context
  },
  newTaskDescription: userRequestedTask,  // Single task from user request
  guideLinks: extractedGuideLinks,
  autoApprove: true
})

Key differences from CREATE MODE:

appendMode: true → Skip full IDEAL plan, create only requested task(s)
newTaskDescription → User's specific request (e.g., "add validation task")
Does NOT require Phase 2 IDEAL plan for all tasks
Preserves existing tasks without comparison

Worker responsibilities:

Input: appendMode + storyData + newTaskDescription + guideLinks
Output: Created task URL + summary
Details: See ln-311-task-creator/SKILL.md

Phase 5: Post-Execution

Verify worker completed successfully:

ln-311-task-creator (CREATE): Tasks created in Linear + kanban_board.md updated
ln-311-task-creator (ADD): New task(s) appended + kanban_board.md updated
ln-312-task-replanner (REPLAN): Operations executed + kanban_board.md updated

Return to user:

CREATE MODE: "N tasks created. Linear URLs: [...]"
ADD MODE: "Task added to existing. Linear URL: [...]"
REPLAN MODE: "Operations executed. X kept, X updated, X canceled, X created."

Next Steps:

ln-320-story-validator: Verify Story + Tasks before approval (Backlog → Todo, adds ✅ APPROVED)

Critical Rules

1. NO Test Creation in Implementation Tasks

HARD RULE: Implementation tasks MUST NOT include new test creation.

Enforced by workers (ln-311-task-creator and ln-312-task-replanner validate):

Scan for: "write tests", "create tests", "add tests", "unit tests", "E2E tests", "integration tests"
ERROR if detected → Stop execution

Why: All new tests (E2E/Integration/Unit) are created in Story's final test task by ln-350-story-test-planner AFTER manual testing passes.

2. Task Size Limits

Optimal task size: 3-5 hours (fits in 1-2 work sessions)

Max tasks per Story: 6 tasks (12-30 hours total)

Automatic decomposition by complexity:

Simple (1-2 AC) → 1 task (3-5h)
Medium (3-4 AC) → 2-3 tasks (6-15h)
Complex (5+ AC) → 3-6 tasks (12-30h)

3. Orchestrator Does NOT Load Task Descriptions

Token Efficiency: Orchestrator loads only task IDs (Phase 3), NOT full descriptions.

Workers load full descriptions:

ln-311-task-creator: Generates new descriptions (doesn't need to load)
ln-312-task-replanner: Loads existing task descriptions for comparison

Rationale: Prevents token waste, scales to Stories with many tasks.

4. No Code in Task Descriptions

Never include actual code in Task descriptions. Only technical approach and structure. Code is written during execution, not planning.

Definition of Done

Before completing work, verify ALL checkpoints:

✅ Team ID Discovered (Phase 1):

Team ID loaded from kanban_board.md OR requested from user
Story ID parsed from request

✅ IDEAL Plan Created (Phase 2):

Story loaded from Linear (AC, Technical Notes)
Complexity analyzed (simple/medium/complex)
Optimal task count determined (1-6)
Foundation-First execution order applied
Guide links extracted from Story

✅ Mode Detected (Phase 3):

Existing tasks queried in Linear (count)
Mode selected: CREATE or REPLAN

✅ Worker Invoked (Phase 4):

ln-311-task-creator (if count = 0) OR ln-312-task-replanner (if count ≥ 1)
Worker received IDEAL plan + Story data + guide links
Worker completed successfully

✅ Post-Execution Verified (Phase 5):

Worker returned summary (task URLs OR operations count)
Linear issues created/updated (verified by worker)
kanban_board.md updated (verified by worker)
Next steps provided to user

Output: Worker summary + next steps (ln-320-story-validator)

IDEAL Plan Data Sources

Where ln-310-story-decomposer gets information to build IDEAL task plan (Phase 2):

Data Source	Used For	Example
Story AC	Define task scope, determine task count (1 task per 1-2 AC)	5 AC → 3 tasks (AC1+AC2 = task1, AC3+AC4 = task2, AC5 = task3)
Story Technical Notes	Identify technical approach, libraries, patterns	"Use PostgreSQL connection pooling" → add Repository task
Story Context	Understand business requirements, domain rules	"User authentication system" → JWT token + refresh logic tasks
Complexity Analysis	Determine optimal task count (1-6)	Simple (1-2 tasks), Medium (3-4), Complex (5-6)
Foundation-First Execution	Order tasks for execution (DB → Repository → Service → API)	Start with database, end with API (each layer testable when built)
Guide Links	Extract implementation patterns to pass to workers	"Related Guides: Database Access Pattern" → pass link to ln-311-task-creator

IDEAL Plan Building Process (Phase 2):

Load Story from Linear (AC, Technical Notes, Context)
Analyze complexity (simple/medium/complex)
Determine task count (1-6) based on AC coverage
Apply Foundation-First ordering (DB → Repository → Service → API)
Extract guide links from Technical Notes
Build IDEAL task structure with titles, AC mapping, time estimates

Key Insight: IDEAL plan is built BEFORE querying Linear for existing tasks (Decompose-First Pattern). This ensures optimal decomposition regardless of current state.

Reference Files

task_template_implementation.md (MOVED)

Purpose: Complete implementation task template structure with all 7 sections

Contents: Detailed descriptions for Context, Implementation Plan, Technical Approach, Acceptance Criteria, Affected Components, Existing Code Impact, Definition of Done

Location: Moved to ln-311-task-creator/references/task_template_implementation.md

Ownership: ln-311-task-creator (universal factory owns all product templates)

Rationale: Templates moved to universal factory (ln-311-task-creator) which creates ALL 3 task types (implementation, refactoring, test). ln-311-task-creator owns all product templates.

Usage: Workers (ln-311-task-creator, ln-312-task-replanner) read this template when generating implementation task documents (via taskType: "implementation")

replan_algorithm.md (MOVED)

Location: Moved to ln-312-task-replanner/references/replan_algorithm.md

Ownership: ln-312-task-replanner (worker-specific logic)

Rationale: Replan algorithm is worker implementation detail, not orchestrator concern.

Best Practices

Task Decomposition

Automatic Decomposition: Orchestrator determines optimal count (1-6) based on Story complexity

Simple (1-2 AC) → 1 task (3-5h)
Medium (3-4 AC) → 2-3 tasks (6-15h)
Complex (5+ AC) → 3-6 tasks (12-30h)
Max 6 tasks per Story (12-30 hours total)

Foundation-First Execution: Database → Repository → Service → API (applied in Phase 2)

Task Size: Optimal 3-5 hours (fits in 1-2 work sessions)

Orchestrator Responsibilities

DO:

✅ Load Story metadata (AC, Technical Notes)
✅ Analyze complexity
✅ Build IDEAL plan (1-6 tasks)
✅ Extract guide links
✅ Query existing task count
✅ Delegate to workers

DON'T:

❌ Generate task documents (workers do this)
❌ Load task full descriptions (workers do this)
❌ Create/update Linear issues (workers do this)
❌ Update kanban_board.md (workers do this)
❌ Show previews/confirmations (workers do this)

Worker Communication

Context Propagation: Pass all necessary data to workers (Team ID, Story data, IDEAL plan, guide links, existing task IDs)

Trust Worker Results: Workers return summary, orchestrator doesn't re-verify (trust but verify principle)

Error Handling: If worker returns error (e.g., test creation detected), report to user and stop

Story Requirements

Clear AC: Given-When-Then format, 3-5 scenarios

Technical Notes: Guide links, architecture patterns, constraints

Context: Current + Desired state well-defined

Integration with Ecosystem

Called By

Users directly: "Create tasks for US001"

ln-220-story-coordinator: May invoke ln-310-story-decomposer when creating Stories (optional)

Calls (via Skill tool)

ln-311-task-creator: When no existing tasks (CREATE MODE)
ln-312-task-replanner: When tasks exist (REPLAN MODE)

Next Steps (User-initiated)

After ln-310-story-decomposer completes:

ln-320-story-validator: Verify Story + Tasks before approval (Backlog → Todo)
ln-330-story-executor: Execute Story (orchestrates task execution)

Quick Examples

Example 1: Create Mode (New Story, No Tasks)

Request: "Create tasks for US001: Implement OAuth token authentication"

Execution:

Phase 1: Team ID discovered, Story ID = US001
Phase 2: Story loaded (5 AC scenarios), Complexity = Medium-Complex, IDEAL Plan = 3 tasks (Token generation 4h, Validation middleware 3h, Refresh logic 5h), Foundation-First ✓
Phase 3: Query Linear → Count = 0 → CREATE MODE
Phase 4a: Invoke ln-311-task-creator (IDEAL plan + Story data)
- ln-311-task-creator: Generate 3 tasks, validate NO tests, show preview, user confirms, create in Linear, update kanban
Phase 5: Receive summary from worker, return to user

Result: 3 tasks created, 12h total

Example 2: Replan Mode (AC Changed)

Request: "Create tasks for US001" (Story AC updated: AC4 "expired tokens" added)

Execution:

Phase 1: Team ID discovered, Story ID = US001
Phase 2: Story loaded (5 AC scenarios, AC4 NEW), IDEAL Plan = 3 tasks (same structure, AC4 added to task 2)
Phase 3: Query Linear → Count = 3 → REPLAN MODE
Phase 4b: Invoke ln-312-task-replanner (IDEAL plan + Story data + existing task IDs)
- ln-312-task-replanner: Load existing, Compare (EP7_01 KEEP, EP7_02 UPDATE +AC4, EP7_03 OBSOLETE), show summary, user confirms, execute operations
Phase 5: Receive summary from worker (1 kept, 1 updated, 1 canceled), return to user

Result: 1 kept, 1 updated, 1 canceled

Version: 7.3.0 (Fixed Writing Style: "Use this skill when" → "This skill should be used when" for skill-creator compliance.) Last Updated: 2025-11-16

Install Skill

SKILL.md

Linear Task Planner (Orchestrator)

Overview

What This Skill Does

When to Use This Skill

When NOT to Use

Core Concepts

Orchestrator Pattern

Decompose-First Pattern

Task Order Strategy

Task Structure (7 Sections)

Auto-Discovery

Workflow

Phase 1: Discovery (Automated)

Phase 2: Analyze & Decompose (ALWAYS)

Phase 3: Check Existing Tasks & Detect Mode

Phase 4a: Delegate to ln-311-task-creator (if Count = 0)

Phase 4b: Delegate to ln-312-task-replanner (if Count ≥ 1)

Phase 4c: Delegate to ln-311-task-creator (ADD MODE - append to existing)

Phase 5: Post-Execution

Critical Rules

1. NO Test Creation in Implementation Tasks

2. Task Size Limits

3. Orchestrator Does NOT Load Task Descriptions

4. No Code in Task Descriptions

Definition of Done

IDEAL Plan Data Sources

Reference Files

task_template_implementation.md (MOVED)

replan_algorithm.md (MOVED)

Best Practices

Task Decomposition

Orchestrator Responsibilities

Worker Communication

Story Requirements

Integration with Ecosystem

Called By

Calls (via Skill tool)

Next Steps (User-initiated)

Quick Examples

Example 1: Create Mode (New Story, No Tasks)

Example 2: Replan Mode (AC Changed)