001-jeremy-taskwarrior-integration

What This Skill Does

This skill enforces mandatory Taskwarrior integration for ALL coding activities. It ensures every piece of work is:

1. Decomposed into trackable Taskwarrior tasks BEFORE code is written
2. Tracked with proper attributes (project, priority, due date, tags)
3. Time-accounted via automatic Timewarrior integration
4. Dependency-managed for complex multi-step projects
5. Completed with proper task lifecycle (add → start → done)

CRITICAL: NO CODE IS WRITTEN until Taskwarrior tasks are created and started.

When This Skill Activates

Trigger this skill when you mention:

• "taskwarrior"
• "task warrior"
• "tw" (as abbreviation)
• "create a task for this"
• "track this work"
• "add to taskwarrior"
• "start a task"
• "task management"
• "time tracking"

Complete Taskwarrior Integration Protocol

Phase 1: Task Decomposition (MANDATORY FIRST STEP)

Before writing ANY code, decompose the request into Taskwarrior tasks:

For Simple Requests (1 task):

task add "Brief description of work" project:ProjectName priority:H/M/L due:today/tomorrow/YYYY-MM-DD +tag1 +tag2

For Complex Requests (multiple tasks with dependencies):

# Parent task
task add "Main project goal" project:ProjectName priority:H due:3days +architecture +planning

# Subtasks with dependencies
task add "Subtask 1" project:ProjectName depends:1 priority:M +implementation
task add "Subtask 2" project:ProjectName depends:2 priority:M +testing
task add "Subtask 3" project:ProjectName depends:3 priority:L +documentation

Required Task Attributes:

• project: Categorize the work (e.g., project:DevOps, project:WebDev)
• priority: H (high), M (medium), or L (low) based on urgency
• due: Realistic deadline (today, tomorrow, YYYY-MM-DD, or relative like 3days)
• tags: At least 2 relevant tags (+feature, +bugfix, +refactor, +testing, +deployment, +security, etc.)

Phase 2: Task Activation & Time Tracking

After creating tasks, activate them to start time tracking:

# Start the first task in the dependency chain
task <ID> start

# Verify task is active
task active

# Timewarrior should automatically begin tracking
timew

What happens:

• Taskwarrior marks task as started
• Timewarrior begins tracking time spent
• Task appears in task active list
• Urgency score increases for started tasks

Phase 3: Code Implementation

Now and ONLY now proceed with writing code:

1. Implement the solution following best practices
2. Annotate task with key decisions or blockers:

task <ID> annotate "Decision: Using FastAPI over Flask for async support"
task <ID> annotate "Blocker: Waiting for API credentials"

3. If blocked, stop the task temporarily:

task <ID> stop
task <ID> modify +blocked

4. If scope changes mid-implementation:

task <ID> modify +additional_tag description:"Updated description"

Phase 4: Task Completion

After code is delivered and verified, complete the task:

# Complete the task
task <ID> done

# Timewarrior automatically stops tracking
# View time summary for this task
timew summary :ids

# Check if dependent tasks are now unblocked
task next

Completion Checklist:

• ✅ Code is written and tested
• ✅ Documentation is updated (if applicable)
• ✅ Task annotations reflect final state
• ✅ Any blockers are resolved or escalated
• ✅ Time tracking is accurate

Phase 5: Verification & Reporting

After completing tasks, provide summary:

# Show completed task details
task <ID> info

# Show time spent
timew summary :ids

# Show remaining work
task next

Task Decomposition Examples

Example 1: Simple Single-File Script

User Request: "Create a Bash script that backs up my home directory"

Task Decomposition:

task add "Create home directory backup script" project:DevOps priority:M due:today +scripting +automation +backup

Lifecycle:

task 42 start
[Write backup.sh script]
task 42 done
timew summary :ids

Example 2: Complex Multi-Component Feature

User Request: "Build a REST API with authentication, user management, and PostgreSQL"

Task Decomposition:

# Parent task
task add "Build FastAPI REST API with auth" project:WebDev priority:H due:5days +api +backend

# Dependent subtasks
task add "Design PostgreSQL schema" project:WebDev depends:43 priority:H due:1day +database +design
task add "Implement JWT authentication" project:WebDev depends:44 priority:H due:2days +auth +security
task add "Create user management endpoints" project:WebDev depends:45 priority:M due:3days +crud +endpoints
task add "Write API documentation" project:WebDev depends:46 priority:L due:5days +documentation +openapi
task add "Deploy to staging environment" project:WebDev depends:47 priority:M due:5days +deployment +staging

Lifecycle:

