mix validate_tasklist (TaskValidator v0.9.1)

View Source

Validates the format and structure of a TaskList.md file.

Usage

mix validate_tasklist [OPTIONS]

Options

--path       Path to the TaskList.md file (default: ./TaskList.md)

Examples

# Validate default TaskList.md in current directory
mix validate_tasklist

# Validate specific file
mix validate_tasklist --path docs/TaskList.md

# Validate example templates
mix validate_tasklist --path docs/examples/phoenix_web_example.md

Task List Structure

The task list must contain:

  • Current Tasks table (active tasks)
  • Completed Tasks table (finished tasks)
  • Task Details sections for each task

Validation Rules

Task ID Format

  • 2-4 uppercase letters as prefix (e.g., SSH, SCP, ERR)
  • 3-4 digits as sequence number (e.g., 001, 0001)
  • Optional subtask suffix: hyphen + number for numbered subtasks (e.g., SSH0001-1)
  • Optional subtask suffix: letter for checkbox subtasks (e.g., SSH0001a)
  • Examples: SSH0001, SCP0001, ERR001, SSH0001-1, SSH0001a

Status Values

  • Planned - Task not yet started
  • In Progress - Active work (requires subtasks)
  • Review - Under review
  • Completed - Finished (requires additional sections)
  • Blocked - Work blocked

Priority Values

  • Critical - Must be done immediately
  • High - Important, should be prioritized
  • Medium - Normal priority
  • Low - Can be deferred

Error Handling Requirements

Main tasks and subtasks have different error handling requirements:

Main Tasks

Must include comprehensive error handling documentation:

**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

Subtasks

Use simplified error handling format:

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

Common Validation Errors:

  • Using wrong error handling format (e.g., main task format for subtasks)
  • Missing error handling sections
  • Incomplete error handling documentation

Required Sections

Main Tasks

All main tasks must include these sections:

  • Description - What the task accomplishes
  • Status - Current state (Planned, In Progress, etc.)
  • Priority - Task importance (Critical, High, Medium, Low)
  • Dependencies - Other tasks that must be completed first (or "None")
  • Error Handling - Comprehensive error handling documentation
  • Test sections: ExUnit Test Requirements, Integration Test Scenarios
  • TypeSpec sections: Requirements, Documentation, Verification
  • Code Quality KPIs - Metrics for code quality

Additional sections for specific categories:

  • OTP tasks: Process Design, State Management, Supervision Strategy
  • Phoenix tasks: Route Design, Context Integration, Template/Component Strategy
  • Data tasks: Schema Design, Migration Strategy, Query Optimization
  • Business logic: Context Boundaries, Business Rules

Completed Tasks

Completed tasks require additional sections:

  • Implementation Notes - How it was implemented
  • Complexity Assessment - Implementation complexity
  • Maintenance Impact - Long-term maintenance considerations
  • Error Handling Implementation - How errors were handled
  • Review Rating - Quality score (1-5)

Subtask Requirements

  • Must use same prefix as parent task
  • Must have "Status" section
  • If status is "Completed", must have "Review Rating"
  • Review rating format: 1-5 with optional decimal (e.g., 4.5)
  • Review rating can include "(partial)" suffix
  • Can be organized as checkboxes or numbered entries

Subtask Formats

Tasks can organize subtasks in two formats:

1. Checkbox Format (for minor items)

Simple checklist format for quick subtasks:

**Subtasks**
- [x] Basic structure implementation [SSH0001a]
- [ ] Essential features [SSH0001b]
- [ ] Integration testing [SSH0001c]

2. Numbered Format (for major subtasks)

Full format with sections for significant subtasks:

#### 1. Basic structure implementation (SSH0001-1)
**Description**
Implement the core structure with proper error handling

**Status**
Completed

**Review Rating**
4.5

\{\{error-handling-subtask\}\}

Use numbered format when subtasks need detailed tracking, checkbox format for simple items.

Additional Rules

  • Tasks marked as "In Progress" must have at least one subtask
  • All non-completed tasks must have detailed entries
  • No duplicate task IDs allowed
  • All subtasks must use the same prefix as their parent task

Reference System

The validator supports content references to reduce file size by 60-70%:

  • Define references: ## #\{\{reference-name\}\}
  • Use references: \{\{reference-name\}\}
  • Common references: {{error-handling}}, {{test-requirements}}, {{standard-kpis}}
  • The validator only checks existence, not content

Common Validation Errors

  1. Wrong error handling format - Using main task format for subtasks
  2. Missing subtasks - "In Progress" tasks without subtasks
  3. Prefix mismatch - Subtask ID doesn't match parent prefix
  4. Invalid status - Using non-standard status values
  5. Missing sections - Required sections not present
  6. Invalid review rating - Wrong format or out of range

See Also

Example

mix validate_tasklist
mix validate_tasklist --path ./custom/path/TaskList.md

Summary

Functions

Callback implementation for Mix.Task.run/1.

Functions

run(args)

Callback implementation for Mix.Task.run/1.