---
name: task-workflow-assistant
description: >-
  Structured analysis and planning of a spec.
  Use when: analyzing a spec, planning its solution, identifying affected files.
  Do NOT use for: pure code implementation, TDD cycle, code review
effort: high
---

# Task Workflow Assistant

## When to use this skill

- You are analyzing a spec
- You are planning its solution
- You are identifying affected files
- You are estimating complexity

---

## 4-file structure

### 1. description.md

**Content:**
- The spec (title, description, acceptance criteria)
- The problem as reported
- Prerequisites and dependencies

**Structure:** Follow the `spec structure` § 1-description

### 2. analysis.md

**Content:**
- Mapping (how the analysis was performed)
- Affected files (with **file:line** references)
- API impact (frontend ↔ backend)

**Structure:** Follow the `spec structure` § 2-analysis

**Example:**
```markdown
## Affected files

### Frontend
- `src/components/UserProfile.tsx:45` - Must update form validation
- `src/api/userApi.ts:12` - Must add new endpoint call

### Backend
- `com/example/api/UserController.kt:78` - Must update DTO
- `com/example/domain/User.kt:23` - Must add new field
```

### 3. solution.md

**Content:**
- Scope (files to change, complexity, estimate)
- TDD-based implementation plan
- Task 0: Write tests (RED phase)
- Tasks 1-N: Implementation (GREEN phase)
- Testing strategy (VERIFY phase)
- Risk analysis
- Each task: concrete, testable, with time estimate

**Structure:** Follow the `spec structure` § 3-solution

**Example:**
```markdown
## Implementation plan

### Task 0: Write tests (RED phase)
- [ ] `UserProfile.test.tsx` - Test new validation (30 min)
- [ ] `UserController.test.kt` - Test new endpoint (30 min)

### Task 1: Implement backend (GREEN phase)
- [ ] Add field to `User.kt` (15 min)
- [ ] Update `UserController.kt` (30 min)
- [ ] Run tests - verify that they pass (10 min)

### Task 2: Implement frontend (GREEN phase)
- [ ] Update `UserProfile.tsx` (45 min)
- [ ] Update `userApi.ts` (15 min)
- [ ] Run tests - verify that they pass (10 min)

### Task 3: Quality check (VERIFY phase)
- [ ] TypeScript check: `npx tsc --noEmit` (5 min)
- [ ] ESLint: `pnpm run eslint` (5 min)
- [ ] All tests: `pnpm test -- --run` (10 min)
```

### 4. status.md

**Content:**
- Progress tracking
- Challenges and solutions
- Tests (status, coverage)
- Deployment status

**Structure:** Follow the `spec structure` § 4-status

---

## Analyze impact

### Frontend vs Backend

Use the API mapping to identify:
- Is this a frontend bug (parsing/rendering)?
- Is this a backend bug (data/logic)?
- Does it affect both layers?

### API impact

```markdown
## API impact

### Changed endpoint
- `GET /api/user/{id}` → Response format changed
- Affected frontend files:
  - `src/api/userApi.ts:12`
  - `src/components/UserProfile.tsx:45`
```

### Complexity

See the workflows rules § Complexity detection for the grading criteria:
Operation, Keywords and API impact decide the grade; Number of files is
a signal, read last, never a floor by itself.

---

## References

- `workflow rules` - Complete workflow documentation
- `documentation standard` - 4-file structure standard
- The project's own API documentation (OpenAPI/mapping), if it has any