# Dependency Graph Patterns

Visual patterns for task dependency design with trade-offs.

## Pattern 1: Fully Independent (Maximum Parallelism)

```
Task A ─┐
Task B ─┼─→ Final Integration
Task C ─┘
```

- **Parallelism**: Maximum — all tasks run simultaneously
- **Risk**: Integration may reveal incompatibilities late
- **Use when**: Tasks operate on completely separate files/modules
- **TaskCreate**: No blockedBy relationships; integration task blocked by all

## Pattern 2: Sequential Chain (No Parallelism)

```
Task A → Task B → Task C → Task D
```

- **Parallelism**: None — each task waits for the previous
- **Risk**: Bottleneck at each step; one delay cascades
- **Use when**: Each task depends on the output of the previous (avoid if possible)
- **TaskCreate**: Each task blockedBy the previous

## Pattern 3: Diamond (Shared Foundation)

```
           ┌→ Task B ─┐
Task A ──→ ┤          ├→ Task D
           └→ Task C ─┘
```

- **Parallelism**: B and C run in parallel after A completes
- **Risk**: A is a bottleneck; D must wait for both B and C
- **Use when**: B and C both need output from A (e.g., shared types)
- **TaskCreate**: B and C blockedBy A; D blockedBy B and C

## Pattern 4: Fork-Join (Phased Parallelism)

```
Phase 1:  A1, A2, A3  (parallel)
          ────────────
Phase 2:  B1, B2      (parallel, after phase 1)
          ────────────
Phase 3:  C1          (after phase 2)
```

- **Parallelism**: Within each phase, tasks are parallel
- **Risk**: Phase boundaries add synchronization delays
- **Use when**: Natural phases with dependencies (build → test → deploy)
- **TaskCreate**: Phase 2 tasks blockedBy all Phase 1 tasks

## Pattern 5: Pipeline (Streaming)

```
Task A ──→ Task B ──→ Task C
  └──→ Task D ──→ Task E
```

- **Parallelism**: Two parallel chains
- **Risk**: Chains may diverge in approach
- **Use when**: Two independent feature branches from a common starting point
- **TaskCreate**: B blockedBy A; D blockedBy A; C blockedBy B; E blockedBy D

## Anti-Patterns

### Circular Dependency (Deadlock)

```
Task A → Task B → Task C → Task A  ✗ DEADLOCK
```

**Fix**: Extract shared dependency into a separate task that all three depend on.

### Unnecessary Dependencies

```
Task A → Task B → Task C
(where B doesn't actually need A's output)
```

**Fix**: Remove the blockedBy relationship; let B run independently.

### Star Pattern (Single Bottleneck)

```
     ┌→ B
A →  ├→ C  → F
     ├→ D
     └→ E
```

**Fix**: If A is slow, all downstream tasks are delayed. Try to parallelize A's work.

# Task Decomposition Examples

Practical examples of decomposing features into parallelizable tasks with clear ownership.

## Example 1: User Authentication Feature

### Feature Description

Add email/password authentication with login, registration, and profile pages.

### Decomposition (Vertical Slices)

**Stream 1: Login Flow** (implementer-1)

- Owned files: `src/pages/login.tsx`, `src/api/login.ts`, `tests/login.test.ts`
- Requirements: Login form, API endpoint, input validation, error handling
- Interface: Imports `AuthResponse` from `src/types/auth.ts`

**Stream 2: Registration Flow** (implementer-2)

- Owned files: `src/pages/register.tsx`, `src/api/register.ts`, `tests/register.test.ts`
- Requirements: Registration form, API endpoint, email validation, password strength
- Interface: Imports `AuthResponse` from `src/types/auth.ts`

**Stream 3: Shared Infrastructure** (implementer-3)

- Owned files: `src/types/auth.ts`, `src/middleware/auth.ts`, `src/utils/jwt.ts`
- Requirements: Type definitions, JWT middleware, token utilities
- Dependencies: None (other streams depend on this)

### Dependency Graph

```
Stream 3 (types/middleware) ──→ Stream 1 (login)
                             └→ Stream 2 (registration)
```

## Example 2: REST API Endpoints

### Feature Description

Add CRUD endpoints for a new "Projects" resource.

### Decomposition (By Layer)

**Stream 1: Data Layer** (implementer-1)

- Owned files: `src/models/project.ts`, `src/migrations/add-projects.ts`, `src/repositories/project-repo.ts`
- Requirements: Schema definition, migration, repository pattern
- Dependencies: None

**Stream 2: Business Logic** (implementer-2)

- Owned files: `src/services/project-service.ts`, `src/validators/project-validator.ts`
- Requirements: CRUD operations, validation rules, business logic
- Dependencies: Blocked by Stream 1 (needs model/repository)

**Stream 3: API Layer** (implementer-3)

- Owned files: `src/routes/projects.ts`, `src/controllers/project-controller.ts`
- Requirements: REST endpoints, request parsing, response formatting
- Dependencies: Blocked by Stream 2 (needs service layer)

## Task Template

```markdown
## Task: {Stream Name}

### Objective

{1-2 sentence description of what to build}

### Owned Files

- {file1} — {purpose}
- {file2} — {purpose}

### Requirements

1. {Specific deliverable 1}
2. {Specific deliverable 2}
3. {Specific deliverable 3}

### Interface Contract

- Exports: {types/functions this stream provides}
- Imports: {types/functions this stream consumes from other streams}

### Acceptance Criteria

- [ ] {Verifiable criterion 1}
- [ ] {Verifiable criterion 2}
- [ ] {Verifiable criterion 3}

### Out of Scope

- {Explicitly excluded work}
```