# TaskValidator Library Instructions for LLMs

## Purpose
TaskValidator is an Elixir library for validating structured Markdown task lists. It ensures task lists follow specific format rules, maintain consistency, and include required documentation sections.

## Core Concepts

### Task Structure
- Tasks have IDs like PREFIX0001 (e.g., SSH0001, PHX0101, DB0301)
- Subtasks append suffixes: SSH0001-1 (numbered) or SSH0001a (checkbox)
- Tasks progress through statuses: Planned → In Progress → Completed
- "In Progress" tasks MUST have subtasks

### Task ID Patterns
```
Main task: [A-Z]{2,4}\d{3,4}
Subtask: [A-Z]{2,4}\d{3,4}(-\d+|[a-z])
```

### Valid Statuses
- Planned
- In Progress (requires subtasks)
- Review
- Completed (requires extra sections)
- Blocked

## Usage Instructions

### 1. Validate a Task List
```elixir
# Validate default location
{:ok, message} = TaskValidator.validate_file("docs/TaskList.md")

# Validate custom file
{:ok, message} = TaskValidator.validate_file("path/to/tasklist.md")

# Handle validation errors
case TaskValidator.validate_file(path) do
  {:ok, message} -> IO.puts("Valid: #{message}")
  {:error, reason} -> IO.puts("Invalid: #{reason}")
end
```

### 2. Create Task List Templates
```bash
# Default Phoenix web template
mix task_validator.create_template

# OTP/GenServer template with custom prefix
mix task_validator.create_template --category otp_genserver --prefix GEN

# Use semantic prefixes
mix task_validator.create_template --category testing --semantic
```

### 3. Categories and Prefixes

| Category | ID Range | Semantic Prefix | Use For |
|----------|----------|-----------------|---------|
| otp_genserver | 0001-0099 | OTP | GenServers, Supervisors, Processes |
| phoenix_web | 0100-0199 | PHX | Controllers, LiveView, Routes |
| business_logic | 0200-0299 | CTX | Contexts, Domain Logic |
| data_layer | 0300-0399 | DB | Schemas, Migrations, Queries |
| infrastructure | 0400-0499 | INF | Deployment, Monitoring |
| testing | 0500-0599 | TST | Tests, Coverage, CI/CD |

## Task List Format

### Required Structure
```markdown
# Project Task List

## Current Tasks
| ID | Description | Status | Priority | Assignee | Review Rating |
| --- | --- | --- | --- | --- | --- |
| PHX0101 | Create user auth | In Progress | High | alice | - |

## Completed Tasks
| ID | Description | Status | Priority | Assignee | Review Rating |
| --- | --- | --- | --- | --- | --- |
| OTP0001 | Setup GenServer | Completed | High | bob | 4.5 |

## Active Task Details
### PHX0101: Create user auth
[detailed sections here]

## Completed Task Details
### OTP0001: Setup GenServer
[detailed sections with extra completion fields]
```

### Required Sections for Main Tasks
```markdown
**Description**
**Status**
**Priority**
**Dependencies**
**Error Handling** (comprehensive format)
**ExUnit Test Requirements**
**Integration Test Scenarios**
**Typespec Requirements**
**TypeSpec Documentation**
**TypeSpec Verification**
**Code Quality KPIs**
```

### Category-Specific Sections
- OTP: Process Design, State Management, Supervision Strategy
- Phoenix: Route Design, Context Integration, Template/Component Strategy
- Data: Schema Design, Migration Strategy, Query Optimization
- Business: Context Boundaries, Business Rules

### Completed Task Extra Sections
```markdown
**Implementation Notes**
**Complexity Assessment**
**Maintenance Impact**
**Error Handling Implementation**
**Review Rating** (1-5, e.g., 4.5)
```

## Subtask Formats

### Numbered Format (Major Subtasks)
```markdown
#### 1. Implement validation (PHX0101-1)
**Description**
Details here

**Status**
Planned

**Error Handling**
**Task-Specific Approach**
- Error pattern for this task
**Error Reporting**
- Monitoring approach
```

### Checkbox Format (Minor Items)
```markdown
**Subtasks**
- [x] Setup routes [PHX0101a]
- [ ] Add controllers [PHX0101b]
- [ ] Create views [PHX0101c]
```

