# Task Tracking System

> **SCOPE:** Task tracking system workflow and rules ONLY. Contains task lifecycle, naming conventions, and integration rules. DO NOT add: actual task details (→ task files), kanban status (→ kanban_board.md), or implementation guides (→ guides/).

---

## Overview

This folder contains the project's task management system, organizing all development work into trackable units with clear status progression.

### Folder Structure

```
docs/tasks/
├── README.md           # This file - Task tracking workflow and rules
└── kanban_board.md     # Live navigation to active tasks in Linear
```

> [!NOTE]

> All task tracking (Epics, User Stories, tasks) is handled in Linear. Linear is the single source of truth.

**Live Navigation**: [Kanban Board](kanban_board.md)

---

## Core Concepts

### Task Lifecycle

**Workflow:**
```
Backlog/Postponed → Todo → In Progress → To Review → Done
                                              ↓
                                         To Rework → (back to In Progress)
```

**Statuses:**
- **Backlog:** New tasks requiring estimation and approval
- **Postponed:** Deferred tasks for future iterations
- **Todo:** Approved tasks ready for development
- **In Progress:** Currently being developed
- **To Review:** Awaiting code review and validation
- **To Rework:** Needs fixes after review
- **Done:** Completed, reviewed, tested, approved

**Manual Statuses** (not in workflow): Canceled, Duplicate

### Epic Structure

**Organization in Linear:**
- **Epic** = Linear Project (contains all User Stories and tasks for epic)
- **User Story** = Linear Issue with `label: user-story` and `parentId: null`
- **Task** = Linear Issue with `parentId: <UserStoryId>`

**Epic Fields:** Name, description, start date, target date, project lead
**User Story Format:** "As a... I want... So that..." + Given-When-Then acceptance criteria
**Task Format:** Context, requirements, acceptance criteria, implementation notes

### Foundation-First Execution Order

**Critical Rule**: Foundation tasks are executed BEFORE consumer tasks (for testability).

**Definitions**:
- **Foundation** = Database, Repository, core services
- **Consumer** = API endpoints, Frontend components that USE foundation

