Writing Compliant Task Lists
View SourceThis guide explains how to create task lists that comply with the TaskValidator
specifications.
Task List Structure
A compliant task list has two main sections:
## Current Tasks
| ID | Description | Status | Priority |
| ------- | -------------------- | ----------- | -------- |
| SSH0001 | SSH authentication | In Progress | High |
| SCP0001 | File transfer module | Planned | Medium |
| ERR001 | Error handling | In Progress | High |
## Completed Tasks
| ID | Description | Status | Completed By | Review Rating |
| ------- | -------------- | --------- | ------------ | ------------- |
| SSH0002 | Key generation | Completed | @developer1 | 4.5 |
Task ID Format
Task IDs must follow this pattern:
- 2-4 uppercase letters as a prefix (representing a component or module)
- 3-4 digits as a sequential number
- Optional suffix for subtasks:
- Numeric:
-1
,-2
(e.g., SSH0001-1) - Letter:
a
,b
,c
for checkbox style (e.g., SSH0001a)
- Numeric:
Examples:
SSH0001
- Main task for SSH componentSSH0001-1
- First subtask of SSH0001 (numeric style)SSH0001a
- First subtask of SSH0001 (checkbox style)ERR001
- Error handling task (3-digit IDs allowed)SCP0005
- File transfer task
Task Categories
Task numbers fall into specific categories:
- Core Infrastructure (1-99): Essential system components
- Features (100-199): User-facing functionality
- Documentation (200-299): Documentation tasks
- Testing (300-399): Test implementation
Each category has specific required sections (see Category-Specific Requirements below).
Error Handling Requirements
Main tasks and subtasks have different error handling documentation requirements.
Main Tasks Error Handling Format
Main tasks must include comprehensive error handling sections that follow this format:
**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 Error Handling Format
Subtasks have a simplified error handling format:
**Error Handling**
**Task-Specific Approach**
- Error pattern for this task
**Error Reporting**
- Monitoring approach
These sections ensure consistent error handling practices across the project while providing appropriate level of detail for each task type. Tasks without proper error handling sections will fail validation.
Detailed Task Entries
Each task needs a detailed entry with the following format:
### SSH0001: Implement SSH authentication module
**Description**
Develop the SSH authentication module supporting key-based and password authentication.
**Simplicity Progression Plan**
1. Start with basic password auth
2. Add key-based auth
3. Refine error handling
**Simplicity Principle**
Progressive enhancement
**Abstraction Evaluation**
Medium - abstracts authentication but maintains clear interfaces
**Requirements**
- Support for password auth
- Support for public key auth
- Configurability of allowed auth methods
**ExUnit Test Requirements**
- Test both auth methods
- Test failure scenarios
- Mock SSH server for integration tests
**Integration Test Scenarios**
- Auth with valid/invalid password
- Auth with valid/invalid key
- Auth with disabled methods
**Typespec Requirements**
- Define types for credentials
- Define auth result types
**TypeSpec Documentation**
All types should be documented clearly
**TypeSpec Verification**
Use Dialyzer to verify type correctness
**Status**
In Progress
**Priority**
High
**Architecture Notes**
Modular authentication system design
**Complexity Assessment**
Medium - Multi-method authentication support
**Dependencies**
- ERR001 (Error handling framework must be complete)
- AUTH005 (Authentication interface design)
**Code Quality KPIs**
- Functions per module: 4
- Lines per function: 12
- Call depth: 2
**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**
- [x] Connection setup [SSH0001a]
- [ ] Authentication flow [SSH0001b]
- [ ] Session establishment [SSH0001c]
#### 1. Implement password authentication (SSH0001-1)
**Status**
Completed
**Review Rating**
4.5
#### 2. Add key-based authentication (SSH0001-2)
**Status**
In Progress
#### 1. Implement password authentication (SSH0001-1)
**Description**
Initial implementation of password-based authentication.
**Error Handling**
**Task-Specific Approach**
- Handle invalid credentials with specific error tuples
- Use clean separation for auth failures vs. connection failures
**Error Reporting**
- Log auth attempts with appropriate level (info/warn)
- Track failed attempts for rate limiting
**Status**
Completed
**Review Rating**
4.5
#### 2. Add key-based authentication (SSH0001-2)
**Description**
Support for RSA and ED25519 keys with proper validation.
**Error Handling**
**Task-Specific Approach**
- Return descriptive error for invalid key formats
- Handle key verification timeout with custom error
**Error Reporting**
- Log key verification attempts
- Report metrics on key type usage
**Status**
In Progress
Status Values
Valid status values are:
Planned
In Progress
Review
Completed
Blocked
Priority Values
Valid priority values are:
Critical
High
Medium
Low
Review Ratings
For completed tasks, include a review rating:
- Scale of 1-5 with optional decimal (e.g.,
4.5
) - Can include
(partial)
suffix for partially meeting requirements
Required Sections for Completed Tasks
When a task is marked as "Completed", it must include these additional sections:
Implementation Notes Describe the implementation approach and patterns used.
Complexity Assessment Assess the final complexity level (High/Medium/Low) and explain why.
Maintenance Impact Evaluate the maintenance burden and any special considerations.
Example:
**Implementation Notes**
Elegant indirection pattern using Registry for PID resolution
**Complexity Assessment**
Low - Used built-in Registry with minimal custom code
**Maintenance Impact**
Low - Self-contained solution with clear interface
Dependencies Field
Tasks should specify their dependencies on other tasks:
**Dependencies**
- SSH0001 (Authentication must be complete)
- ERR001 (Error handling framework required)
- None (for tasks with no dependencies)
The validator ensures all referenced task IDs exist in the task list.
Code Quality KPIs
All tasks must include code quality metrics:
**Code Quality KPIs**
- Functions per module: 3
- Lines per function: 10
- Call depth: 2
These metrics must adhere to the following limits:
- Maximum functions per module: 5
- Maximum lines per function: 15
- Maximum call depth: 2
Checkbox Subtasks
Subtasks can use checkbox format for better visual tracking:
**Subtasks**
- [x] Connection setup [SSH0001a]
- [ ] Authentication flow [SSH0001b]
- [ ] Session establishment [SSH0001c]
Note the letter suffix (a, b, c) instead of numeric suffix (-1, -2, -3).
Category-Specific Requirements
Different task categories require different sections:
Core Infrastructure Tasks (1-99)
Required sections:
- Architecture Decision
- System Impact
- Dependency Analysis
Feature Tasks (100-199)
Required sections:
- Feature Specification
- User Impact
- Integration Points
Documentation Tasks (200-299)
Required sections:
- Documentation Scope
- Target Audience
- Related Documents
Testing Tasks (300-399)
Required sections:
- Test Coverage
- Test Categories
- Performance Impact
Using Reference Definitions
To reduce repetition and maintain consistency, use reference definitions for common sections:
Define references at the end of your task list:
## Reference Definitions ### error-handling-main **Error Handling** **Core Principles** - Pass raw errors - Use {:ok, result} | {:error, reason} - Let it crash ...
Use references in tasks:
### SSH0001: Some task **Description** Task description here {{error-handling-main}} **Status**: Planned
Common reference definitions:
{{error-handling-main}}
- Full error handling for main tasks{{error-handling-subtask}}
- Simplified error handling for subtasks{{standard-kpis}}
- Standard code quality KPIs
Complete Example with References
### SSH0001: Implement authentication module
**Description**: Create a secure authentication module for SSH connections
**Simplicity Progression Plan**: Start with basic auth, then add advanced features
**Simplicity Principle**: Clear separation of authentication concerns
**Abstraction Evaluation**: Keep implementation details hidden behind clean API
**Requirements**: Support password and key-based authentication
**ExUnit Test Requirements**: Test all authentication methods
**Integration Test Scenarios**: Test with real SSH connections
**Typespec Requirements**: Define authentication types and response structures
**TypeSpec Documentation**: Document authentication interface contracts
**TypeSpec Verification**: Use Dialyzer to verify authentication types
**Status**: In Progress
**Priority**: High
**Architecture Notes**: Modular authentication system design
**Complexity Assessment**: Medium - Multi-method authentication support
**Dependencies**
- ERR001 (Error handling framework must be complete)
{{standard-kpis}}
{{error-handling-main}}
**Subtasks**
- [x] Connection setup [SSH0001a]
- [ ] Authentication flow [SSH0001b]
Common Validation Errors
- Missing error handling sections - All tasks and subtasks must include complete error handling documentation
- Incomplete error handling documentation - All three error handling subsections (Core Principles, Implementation, Examples) are required
- Missing detailed entries - All non-completed tasks need detailed entries
- Missing required sections - Ensure all required sections are present
- Missing completion details - Completed tasks must include implementation notes, complexity assessment and maintenance impact
- Inconsistent subtask prefixes - Subtasks must use same prefix as parent
- In Progress tasks without subtasks - Any "In Progress" task needs subtasks
- Invalid status values - Must be one of the valid status values
- Missing review ratings - Completed subtasks need review ratings
- Invalid dependencies - Referenced task IDs must exist
- KPI violations - Code quality metrics exceed maximum limits
- Invalid task category - Task number doesn't match prefix category
- Missing category-specific sections - Required sections based on task category are missing