Task Writing

Comprehensive guide for creating structured, phase-based task files that ensure consistent development workflows.

When to Use This Skill

Use this skill when:

• •Creating a new feature task
• •Documenting a bug fix
• •Planning a refactoring effort
• •Organizing any development work that needs structured phases
• •User requests task creation, work planning, or structured documentation

Core Workflow

Step 1: Understand the Request

Clarify the type of work:

• •Is this a new feature or bug fix?
• •What is the scope and complexity?
• •Are there any specific requirements or constraints?

If unclear, ask the user:

• •"Is this a new feature, bug fix, refactoring, or documentation task?"
• •"What is the main goal or problem being solved?"
• •"Are there any specific technical requirements or constraints?"

Step 2: Analyze the Codebase

Search for similar implementations:

1. •Use scripts/task_analysis.py to find the next task number
2. •Search for similar patterns in the codebase using relevant keywords
3. •Identify existing architecture patterns and conventions
4. •Check for similar features that can serve as reference

Example usage:

cd [project_root]
python _tasks/../scripts/task_analysis.py authentication login user

Analyze dependencies:

• •Review imports/using statements in related files
• •Identify shared libraries and frameworks
• •Note cross-cutting concerns (frontend, backend, database, etc.)
• •Check for potential conflicts with in-progress tasks

Step 3: Determine Task Type

Based on the analysis, select the appropriate template:

• •Feature: New functionality, enhancements (see references/task-type-templates.md - Feature section)
• •Bugfix: Defect repairs, issue fixes (see references/task-type-templates.md - Bugfix section)
• •Refactor: Code improvements without functional changes (see references/task-type-templates.md - Refactor section)
• •Documentation: Documentation updates (see references/task-type-templates.md - Documentation section)
• •Testing: Test coverage improvements (see references/task-type-templates.md - Testing section)

Step 4: Structure the Task into Phases

Phase design principles:

• •Each phase should be independently testable
• •Phases should build on each other logically
• •Keep phases small enough to complete in reasonable time
• •Each phase must end with testing of what changed
• •Specify prerequisites for each phase
• •Include specific test commands for each phase

Typical phase count:

• •Bug fix: 1-3 phases
• •Small feature: 2-4 phases
• •Large feature: 3-5 phases
• •Refactoring: 2-4 phases

Phase structure requirements:

• •Status (pending/in-progress/completed/cancelled)
• •Prerequisites checklist
• •Deliverables checklist
• •Files to modify/create/delete with descriptions
• •Test requirements (coverage >= 80%, security >= 90%)
• •Specific test commands
• •Phase testing description

Step 5: Create the Task File

File location and naming:

1. •Ensure _tasks directory exists at project root (create if missing)
2. •Run scripts/task_analysis.py to get next task number
3. •Create file: _tasks/Task-NNN_DescriptiveTitle.md
   • •NNN is zero-padded number (001, 002, etc.)
   • •Title should be brief and descriptive
   • •Use underscores or hyphens between words

Use the template from references/task-template.md

Fill in all sections:

1. •Frontmatter: id, title, status, priority, created, updated, tags, depends_on, requires_migration, cross_cutting_concerns
2. •Summary: 1-2 sentence overview
3. •Context: Background and justification
4. •Technical Analysis: Current state, similar implementations, proposed solution, dependencies, cross-cutting concerns, risk assessment
5. •Phases: Detailed phase breakdown with all required fields
6. •Definition of Done: Completion criteria
7. •Code Review Checklist: Quality gates
8. •Related Items: Similar implementations, dependencies, blockers
9. •File Change Summary: Track modifications
10. •Notes: Additional considerations

Step 6: Populate Related Items

From codebase analysis:

• •List files with similar implementations found in Step 2
• •Use relative paths from project root
• •Include brief description of what's similar
• •Reference format: path/to/file.ext - Description of similarity

Task dependencies:

• •depends_on: List task IDs this task requires (e.g., [Task-001, Task-005])
• •Blocking tasks: Other tasks waiting on this one
• •Related documentation: Relevant design docs or specifications

Step 7: Add Test Commands

For each phase, include specific test commands:

For .NET projects:

dotnet test --filter Category=FeatureName
dotnet test --filter FullyQualifiedName~ClassName

For Node.js/JavaScript:

npm test -- --coverage
npm test -- path/to/test

For Python:

pytest tests/test_feature.py --cov
python -m pytest --cov=module

Include commands for:

• •Unit tests
• •Integration tests
• •Security tests
• •Performance benchmarks (if applicable)

Step 8: Calculate File Change Summary

After defining all phases, summarize:

• •Count total files to be modified
• •Count total files to be created
• •Count total files to be deleted
• •List all files in each category

Update the File Change Summary section with actual counts and file lists

Guidelines

Code Analysis First

• •Always analyze existing codebase before creating task
• •Look for established patterns and conventions
• •Reference similar implementations in Related Items
• •Maintain consistency with existing architecture

Break Down into Small Steps

• •Smaller phases = easier testing and clearer progress
• •Each phase should have clear, measurable deliverables
• •Test after every phase, not just at the end
• •Allow for incremental progress and early validation

Be Specific and Clear

• •Specify exact expectations for each phase
• •Include concrete test commands, not just "run tests"
• •List specific files to modify/create/delete
• •Define measurable success criteria

Don't Guess - Ask

• •If requirements are unclear, ask for clarification
• •If technical approach is uncertain, present options
• •If scope is ambiguous, seek boundaries
• •Better to ask than make wrong assumptions

Cross-Cutting Concerns

• •Always identify which system areas are affected
• •Mark frontend, backend, database, API, infrastructure
• •Consider impact on existing features
• •Plan for integration testing across boundaries

Migration Awareness

• •Flag when database migrations are required
• •Include migration scripts in deliverables
• •Test migrations in both directions (up/down)
• •Document data transformation logic

Review and Quality

• •Every task includes code review checklist
• •Security considerations must be addressed
• •Performance impact should be assessed
• •Documentation requirements clearly stated

Template Selection

For detailed templates based on task type, read:

• •references/task-type-templates.md - Contains specialized templates for Feature, Bugfix, Refactor, Documentation, and Testing tasks

Example Task Creation Flow

1. •User: "Create a task for adding user authentication"
2. •Run: python scripts/task_analysis.py authentication login user session
3. •Review: Similar implementations found in codebase
4. •Determine: This is a Feature task
5. •Structure: 4 phases (Foundation, Business Logic, API, Integration)
6. •Create: _tasks/Task-023_UserAuthentication.md
7. •Populate: All sections with specific, testable deliverables
8. •Review: Ensure all phases have test requirements and commands