# Task Replan Algorithm

Detailed comparison logic for x-task-coordinator REPLAN MODE. This algorithm determines which operations (KEEP/UPDATE/OBSOLETE/CREATE) to perform when existing tasks are found for a Story.

## Overview

When a Story's requirements change and tasks already exist, x-task-coordinator compares the IDEAL task decomposition (from Phase 2) with existing tasks (from Linear) to determine the minimal set of operations needed.

**Key Principle**: The IDEAL plan from Phase 2 is the source of truth. Existing tasks are compared against this plan.

## Inputs

### Phase 2 Output: IDEAL Task Plan

Result from Story analysis (runs BEFORE checking existing tasks):

**Structure**:
- Task count: 1-4 (based on Story complexity)
- Task titles: Descriptive names (e.g., "Implement token generation endpoint")
- Task goals: Derived from Story AC
- Foundation-First ordering: Database → Repository → Service → API
- Estimate per task: 3-5 hours
- Guide links: From Story Technical Notes

**Example IDEAL Plan**:
```
IDEAL TASK PLAN (3 tasks, 12h total):
1. Implement token generation endpoint
   - Goal: Handle POST /auth/token with credentials
   - AC: AC1 (valid credentials), AC2 (invalid credentials)
   - Estimate: 4h

2. Add token validation middleware
   - Goal: Validate JWT tokens in protected routes
   - AC: AC3 (valid token), AC4 (expired token)
   - Estimate: 3h

3. Create token refresh logic
   - Goal: Implement token refresh mechanism
   - AC: AC5 (refresh with valid refresh token)
   - Estimate: 5h

Foundation-First order: ✓
Guide links: [JWT Best Practices](../../docs/guides/jwt-best-practices.md)
```

### Linear Data: Existing Tasks

From `list_issues(parentId=Story.id)`:

**Structure**:
- Task IDs: Linear issue IDs (e.g., "EP7_01", "EP7_02")
- Titles: Task titles
- Descriptions: Full 7 sections (Context, Implementation Plan, Technical Approach, AC, Components, Existing Code Impact, DoD)
- Status: Todo, In Progress, To Review, Done, Canceled

**Example Existing Tasks**:
```
EXISTING TASKS (3 found):
1. EP7_01: Implement token generation endpoint
   Status: Done
   Created: 2025-11-01
   AC: AC1, AC2

2. EP7_02: Validate JWT tokens
   Status: Todo
   Created: 2025-11-05
   AC: AC3 (missing AC4!)

3. EP7_03: Cache tokens in Redis
   Status: Todo
   Created: 2025-11-06
   AC: AC6 (caching requirement)
```

## Comparison Algorithm

### Step 1: Match by Goal

For EACH task in IDEAL plan:

1. **Extract goal** from IDEAL plan task title and description
2. **Search existing tasks** for similar goal:
   - Fuzzy match on titles (e.g., "token generation" matches "Implement token generation")
   - Check AC overlap (do they cover same Story AC?)
   - Look for key terms (e.g., "validation", "refresh", "generation")
3. **Result**:
   - If **match found** → Candidate for KEEP or UPDATE
   - If **no match** → Mark for CREATE

For EACH existing task:

1. **Extract goal** from existing task title and AC
2. **Search IDEAL plan** for similar goal
3. **Result**:
   - If **match found** → Candidate for KEEP or UPDATE
   - If **no match** → Mark for OBSOLETE

### Step 2: Determine Operations

For EACH existing task:

#### KEEP Operation

**Criteria** (ALL must be true):
- ✅ Task exists in IDEAL plan (goal matches)
- ✅ AC unchanged (compare Story AC sections referenced in task)
- ✅ Implementation approach still valid (guide links, patterns)
- ✅ Status: Any except Done or Canceled
- ✅ No structural changes needed (Affected Components same)

**Action**: None (task is already correct)

**Example**:
```
EP7_01: Implement token generation endpoint
- IDEAL plan has: "Token generation endpoint" (AC1, AC2)
- Existing task has: AC1, AC2
- Status: Done
→ KEEP (task matches IDEAL plan, already complete)
```