**Rationale**: Each layer is testable when built (can't test API without working DB).

**Example**:
```
✅ CORRECT EXECUTION ORDER:
  Task 1: Database schema + Repository (foundation)
  Task 2: Service layer with business logic
  Task 3: API endpoint (consumer)
  Task 4: Frontend dashboard (consumer)

❌ WRONG (can't test):
  Task 1: Frontend dashboard calls /api/users
  Task 2: API endpoint (no DB to test against)
```

> **Note:** Consumer-First is for API/interface DESIGN (think from consumer perspective), Foundation-First is for EXECUTION ORDER (build testable foundation first).

---

## Critical Rules

### Rule 1: Linear Integration (MCP Methods ONLY)

**CRITICAL**: Use ONLY `mcp__linear-server__*` methods for all Linear operations.

**PROHIBITED**:
- `gh` command (GitHub CLI)
- GitHub API calls
- Direct Linear API calls
- Manual task creation in Linear UI (for automated workflows)

**Rationale**:
- MCP Linear provides type-safe, validated operations
- Prevents data inconsistencies
- Ensures proper error handling

**See**: [Linear MCP Methods Reference](#linear-mcp-methods-reference) below

---

### Rule 2: Integration Rules

#### Tests

**Rule**: Tests are created ONLY in the final Story task (Story Finalizer test task).

**NEVER** create:
- Separate test tasks during implementation
- Tests in implementation tasks (implementation tasks focus on feature code only)

**Process**:
1. Implementation tasks (1-6 tasks) → To Review → Done
2. ln-340-story-quality-gate Pass 1 → Manual testing
3. ln-350-story-test-planner → Creates Story Finalizer test task
4. ln-334-test-executor → Implements all tests (E2E, Integration, Unit)

**Rationale**: Atomic testing strategy, prevents test duplication, ensures comprehensive coverage.

#### Documentation

**Rule**: Documentation is ALWAYS integrated in feature tasks (same task as implementation).

**NEVER** create:
- Separate documentation tasks
- "Update README" tasks
- "Write API docs" tasks

**Process**: Implementation task includes both code AND documentation updates in Definition of Done.

**Rationale**: Ensures documentation stays in sync with code, prevents documentation debt.

---

### Rule 3: Story-Level Test Strategy

**Value-Based Testing**: Test only scenarios with Priority ≥15 (calculated by Impact × Likelihood).

**Test Limits per Story**:

| Test Type | Min | Max | Purpose |
|-----------|-----|-----|---------|
| **E2E Tests** | 2 | 5 | End-to-end user workflows (Priority ≥15) |
| **Integration Tests** | 3 | 8 | Component interactions, external APIs |
| **Unit Tests** | 5 | 15 | Business logic, edge cases |
| **Total** | 10 | 28 | Complete Story coverage |

**Example**:
```
Story: User Authentication
- E2E: 3 tests (login success, login failure, session expiry)
- Integration: 5 tests (OAuth flow, token refresh, database session storage, Redis cache, logout)
- Unit: 8 tests (password validation, email validation, token generation, permission checks, etc.)
Total: 16 tests (within 10-28 range)
```

**Reference**: [Risk-Based Testing Guide](../reference/guides/risk-based-testing-guide.md) for Priority calculation.

---

### Rule 4: Context Budget Rule

- [ ] **CRITICAL: Minimize context pollution in kanban_board.md**

**Rule:** [kanban_board.md](./kanban_board.md) contains ONLY links and titles - no descriptions, no implementation notes.

**Board Structure:**

Single hierarchical view: **Status → Epic → User Story → Tasks**

**Sections:**
1. **Work in Progress** - Hierarchical task tracking (Backlog → Todo → In Progress → To Review → To Rework → Done → Postponed)
2. **Epics Overview** - Portfolio-level status (Active + Completed epics)

**Format Rules:**

**User Story:**
- Format: `📖 [{{TEAM_KEY}}-XX: USYYY Title](link)` + optional `✅ APPROVED`
- 2-space indent from Epic
- Always shows parent epic context
- Can exist without tasks ONLY in Backlog status (with note: `_(tasks not created yet)_`)

**Task:**
- Format: `  - [{{TEAM_KEY}}-XX: EPYY_ZZ Title](link)` (2-space indent + dash)
- 4-space total indent (2-space base from Story + 2-space for dash)
- Always nested under parent User Story
- Cannot exist without parent story

**Epic Grouping:**
- Each status section grouped by: `**Epic N: Epic Name**` (bold header)
- Stories listed under epic with 2-space indent
- Tasks listed under stories with 4-space indent (2-space base + 2-space for dash)

**Status-Specific Limits:**
- **Backlog:** All stories (tasks optional, use `_(tasks not created yet)_` if none)
- **Todo/In Progress/To Review/To Rework:** All stories with all tasks
- **Done:** Maximum 5 tasks total across all stories (show most recent)
- **Postponed:** All stories with all tasks

**Rationale:**
- Single view eliminates need to "jump" between sections
- Natural hierarchy matches mental model: Status → Epic → Story → Task
- Story context always visible with its tasks
- Reduced cognitive load: one structure, not three
- Minimize context size for AI agents
- Fast navigation at all levels (status/epic/story/task)

---

## Task Workflow

### Planning Guidelines

**Optimal Task Size**: 3-5 hours per task

**Task Granularity**:
- Too small (< 2 hours): Merge with related tasks
- Too large (> 8 hours): Split into subtasks
- Sweet spot (3-5 hours): Maximum productivity, clear acceptance criteria

**Story Limits**:
- Implementation tasks: 1-6 tasks per Story
- Test task: 1 Story Finalizer test task (created after implementation)
- Total: Max 7 tasks per Story

### Workflow Skills

| Category | Skill | Purpose |
|----------|-------|---------|
| **Planning** | ln-210-epic-coordinator | Decompose scope → 3-7 Epics |
| | ln-220-story-coordinator | Decompose Epic → 5-10 Stories (with Phase 3 Library Research) |
| | ln-310-story-decomposer | Decompose Story → 1-6 Implementation Tasks |
| | ln-350-story-test-planner | Plan Story Finalizer test task (after manual testing) |
| **Validation** | ln-320-story-validator | Auto-fix Stories/Tasks → Approve (Backlog → Todo) |
| **Execution** | ln-330-story-executor | Orchestrate Story execution (delegates to ln-31/ln-34/ln-32) |
| | ln-331-task-executor | Execute implementation tasks (Todo → In Progress → To Review) |
| | ln-334-test-executor | Execute Story Finalizer test tasks (11 sections) |
| | ln-332-task-reviewer | Review tasks (To Review → Done/Rework) |
| | ln-333-task-rework | Fix tasks after review (To Rework → To Review) |
| **Quality** | ln-340-story-quality-gate | Two-pass review (Code Quality → Regression → Manual Testing) |
| | ln-341-code-quality-checker | Analyze code for DRY/KISS/YAGNI violations |
| | ln-342-regression-checker | Run existing test suite |
| | ln-343-manual-tester | Perform manual testing via curl/puppeteer |
| **Documentation** | ln-114-project-docs-creator | Create project docs (requirements, architecture, specs) |
| | ln-322-adr-creator | Create ADRs (architecture decisions) |
| | ln-321-guide-creator | Create guides (reusable patterns) |
| | ln-323-manual-creator | Create manuals (API references) |

---

## Project Configuration

### Quality Commands

```bash
# Docker development environment
{{DOCKER_COMMAND}}

# Run tests
{{TEST_COMMAND}}

# Run tests with coverage
{{COVERAGE_COMMAND}}

# Type checking
{{TYPE_CHECK_COMMAND}}

# Linting
{{LINT_COMMAND}}
```

### Documentation Structure

Core documentation:
- [Requirements](../project/requirements.md) - Functional requirements (FR-XXX-NNN) with MoSCoW prioritization
- [Architecture](../project/architecture.md) - System architecture (C4 Model, arc42)
- [Technical Specification](../project/technical_specification.md) - Implementation details
- [ADRs](../reference/adrs/) - Architecture Decision Records
- [Guides](../reference/guides/) - Project patterns and best practices
- [Manuals](../reference/manuals/) - Package API references

### Label Taxonomy

**Functional Labels**: `feature`, `bug`, `refactoring`, `documentation`, `testing`, `infrastructure`

**Type Labels**: `user-story`, `implementation-task`, `test-task`

**Status Labels** (auto-managed by Linear): `backlog`, `todo`, `in-progress`, `to-review`, `to-rework`, `done`, `canceled`

### Test Audit History (Optional)

**Test Audit:** Every +50 tests → review new files, delete framework tests. Last: {{AUDIT_DATE}} ({{OLD_COUNT}} → {{NEW_COUNT}})

---

## Linear MCP Methods Reference

### Core Operations

**Issues**:

```python
# List issues
mcp__linear-server__list_issues(
    team="TeamName",           # Team name or ID
    state="In Progress",       # State name or ID
    assignee="me",             # User ID, name, email, or "me"
    limit=50                   # Max 250
)

# Get issue details
mcp__linear-server__get_issue(
    id="PROJ-123"              # Issue ID
)

# Create issue
mcp__linear-server__create_issue(
    team="TeamName",           # Required: Team name or ID
    title="Task title",        # Required: Issue title
    description="...",         # Markdown description
    state="Todo",              # State name or ID
    assignee="me",             # User ID, name, email, or "me"
    parentId="parent-uuid",    # For tasks (parent Story UUID)
    labels=["feature", "backend"]  # Label names or IDs
)

# Update issue
mcp__linear-server__update_issue(
    id="PROJ-123",             # Required: Issue ID
    state="Done",              # State name or ID
    description="...",         # Updated description
    assignee="me"              # Reassign
)
```

**Projects** (Epics):

```python
# List projects
mcp__linear-server__list_projects(
    team="TeamName",           # Filter by team
    state="started",           # Filter by state
    limit=50
)

# Get project
mcp__linear-server__get_project(
    query="Epic 1"             # ID or name
)

# Create project (Epic)
mcp__linear-server__create_project(
    team="TeamName",           # Required
    name="Epic 1: Auth",       # Required
    description="...",         # Epic description
    state="planned"            # Epic state
)

# Update project
mcp__linear-server__update_project(
    id="project-uuid",         # Required
    state="started",           # Update state
    description="..."          # Update description
)
```

**Teams**:

```python
# List teams
mcp__linear-server__list_teams()

# Get team
mcp__linear-server__get_team(
    query="TeamName"           # UUID, key, or name
)
```

**Labels**:

```python
# List labels
mcp__linear-server__list_issue_labels(
    team="TeamName"            # Optional: filter by team
)

# Create label
mcp__linear-server__create_issue_label(
    name="backend",            # Required
    color="#FF5733",           # Hex color
    teamId="team-uuid"         # Optional: team-specific label
)
```

**Comments**:

```python
# List comments
mcp__linear-server__list_comments(
    issueId="issue-uuid"       # Required
)

# Create comment
mcp__linear-server__create_comment(
    issueId="issue-uuid",      # Required
    body="Comment text"        # Required: Markdown
)
```

### Parameter Patterns

**Common Filters**:

```python
# By assignee
assignee="me"                  # Current user
assignee="user@example.com"    # By email
assignee="user-uuid"           # By UUID

# By state
state="Todo"                   # By name
state="state-uuid"             # By UUID

# By team
team="TeamName"                # By name
team="team-uuid"               # By UUID

# By label
label="feature"                # By name
label="label-uuid"             # By UUID
```

**Pagination**:

```python
# Limit results
limit=50                       # Default: 50, Max: 250

# Pagination
after="cursor-id"              # Start from cursor
before="cursor-id"             # End at cursor
```

**Date Filters**:

```python
# ISO-8601 date-time
createdAt="2025-01-01T00:00:00Z"

# Duration (relative)
createdAt="-P1D"               # Created in last 1 day
updatedAt="-P7D"               # Updated in last 7 days
```

### Examples

**Example 1: Get all In Progress tasks for current user**

```python
issues = mcp__linear-server__list_issues(
    team="ProjectTeam",
    state="In Progress",
    assignee="me",
    limit=100
)
```

**Example 2: Create Story (User Story)**

```python
story = mcp__linear-server__create_issue(
    team="ProjectTeam",
    title="US001 User Login",
    description="User story description...",
    state="Backlog",
    labels=["user-story", "feature"]
)
```

**Example 3: Create Task (child of Story)**

```python
task = mcp__linear-server__create_issue(
    team="ProjectTeam",
    title="EP1_01 Implement JWT tokens",
    description="Task description...",
    state="Todo",
    parentId="story-uuid",      # Link to parent Story
    labels=["implementation-task", "backend"]
)
```

**Example 4: Move task to Done**

```python
mcp__linear-server__update_issue(
    id="PROJ-123",
    state="Done"
)
```

**Example 5: Create Epic (Project)**

```python
epic = mcp__linear-server__create_project(
    team="ProjectTeam",
    name="Epic 1: Authentication System",
    description="Epic description...",
    state="planned"
)
```

---

## Maintenance

**Update Triggers**:
- When adding new workflow skills
- When changing task lifecycle statuses
- When updating Critical Rules
- When modifying Linear integration patterns
- When changing test strategy limits

**Verification**:
- All Linear MCP method examples are valid
- Workflow skills table matches available skills
- Critical Rules align with current development principles
- Test limits match risk-based testing guide

**Last Updated**: {{DATE}}

---

**Template Version:** 1.0.0
**Template Last Updated:** 2025-11-15