Taskwarrior

Taskwarrior Issue Management

Use the task CLI to manage issues with dependency tracking.

When to Use

• The user mentions a task ID or wants to manage work items
• The user asks to create, view, update, close, or search tasks
• The user wants to see what work is ready or blocked
• The user wants to manage dependencies between tasks
• The user asks about project status

Important Notes

Sandbox

The task CLI needs read/write access to ~/.task/ which is typically outside the sandbox. Commands will fail with "unable to open database file" errors. Use dangerouslyDisableSandbox: true for all task commands.

Output Formatting

Use rc.verbose=label on list/report commands to keep column headers but strip footer noise (task count, config overrides, sync messages). Prefer this over rc.verbose=nothing which strips headers too and makes output harder to parse.

For programmatic use or when you need structured data (e.g., to build a markdown table), use task export which outputs JSON. You can filter it the same way: task project:cpb export, task +BLOCKED export, etc.

Instructions

Phase 1: Identify the Request

IMPORTANT: Always use UUID (short prefix is fine) instead of numeric IDs when referencing tasks. Numeric IDs are unstable and shift when tasks are completed or deleted — never use numeric IDs in commands, even if they appear in the output. IDs are shown in reports for the user's convenience only. After creating a task, use rc.verbose=new-uuid to get the UUID directly (see Phase 2A).

Phase 2A: Creating Tasks

Always use rc.verbose=new-uuid when creating tasks — this makes task add output the UUID directly instead of the unstable numeric ID.

Task titles: Write clean, concise descriptions — don't just copy-paste alert names or ticket titles verbatim. Distill the key info: service, symptom, environment. For example, instead of Elastic - [prod] [swedencentral] API Error - earn-svc - 5xx PrdeuswEARNQueryOrg, use Investigate earn-svc 5xx errors in prod swedencentral (PrdeuswEARNQueryOrg).

Tags and projects: Do NOT invent tags or projects. Only use tags and projects that already exist in the task database. Before creating a task, check existing tasks (task rc.verbose=label projects and task rc.verbose=label tags) to see what's in use. If no matching tag/project exists, create the task without tags/projects and let the user decide. The only exception is project:on-call and priority:H for on-call investigation tasks — these are always correct.

# Basic task with project
task rc.verbose=new-uuid add "Task description" project:cpb

# With priority (H=high, M=medium, L=low)
task rc.verbose=new-uuid add "Fix bug" project:cpb priority:H

# With due date
task rc.verbose=new-uuid add "Deploy" project:cpb due:friday

# With tags
task rc.verbose=new-uuid add "Review" project:cpb +urgent +review

# With dependencies (use UUID of the dependency)
task rc.verbose=new-uuid add "Deploy to prod" project:cpb depends:a1b2c3d4

# Sub-projects using dots
task rc.verbose=new-uuid add "Fix API" project:cpb.earn

The output will be like Created task a1b2c3d4-... — use that UUID for all subsequent operations.

Phase 2B: Annotations (Comments)

# Add annotation (use UUID)
task a1b2c3d4 annotate "Spoke with Ryan, needs API change first"
task a1b2c3d4 annotate "See PR #1234 for context"

# Remove annotation
task a1b2c3d4 denotate "Spoke with Ryan"

Phase 2C: Dependencies

# Add dependency using UUIDs (task abc depends on tasks def and ghi)
task a1b2c3d4 modify depends:d5e6f7a8,b9c0d1e2

# Remove dependency
task a1b2c3d4 modify depends:-d5e6f7a8

# View blocked/blocking
task blocked
task blocking

Phase 2D: Filtering

# By project
task project:cpb list

# By priority
task priority:H list

# By tag
task +urgent list

# By status
task +BLOCKED list
task +OVERDUE list
task +ACTIVE list

# Text search
task /deploy/ list

# Combined filters
task project:cpb priority:H due.before:eow list

Phase 2E: Modifying Tasks

IMPORTANT: Always use tag: attribute syntax when adding tags — the +tag syntax is unreliable with modify and can be misinterpreted as a description. Use -tag to remove tags.

task a1b2c3d4 modify priority:H
task a1b2c3d4 modify project:cpb.earn
task a1b2c3d4 modify due:eow
task a1b2c3d4 modify tag:urgent          # add/set tag
task a1b2c3d4 modify tag:on-call,prod    # set multiple tags
task a1b2c3d4 modify -urgent             # remove tag
task a1b2c3d4 modify depends:d5e6f7a8    # add dependency

Phase 2F: Task Notes

Detailed notes for tasks live in /Users/meain/.local/share/tasknotes/. Each note is a markdown file named <uuid-prefix> - <task name>.md.

All task-related resources go here — not just notes, but also drafts, templates, support ticket messages, or any other artifacts tied to a task. Name them with the task UUID prefix for discoverability (e.g., <uuid> - Azure support ticket draft.md). Never save task-related files to /tmp or other locations.

When completing a task, always write detailed notes summarizing what was done, findings, and outcomes. If you learned something new during the task (new patterns, gotchas, field types, service behaviors, etc.), also create a separate learning note named <uuid-prefix> learning.md with bullet points of key learnings.

After writing notes, annotate the task with the filenames:

# Write the note file
# /Users/meain/.local/share/tasknotes/<uuid> - <task name>.md

# Annotate the task to reference the note
task a1b2c3d4 annotate "notes: <uuid> - <task name>.md"

# If there are learnings too
task a1b2c3d4 annotate "notes: <uuid> - <task name> - learning.md"

Notes should include:

• Summary of what was done
• Root cause / findings (for investigations)
• Evidence and key data points
• Links to PRs, runbooks, or other artifacts
• Next steps if applicable

Learning notes should be concise bullet points covering:

• New patterns or conventions discovered
• Gotchas and pitfalls encountered
• Service behaviors or field types that weren't obvious
• Useful queries or commands found