#### UPDATE Operation

**Criteria** (ANY must be true):
- ⚠️ Task in IDEAL plan BUT AC changed
  - New AC added to Story
  - Existing AC modified (conditions changed)
  - AC removed from task scope
- ⚠️ Technical approach changed
  - New guide links added to Story
  - Architecture patterns updated
  - Technology stack changed
- ⚠️ Affected components changed
  - New files to modify
  - Different layers involved

**Constraints**:
- ✅ Status: Todo or Backlog ONLY
- ❌ If In Progress/To Review → WARNING, manual review needed (don't auto-update)
- ❌ If Done → WARNING, never update Done tasks

**Action**: `update_issue(id, description=new_description)`

**Example**:
```
EP7_02: Validate JWT tokens
- IDEAL plan has: "Token validation middleware" (AC3, AC4)
- Existing task has: AC3 ONLY (AC4 missing!)
- Status: Todo
→ UPDATE (AC4 "Handle expired tokens" added to Story)

Changes to apply:
- Update AC section: Add AC4 scenario
- Update Implementation Plan: Add expiration check phase
- Update Technical Approach: Reference token expiration guide
```

#### OBSOLETE Operation

**Criteria** (ALL must be true):
- ❌ Task NOT in IDEAL plan (no matching goal)
- ❌ Feature removed from Story AC
- ❌ OR functionality merged into different task

**Constraints**:
- ✅ Status: Todo or Backlog ONLY
- ❌ If In Progress/To Review → WARNING, manual review needed (don't auto-cancel)
- ❌ If Done → WARNING, never obsolete Done tasks (work was completed)

**Action**:
```
update_issue(id, state="Canceled")
```
Add comment: "Task canceled due to Story replan. Feature removed from requirements."

**Example**:
```
EP7_03: Cache tokens in Redis
- IDEAL plan does NOT have: Caching task
- Story AC6 (caching requirement) REMOVED
- Status: Todo
→ OBSOLETE (caching is no longer in scope)

Action: Cancel task, preserve history
```

#### CREATE Operation

**Criteria** (ALL must be true):
- ✨ Task in IDEAL plan
- ✨ No existing task matches goal
- ✨ New requirement added to Story

**Action**: `create_issue(title, description, parentId=Story.id, ...)` (same as CREATE MODE)

**Example**:
```
IDEAL plan has: "Email validation" (NEW AC6)
- No existing task for email validation
- New requirement added to Story
→ CREATE (new task needed)

Generate:
- Title: "EP7_04: Validate email format in registration"
- Description: Full 7 sections
- AC: AC6 from Story
- parentId: Story.id
```

### Step 3: Handle Edge Cases

#### Edge Case 1: Obsolete Task In Progress

**Scenario**: Task is marked OBSOLETE but status is In Progress or To Review.

**Problem**: Someone is actively working on this task, auto-canceling would waste work.

**Action**:
```
WARNING: "Task EP7_03 is In Progress but no longer in IDEAL plan. Manual review needed."
- Do NOT auto-cancel
- Show in operations summary with ⚠️ warning
- Let user decide:
  - Complete the task and cancel later?
  - Cancel now and abandon work?
  - Merge work into different task?
```

#### Edge Case 2: UPDATE Task To Review

**Scenario**: Task needs UPDATE (AC changed) but status is To Review (awaiting review).

**Problem**: Task already completed and awaiting review, updating would invalidate the review.

**Action**:
```
WARNING: "Task EP7_02 is To Review but AC changed. Review may need to restart."
- Show diff (old AC vs new AC)
- Let user decide:
  - Update now (review must restart)?
  - Wait for review to complete, then update?
  - Cancel task and create new one?
```

#### Edge Case 3: IDEAL Plan Differs from Done Tasks

**Scenario**: IDEAL plan significantly differs from completed Done tasks.

**Problem**: Work was completed under old requirements, new requirements are different.

**Action**:
```
WARNING: "Story requirements changed significantly. Done tasks may need follow-up work."
- NEVER update or cancel Done tasks (preserve completed work)
- If new requirements conflict with Done work → CREATE new task to address discrepancy
- Example:
  - Done: "EP7_01: Token generation with JWT"
  - IDEAL: "Token generation with OAuth2" (different approach!)
  - Action: CREATE "EP7_04: Migrate token generation to OAuth2"
```

#### Edge Case 4: Multiple Tasks Match Same IDEAL Goal

**Scenario**: Two existing tasks both match same IDEAL plan goal.

**Problem**: Duplicate work, unclear which to keep.

**Action**:
```
WARNING: "Multiple tasks match same IDEAL goal. Manual consolidation needed."
- EP7_02: "Validate JWT tokens" (Todo)
- EP7_05: "Add token validation" (In Progress)
- Both match IDEAL: "Token validation middleware"

Let user decide:
- Keep EP7_05 (In Progress), obsolete EP7_02?
- Merge both into one task?
```

#### Edge Case 5: AC Count Mismatch

**Scenario**: IDEAL plan has 5 AC, but distributed differently across tasks than existing tasks.

**Problem**: AC reassignment between tasks.

**Action**:
```
EXAMPLE:
IDEAL Plan:
- Task 1: AC1, AC2, AC3 (endpoint)
- Task 2: AC4, AC5 (middleware)

Existing Tasks:
- EP7_01: AC1, AC2 (endpoint) - Done
- EP7_02: AC3, AC4, AC5 (middleware) - Todo

Operations:
- EP7_01: KEEP (Done, matches AC1, AC2)
- EP7_02: UPDATE (AC3 moved to Task 1, remove from EP7_02)
  - BUT AC3 implementation may be in EP7_02 code!
  - WARNING: "AC3 reassigned. Manual code review needed."
```

## Example Scenarios

### Scenario 1: AC Change (UPDATE)

**Story**: US001 OAuth Authentication
**Change**: AC4 "Handle expired tokens" ADDED to Story

**IDEAL Plan** (Phase 2):
```
1. Token generation endpoint (AC1, AC2)
2. Token validation middleware (AC3, AC4) ← AC4 NEW!
3. Token refresh logic (AC5)
```

**Existing Tasks**:
```
1. EP7_01: Token generation (AC1, AC2) - Done
2. EP7_02: Validate tokens (AC3 ONLY) - Todo
3. EP7_03: Token refresh (AC5) - In Progress
```

**Comparison**:
```
EP7_01 vs IDEAL Task 1:
- Goals match: ✓ (token generation)
- AC match: ✓ (AC1, AC2)
- Status: Done
→ KEEP

EP7_02 vs IDEAL Task 2:
- Goals match: ✓ (token validation)
- AC match: ✗ (AC3 only, AC4 missing)
- Status: Todo
→ UPDATE (add AC4)

EP7_03 vs IDEAL Task 3:
- Goals match: ✓ (token refresh)
- AC match: ✓ (AC5)
- Status: In Progress
→ KEEP (In Progress, don't interfere)
```

**Operations Summary**:
```
KEEP: 2 tasks (EP7_01 Done, EP7_03 In Progress)
UPDATE: 1 task (EP7_02 add AC4)
OBSOLETE: 0 tasks
CREATE: 0 tasks
```

**Diff for EP7_02 UPDATE**:
```diff
## Acceptance Criteria

- **Given** valid JWT token in Authorization header
  **When** request is made to protected route
  **Then** request proceeds with authenticated user context

+ **Given** expired JWT token in Authorization header
+   **When** request is made to protected route
+   **Then** return 401 Unauthorized with "Token expired" message
```

### Scenario 2: Feature Removed (OBSOLETE)

**Story**: US001 OAuth Authentication
**Change**: Caching requirement REMOVED from Story (AC6 deleted)

**IDEAL Plan** (Phase 2):
```
1. Token generation endpoint (AC1, AC2)
2. Token validation middleware (AC3, AC4)
3. Token refresh logic (AC5)
# NO caching task (AC6 removed)
```

**Existing Tasks**:
```
1. EP7_01: Token generation (AC1, AC2) - Done
2. EP7_02: Validate tokens (AC3, AC4) - Todo
3. EP7_03: Cache tokens in Redis (AC6) - Todo ← AC6 REMOVED!
```

**Comparison**:
```
EP7_01 → KEEP (matches IDEAL Task 1)
EP7_02 → KEEP (matches IDEAL Task 2)
EP7_03 → OBSOLETE (no matching goal in IDEAL plan, AC6 removed)
```

**Operations Summary**:
```
KEEP: 2 tasks
UPDATE: 0 tasks
OBSOLETE: 1 task (EP7_03 caching)
CREATE: 0 tasks
```

**Action for EP7_03**:
```
update_issue(
  id="EP7_03",
  state="Canceled"
)

Add comment:
"Task canceled due to Story replan. Caching requirement (AC6) removed from Story.
Original AC6: Cache JWT tokens in Redis with 1-hour TTL.
Reason: Simplified authentication flow, removed caching complexity."
```

### Scenario 3: New Feature Added (CREATE)

**Story**: US002 User Profile
**Change**: NEW AC4 "Upload avatar" ADDED to Story

**IDEAL Plan** (Phase 2):
```
1. Create profile endpoint (AC1)
2. Update profile endpoint (AC2, AC3)
3. Upload avatar (AC4) ← NEW!
```

**Existing Tasks**:
```
1. EP8_01: Create profile (AC1) - Done
2. EP8_02: Update profile (AC2, AC3) - In Progress
# NO avatar task
```

**Comparison**:
```
EP8_01 → KEEP (matches IDEAL Task 1, Done)
EP8_02 → KEEP (matches IDEAL Task 2, In Progress)
IDEAL Task 3 → CREATE (no existing task for avatar upload)
```

**Operations Summary**:
```
KEEP: 2 tasks
UPDATE: 0 tasks
OBSOLETE: 0 tasks
CREATE: 1 task (avatar upload)
```

**New Task EP8_03**:
```
Title: "EP8_03: Implement avatar upload for user profile"

Description: (7 sections)
- Context: Users need to upload profile pictures
- Implementation Plan: File upload, validation, storage, URL generation
- Technical Approach: Multipart form data, S3/local storage, image processing
- AC: AC4 from Story (upload, size limits, format validation)
- Affected Components: src/api/profile.ts, src/services/storage.ts
- Existing Code Impact: Add storage service, update profile model
- DoD: Upload works, validation enforced, images stored securely

Estimate: 4 hours
parentId: US002
```

### Scenario 4: Scope Reduction (Multiple OBSOLETE)

**Story**: US003 Payment Integration
**Change**: PayPal and Refund APIs REMOVED from scope (simplify to Stripe only)

**IDEAL Plan** (Phase 2):
```
1. Stripe integration (AC1, AC2)
2. Payment webhook (AC3)
# PayPal removed
# Refund API removed
```

**Existing Tasks**:
```
1. EP9_01: Stripe integration (AC1, AC2) - Todo
2. EP9_02: Payment webhook (AC3) - In Progress
3. EP9_03: PayPal integration (AC4) - Todo ← REMOVED!
4. EP9_04: Refund API (AC5) - Todo ← REMOVED!
```

**Comparison**:
```
EP9_01 → KEEP (matches IDEAL Task 1)
EP9_02 → KEEP (matches IDEAL Task 2, In Progress)
EP9_03 → OBSOLETE (PayPal removed)
EP9_04 → OBSOLETE (Refund removed)
```

**Operations Summary**:
```
KEEP: 2 tasks
UPDATE: 0 tasks
OBSOLETE: 2 tasks (EP9_03 PayPal, EP9_04 Refund)
CREATE: 0 tasks
```

**Warning**:
```
⚠️ EP9_02 (Payment webhook) is In Progress.
   Ensure webhook handler still works with reduced scope (Stripe only, no PayPal events).
   Manual review recommended.
```

### Scenario 5: Complex Reassignment

**Story**: US004 Search Functionality
**Change**: AC3 "Pagination" moved from "Search results" task to "Search API" task

**IDEAL Plan** (Phase 2):
```
1. Search API with pagination (AC1, AC2, AC3) ← AC3 moved here!
2. Search results display (AC4, AC5)
# AC3 was in Task 2, now in Task 1
```

**Existing Tasks**:
```
1. EP10_01: Search API (AC1, AC2) - Done
2. EP10_02: Search results (AC3, AC4, AC5) - Todo ← AC3 should move!
```

**Comparison**:
```
EP10_01 vs IDEAL Task 1:
- Goals match: ✓
- AC match: ✗ (AC3 missing, now required)
- Status: Done
→ KEEP (Done, don't update)
→ WARNING: AC3 pagination should be in API but implemented in results!

EP10_02 vs IDEAL Task 2:
- Goals match: ✓
- AC match: ✗ (AC3 should not be here)
- Status: Todo
→ UPDATE? (remove AC3, keep AC4/AC5)
→ WARNING: AC3 code may be in EP10_02, refactoring needed!
```

**Operations Summary**:
```
KEEP: 1 task (EP10_01 Done)
UPDATE: 1 task (EP10_02 remove AC3 reference)
CREATE: 1 task (NEW: Refactor pagination to API)
OBSOLETE: 0 tasks

WARNINGS:
- AC reassignment detected (AC3: results → API)
- EP10_01 is Done, cannot update
- Code refactoring required (move pagination logic)
- Manual intervention needed
```

**Recommended Action**:
```
Create NEW task:
EP10_03: "Refactor pagination from results to API"
- Goal: Move pagination logic from search results component to search API endpoint
- Reason: AC3 reassignment after EP10_01 completion
- Implementation: Extract pagination from EP10_02, integrate into API
- Testing: Ensure backward compatibility, update existing tests
- Estimate: 3 hours
```

## Best Practices

### 1. Be Conservative with Updates

- **Prefer CREATE over UPDATE** when in doubt
- Updating tasks can invalidate work in progress
- Creating new tasks preserves existing work

### 2. Respect Status

- **Never auto-update In Progress/To Review tasks**
- **Never auto-cancel In Progress/To Review tasks**
- **Never update/cancel Done tasks**
- Show warnings, let user decide

### 3. Preserve History

- Use `state="Canceled"` for obsolete tasks (don't delete)
- Add comments explaining why task was canceled
- Reference removed AC numbers and reasons

### 4. Handle AC Reassignment Carefully

- AC moving between tasks is complex
- Code may be in wrong task
- Requires manual refactoring
- Create explicit refactoring tasks

### 5. Show Clear Diffs

- For UPDATE operations, show before/after
- Highlight added/removed AC
- Show technical approach changes
- Make review easy for user

### 6. Warn About Work Loss

- If canceling task with partial work → warning
- If updating task with code changes → warning
- If Done task conflicts with new requirements → create follow-up task

### 7. Foundation-First Validation

- Ensure IDEAL plan respects Foundation-First execution order
- If replan changes order → warning
- Dependencies should flow correctly (Database before Repository before Service before API)

## Output Format

### Operations Summary

```
REPLAN SUMMARY for US001:

IDEAL PLAN (from Story analysis):
1. Token generation endpoint (AC1, AC2)
2. Token validation middleware (AC3, AC4) ← AC4 ADDED!
3. Email validation (NEW AC6) ← NEW!

EXISTING TASKS:
✓ EP7_01: Token generation endpoint
   Status: Done
   Operation: KEEP (matches plan, already Done)

⚠ EP7_02: Token validation middleware
   Status: Todo
   Operation: UPDATE (AC4 added to Story)
   Changes:
     - Add AC4: Handle expired token scenario
     - Update Implementation Plan with expiration check
     - Update Technical Approach: Reference token expiration guide

✗ EP7_03: Cache tokens in Redis
   Status: Todo
   Operation: OBSOLETE (caching removed from Story)
   Action: Cancel task (state="Canceled")

NEW TASKS:
+ EP7_04: Email validation
   Goal: Validate email format in registration
   Estimate: 3 hours
   AC: New AC6 from Story

OPERATIONS: 1 keep, 1 update, 1 cancel, 1 create

WARNINGS:
- EP7_02 will be updated (AC changed)

Type "confirm" to execute all operations.
```

---

**Version:** 1.0.0
**Last Updated:** 2025-11-10