task-decomposer

What this skill does

# Task Decomposer

Transform high-level Linear tasks into structured, actionable subtasks with comprehensive analysis. Optimize for team efficiency, testability, and risk management.

## Overview

Break down complex tasks into:
- **Actionable subtasks** - Clear, specific work items
- **Testifiable chunks** - Each with validation criteria
- **Decomposition rationale** - Why this breakdown makes sense
- **As-is → To-be analysis** - Current vs. desired state
- **Expected outputs** - Concrete deliverables per subtask
- **Risk assessment** - Potential blockers and mitigation

## Basic Workflow

### 1. Analyze the Task

Understand the complete scope:
```
Input: "Implement user authentication system"
```

Run analysis:
```bash
python scripts/analyze_task.py "Implement user authentication system" --project backend
```

### 2. Generate Decomposition

Receive structured breakdown:
- Subtask list with estimates
- Dependency graph
- Testing criteria
- Risk matrix
- Linear-ready format

### 3. Review and Refine

Validate decomposition:
- Check for completeness
- Verify dependencies
- Assess estimates
- Confirm testability

### 4. Export to Linear

Create Linear issues:
```bash
python scripts/analyze_task.py "..." --export-linear --team-id TEAM123
```

## Decomposition Framework

### Core Principles

**Actionable:**
Each subtask should be:
- Specific and concrete
- Assignable to one person
- Completable in 1-4 hours
- Independently testable

**Testifiable:**
Every subtask includes:
- Acceptance criteria
- Test scenarios
- Verification steps
- Success metrics

**Structured:**
Organized by:
- Dependencies (what blocks what)
- Priority (critical path items)
- Complexity (risk assessment)
- Domain (frontend, backend, etc.)

### Analysis Components

#### 1. Decomposition Rationale

Explain the breakdown logic:

```markdown
## Rationale

**Why 5 subtasks?**
- Authentication flow has 3 distinct phases: capture, verify, persist
- Each phase requires separate testing
- Frontend and backend work can proceed in parallel
- Security review is critical path item

**Why this grouping?**
- Backend API development unblocks frontend work
- Database schema must exist before API implementation
- Security review happens after basic implementation
- Integration tests require all components complete
```

#### 2. As-Is → To-Be Analysis

Document current state and goal state:

```markdown
## State Analysis

**As-Is (Current State):**
- No user authentication
- Open API endpoints
- No session management
- No access control

**To-Be (Desired State):**
- JWT-based authentication
- Protected API endpoints
- Secure session handling
- Role-based access control
- Password reset flow
- Account lockout after failed attempts

**Gap Analysis:**
- Need database schema for users and sessions
- Need password hashing mechanism
- Need JWT generation and validation
- Need middleware for protected routes
- Need frontend login/registration forms
- Need security audit
```

#### 3. Expected Outputs

Define deliverables per subtask:

```markdown
## Subtask 1: Database Schema Design
**Outputs:**
- `schema/users.sql` - User table definition
- `schema/sessions.sql` - Session table definition
- Migration script with rollback
- Schema documentation

## Subtask 2: Password Hashing Service
**Outputs:**
- `services/auth/hasher.py` - Bcrypt implementation
- Unit tests (>90% coverage)
- API documentation
- Performance benchmarks

## Subtask 3: JWT Token Service
**Outputs:**
- `services/auth/jwt.py` - Token generation/validation
- Unit tests with mocked scenarios
- Token expiration handling
- Refresh token logic
```

#### 4. Risk Assessment

Identify and mitigate risks:

```markdown
## Risks & Mitigation

### HIGH Risk
**Security vulnerabilities**
- Impact: System breach, data exposure
- Probability: Medium
- Mitigation: External security audit, penetration testing
- Owner: Security team

**Password storage weakness**
- Impact: Credential compromise
- Probability: Low (using bcrypt)
- Mitigation: Use industry-standard bcrypt, security review
- Owner: Backend lead

### MEDIUM Risk
**JWT secret management**
- Impact: Token forgery
- Probability: Medium
- Mitigation: Environment variables, secret rotation policy
- Owner: DevOps

**Performance degradation**
- Impact: Slow authentication
- Probability: Low
- Mitigation: Benchmark tests, caching strategy
- Owner: Backend team

### LOW Risk
**Browser compatibility**
- Impact: Some users can't authenticate
- Probability: Low (modern APIs)
- Mitigation: Test on major browsers, polyfills
- Owner: Frontend team
```