## Error Handling Requirements

### Main Task Error Handling (Comprehensive)
```markdown
**Error Handling**
**Core Principles**
- Pass raw errors
- Use {:ok, result} | {:error, reason}
- Let it crash
**Error Implementation**
- No wrapping
- Minimal rescue
- function/1 & /! versions
**Error Examples**
- Raw error passthrough
- Simple rescue case
- Supervisor handling
**GenServer Specifics**
- Handle_call/3 error pattern
- Terminate/2 proper usage
- Process linking considerations
```

### Subtask Error Handling (Simplified)
```markdown
**Error Handling**
**Task-Specific Approach**
- Error pattern for this task
**Error Reporting**
- Monitoring approach
```

## Reference System

### Define References
```markdown
## #{{error-handling}}
**Error Handling**
[full content here]
```

### Use References
```markdown
{{error-handling}}
```

Common references:
- {{error-handling}} - Main task error handling
- {{error-handling-subtask}} - Subtask error handling
- {{test-requirements}} - Integration-first test requirements
- {{typespec-requirements}} - All TypeSpec sections
- {{standard-kpis}} - Code quality metrics
- {{def-no-dependencies}} - When task has no dependencies

## Validation Rules

1. **Task IDs**: Must match pattern, no duplicates
2. **Subtask Prefixes**: Must match parent (SSH0001 → SSH0001-1)
3. **In Progress Status**: Must have at least one subtask
4. **Completed Tasks**: Need all extra sections and review rating
5. **Error Handling**: Different formats for main tasks vs subtasks
6. **References**: Must be defined if used

## Common Errors and Solutions

| Error | Solution |
|-------|----------|
| "Main task missing error handling" | Add comprehensive error handling format |
| "Subtask using main task error format" | Use simplified subtask format |
| "In Progress without subtasks" | Add numbered or checkbox subtasks |
| "Invalid task ID format" | Use PREFIX#### format (e.g., PHX0101) |
| "Reference not found" | Define reference at bottom of file |
| "Subtask prefix mismatch" | Ensure subtask uses parent's prefix |

## API Functions

```elixir
# Basic validation
TaskValidator.validate_file(path)

# Detailed validation with all errors
TaskValidator.validate_file_detailed(path)

# Pipeline validation (advanced)
TaskValidator.validate_file_with_pipeline(path, opts)
```

## Mix Tasks

```bash
# Show all commands
mix help task_validator

# Validate task list
mix validate_tasklist [--path FILE]

# Create template
mix task_validator.create_template [--category CAT] [--prefix PRE] [--semantic]
```

## Best Practices for LLMs

1. **Creating Tasks**: Start with templates via mix task
2. **Validation**: Always validate after changes
3. **References**: Use to reduce repetition
4. **Categories**: Use semantic prefixes (OTP, PHX, CTX, DB, INF, TST)
5. **Subtasks**: Use numbered for complex, checkbox for simple
6. **Error Handling**: Never mix main/subtask formats
7. **Status Flow**: Planned → In Progress (with subtasks) → Completed
8. **Testing Philosophy**: Integration tests FIRST against real dependencies
   - Test with real databases, processes, files, networks
   - Document actual behavior before any mocking
   - Extract unit tests from integration observations
   - Mocks that don't match reality are worse than no tests

## Quick Examples

### Valid Main Task
```markdown
### PHX0101: User authentication
**Description**
Implement user login system
**Status**
In Progress
**Priority**
High
**Dependencies**
- None
[... all required sections including comprehensive error handling ...]

#### 1. Create login form (PHX0101-1)
**Description**
Build the login form component
**Status**
Planned
**Error Handling**
**Task-Specific Approach**
- Validate user input
**Error Reporting**
- Log failed attempts
```

### Valid Completed Task
```markdown
### OTP0001: GenServer setup
[... all standard sections ...]
**Implementation Notes**
Used standard OTP patterns
**Complexity Assessment**
Low - Standard implementation
**Maintenance Impact**
Low - Well documented
**Error Handling Implementation**
Supervisor handles crashes
**Review Rating**
4.5
```