task 44 start  # Start with database schema
[Design and implement schema]
task 44 done

task 45 start  # Next: authentication
[Implement JWT auth]
task 45 done

# Continue through dependency chain...

Example 3: Debugging Investigation

User Request: "My Node.js app crashes with ECONNREFUSED"

Task Decomposition:

task add "Debug ECONNREFUSED error in Node.js app" project:Debugging priority:H due:today +debugging +nodejs +urgent +investigation

Lifecycle with Annotations:

task 50 start
task 50 annotate "Error occurs during PostgreSQL connection"
task 50 annotate "Root cause: PostgreSQL service not running"
task 50 annotate "Solution: systemctl start postgresql"
[Provide debugging steps and code fixes]
task 50 done

Example 4: Recurring Maintenance Task

User Request: "Create a script I need to run weekly to clean Docker images"

Task Decomposition:

task add "Weekly Docker cleanup script" project:Maintenance recur:weekly due:friday priority:M +automation +docker +cleanup

Lifecycle:

task 55 start
[Write docker-cleanup.sh script]
task 55 done

# Future instances auto-generate every Friday
task next  # Will show next week's instance

Task Priority Guidelines

Use this urgency matrix to assign priority:

priority:H (High) - Use when:

• Blocking other work
• Production outage or critical bug
• Security vulnerability
• Hard deadline within 24-48 hours
• Explicitly marked as urgent by user

priority:M (Medium) - Use when:

• Normal feature development
• Non-blocking improvements
• Deadline within 3-7 days
• Standard maintenance work
• Default for most tasks

priority:L (Low) - Use when:

• Nice-to-have enhancements
• Documentation updates
• Refactoring for cleanliness (not performance)
• No specific deadline
• Can be deferred without impact

Tag Taxonomy

Common Project Tags:

• +feature - New functionality
• +bugfix - Fixing existing issues
• +refactor - Code restructuring
• +testing - Test creation/execution
• +documentation - Docs and comments
• +deployment - Release and infrastructure
• +security - Security-related work
• +performance - Optimization work
• +debugging - Investigation and diagnosis
• +maintenance - Routine upkeep
• +automation - Scripting and tooling
• +infrastructure - DevOps and systems

Technology Tags:

• +python, +javascript, +bash, +typescript
• +docker, +kubernetes, +cicd
• +postgresql, +redis, +mongodb
• +fastapi, +react, +nextjs

Status Tags:

• +blocked - Cannot proceed (annotate reason)
• +urgent - Needs immediate attention
• +waiting - Awaiting external input
• +review - Ready for review

Handling Special Scenarios

Scenario 1: Mid-Task Scope Change

If requirements change while working:

# Modify existing task
task <ID> modify +new_tag description:"Updated description"

# Or create dependent subtask for additional work
task add "Additional scope: Email notifications" depends:<ID> project:SameProject +feature

Scenario 2: Blocked Work

If encountering blockers (missing credentials, API limits, permissions):

# Stop the task
task <ID> stop

# Annotate the blocker
task <ID> annotate "Blocked: Need AWS credentials from ops team"

# Mark as blocked
task <ID> modify +blocked

# Explain to user what's needed to unblock

Scenario 3: Multi-Session Work

For work spanning multiple conversations:

Session 1:

task add "Build e-commerce platform - product catalog" project:Ecommerce priority:H +feature
task 60 start
[Implement product catalog]
task 60 done

Session 2 (later):

# Check existing project tasks
task project:Ecommerce status:pending

# Create related task
task add "Build e-commerce platform - shopping cart" project:Ecommerce depends:60 priority:H +feature
task 61 start
[Implement shopping cart]
task 61 done

Scenario 4: Working with User's Existing Tasks

If user references an existing Taskwarrior task:

User: "Help me complete task 42: 'Optimize database queries'"

Response:

# Start user's existing task
task 42 start

[Provide optimization recommendations and code]

# Complete user's task
task 42 done

# Show results
task 42 info
timew summary :ids

Integration with Timewarrior

Taskwarrior automatically integrates with Timewarrior when configured. Here's what happens:

When you start a task:

task <ID> start
# Timewarrior begins tracking with tags from the task

Check current tracking:

timew  # Shows what's currently being tracked
task active  # Shows active Taskwarrior tasks

Stop tracking (when you stop or complete a task):

task <ID> stop  # Pauses tracking
task <ID> done  # Stops tracking and completes task

View time reports:

timew summary :ids              # Total time per task
timew report :ids :week         # This week's breakdown
timew tags                      # Most-used tags
timew day                       # Today's time us

---

*Content truncated.*