## Output Format

### Linear-Ready Subtasks

```markdown
# Task: Implement User Authentication System

## Subtasks

### 1. Design Database Schema for Authentication
**Priority:** P0 (Critical Path)
**Estimate:** 2 hours
**Labels:** backend, database, security
**Dependencies:** None

**Description:**
Create user and session tables with proper indexing and constraints.

**Acceptance Criteria:**
- [ ] Users table with email, password_hash, created_at
- [ ] Sessions table with token, user_id, expires_at
- [ ] Unique index on users.email
- [ ] Foreign key from sessions to users
- [ ] Migration script with rollback

**Testing:**
- [ ] Run migration on test database
- [ ] Verify constraints prevent duplicate emails
- [ ] Verify cascade deletion works
- [ ] Test rollback functionality

**Expected Output:**
- `migrations/001_create_auth_schema.sql`
- Schema documentation in `docs/database.md`

**Risks:**
- None (foundational task)

---

### 2. Implement Password Hashing Service
**Priority:** P0 (Critical Path)
**Estimate:** 3 hours
**Labels:** backend, security
**Dependencies:** #1 (database schema)

**Description:**
Create secure password hashing using bcrypt with configurable rounds.

**Acceptance Criteria:**
- [ ] Hash passwords with bcrypt (12 rounds minimum)
- [ ] Verify password against hash
- [ ] Handle encoding edge cases
- [ ] Unit tests >90% coverage

**Testing:**
- [ ] Test password hashing is deterministic
- [ ] Test verification accepts correct passwords
- [ ] Test verification rejects incorrect passwords
- [ ] Test edge cases (empty, very long, special chars)

**Expected Output:**
- `services/auth/hasher.py`
- `tests/test_hasher.py` (>90% coverage)
- API documentation

**Risks:**
- LOW: Bcrypt dependency issues (mitigation: pin version)

---

### 3. Implement JWT Token Service
**Priority:** P0 (Critical Path)
**Estimate:** 4 hours
**Labels:** backend, security
**Dependencies:** None (can parallel with #1-2)

**Description:**
Generate and validate JWT tokens with expiration and refresh logic.

**Acceptance Criteria:**
- [ ] Generate JWT with user_id payload
- [ ] Set expiration (configurable, default 1 hour)
- [ ] Validate token signature and expiration
- [ ] Generate refresh tokens (7 day expiration)
- [ ] Blacklist mechanism for logout

**Testing:**
- [ ] Test token generation includes correct claims
- [ ] Test expired tokens fail validation
- [ ] Test invalid signatures fail validation
- [ ] Test refresh token flow
- [ ] Test blacklist prevents token reuse

**Expected Output:**
- `services/auth/jwt.py`
- `tests/test_jwt.py`
- Environment variable documentation

**Risks:**
- MEDIUM: JWT secret management (mitigation: document env vars)

---

### 4. Build Authentication API Endpoints
**Priority:** P0 (Critical Path)
**Estimate:** 4 hours
**Labels:** backend, api
**Dependencies:** #1, #2, #3

**Description:**
Create /register, /login, /logout, /refresh endpoints with validation.

**Acceptance Criteria:**
- [ ] POST /register - Create user account
- [ ] POST /login - Authenticate and return JWT
- [ ] POST /logout - Invalidate token
- [ ] POST /refresh - Get new access token
- [ ] Input validation and error handling
- [ ] Rate limiting on auth endpoints

**Testing:**
- [ ] Test successful registration flow
- [ ] Test duplicate email rejection
- [ ] Test successful login flow
- [ ] Test invalid credentials rejection
- [ ] Test logout invalidates token
- [ ] Test ref