diff --git a/SKILL.md b/SKILL.md index 1c56ffbb53a1290423590055fe76b57f6cbb028a..b0e4cbbaa2c64925d9e75ec41d51b1d7d6c1e860 100644 --- a/SKILL.md +++ b/SKILL.md @@ -3,12 +3,47 @@ name: managing-tasks-with-td description: Manages tasks with the td CLI. Use when tracking work items, creating todos, managing task dependencies, or when the user mentions td, tasks, or todos in a project using td. When the project obviously uses something else, or the user doesn't mention td explicitly, do not read. --- +Don't forget the single quotes around `'DESC'` HEREDOCs; they disable shell +interpolation, preventing it from messing up Markdown in the description. + +## General reference + +These are not your most-used commands, nor are they the most critical, but you +still need reference for them. The sections following are more important than +this one and thus contain more instruction. + +```bash +td rm td-a1b2c3 td-d4e5f6 # delete one or many IDs +td rm --recursive td-parent # required for deleting task trees +td rm --force td-blocker # suppress dependent-unblocked warnings +td list # all +td list -s open +td list -p high +td list -e low +td list -l frontend +td label add td-a1b2c3 frontend +td label rm td-a1b2c3 backend +td label list td-a1b2c3 +td label list-all +td show td-a1b2c3 # read a task, its metadata, and logs +td ready # show open tasks with no active blockers +td search "smtp" # substring match in title and description +``` + +## Creating tasks + +Flags: + +- -p priority: low, medium (default), high +- -e effort: low, medium (default), high +- -t type -d desc -l labels (csv) + +Titles and bodies should stand on their own a year from now, not requiring +additional context to understand the nuances but including those nuances +directly at task creation or by adding them later through logs. + ```bash -# New work — title should stand on its own a year from now -# -p priority: low, medium (default), high -# -e effort: low, medium (default), high -# -t type -d desc -l labels (csv) -td create "panic in token_refresh when OAuth provider returns HTTP 429" \ +td create "Panic in token_refresh when OAuth provider returns HTTP 429" \ -p high -e medium -t bug -d "$(cat <<'DESC' Reproduction: 1. Point OAuth at a rate-limiting provider (or stub with httpbin/status/429) @@ -48,21 +83,37 @@ Relevant: tests/db_stress.rs:88, db::open() DESC )" -td create "Child task" --parent td-a1b2c3 # ID becomes .N +td create "Child task" --parent td-a1b2c3 # for splitting tasks into smaller chunks +``` + +## Dependencies + +These are a core part of td; use them liberally, but appropriately. The `next` and `ready` commands both filter tasks with blockers so you have an easier time ordering work. Blocker relationships also make obvious opportunities for parallel work. When there are opportunities for parallelisation, and you have a subagent tool with write capabilities, and the tasks are small, ask the user whether they want you to invoke subagents for them. If the tasks aren't quite scoped well enough yet, ask whether they would like you to interview/question them regarding the gaps that need filling. DO NOT parallelise work without EXPLICIT user confirmation. + +```bash +td dep add td-child td-blocker # child waits for blocker to close +td dep rm td-child td-blocker +td dep tree td-parent # subtask tree +``` -# What's on the board? -td list # all tasks -td list -s open # by status: open, in_progress, closed -td list -p high # high-priority only -td list -e low # low-effort tasks -td list -l frontend # by label +## Updating tasks -# Full context on a task -td show td-a1b2c3 +_As soon as_ it's obvious you're working on a particular task, mark it `in_progress`. If that was wrong, the user will say so. -# Append notes as you go, not just once at the end. -# Focus on why: what the user asked for, what decision was made, and why. -# Keep file paths as context, not the headline. +```bash +td update td-a1b2c3 -s in_progress +td update td-a1b2c3 -p high -e low -t "Revised title" -d "Added context" +td done td-a1b2c3 td-d4e5f6 # one or many +td reopen td-a1b2c3 # only on explicit user request +``` + +## Logging and looking for work + +These, and `show` of course, but that one's self-explanatory, are your most-run `td` commands. + +The `log`s are your scratchpad from which another agent or human might pick up after you. Any time you discover something, like maybe the code doesn't actually line up with the spec or some constraint forces you to implement something differently from initially described or whatever else, this is where you note it down. As you're discussing things with the user, they'll communicate preferences or make decisions or tell you to do things a certain way. Any time the task doesn't already reflect those, this is where you record them. Do not EVER let these signals go unrecorded. In case there's a network outage or a power failure or any other kind of weird issue, the user needs to be able to hand this ticket in whatever form YOU left it to what will effectively be an amensic agent. It'll be competent, but like a completely fresh consultant, need lots and lots of context to get up to speed. The ticket and the logs you attach to it _massively_ help anyone coming after you. While the "what" is definitely important, be sure not to skimp on the much more important "why", such as "User said ..." or "Discovered that [code symbol] actually ...". + +```bash td log td-a1b2c3 "User asked for logs in show/export/import but not in list --json. Kept list untouched to avoid breaking existing scripts that parse its output." td log td-a1b2c3 "User wanted task validation before insert. Added it so 'task not found' is explicit and immediate instead of a less obvious DB failure." td log td-a1b2c3 "Kept ON DELETE CASCADE only on task_logs because the user scoped labels/blockers cascade changes to a separate task." @@ -71,41 +122,17 @@ td log td-a1b2c3 "Used timestamp+id ordering so handoff readers get a stable tim td log td-a1b2c3 "Import replaces logs for the task to keep repeated imports deterministic and consistent with label/blocker import behavior." td log td-a1b2c3 "CI failed only on migration version assertions after adding 0004; updated expected version and re-ran full suite to confirm no behavioral regressions." td log td-a1b2c3 "Ran manual round-trip (init -> create -> log -> show -> export/import -> show) to prove logs survive transfer and stay in chronological order." +``` -# Task status or details changed -td update td-a1b2c3 -s in_progress -td update td-a1b2c3 -p high -e low -t "Revised title" -d "Added context" - -# Finished or needs reopening -td done td-a1b2c3 td-d4e5f6 # one or many -td reopen td-a1b2c3 - -# Delete tasks (always non-interactive) -td rm td-a1b2c3 # delete one or many IDs -td rm td-a1b2c3 td-d4e5f6 -td rm --recursive td-parent # required for deleting task trees -td rm --force td-blocker # suppress dependent-unblocked warnings -td --json rm td-a1b2c3 # machine-readable deleted/unblocked IDs - -# Blocked by something else -td dep add td-child td-blocker # child waits for blocker to close -td dep rm td-child td-blocker -td dep tree td-parent # subtask tree - -# Tag for cross-cutting concerns -td label add td-a1b2c3 urgent -td label rm td-a1b2c3 urgent -td label list td-a1b2c3 -td label list-all - -# What can be worked on right now? -td ready # open with all blockers resolved -td search "smtp" # substring match in title and description +The `next` command traverses the graph using an algorithm that weighs tasks such that the top-scoring task is likely the one you want to start with. The algorithm accounts for unblocking other tasks, priority, and effort signals. It defaults to sorting by tasks which make the impact. Effort mode still accounts for all the signals, buts weighs them such that tasks with lower effort values bubble to the top. Only use effort mode if explicitly requested. Passing the verbose flag will show the equation resulting in the score, if the user is curious why things are sorted as they are. Only use the verbose flag if the user is curious about sorting/scoring. +```bash # What should I work on next? -td next # top 5 by critical path (default) -td next --mode effort # top 5 by effort-weighted scoring -td next --verbose # show scoring breakdown per task -td next -n 3 # limit to top 3 -td next --mode effort -v # combine flags +td next # top 5 by critical path (default) +td next --mode effort +td next --verbose # show scoring breakdown per task +td next -n 3 # limit to top 3 +td next --mode effort -v # combine flags ``` + +Reminder: update the status to "in*progress" \_before* starting and _frequently_ attach high-signal, low-noise logs to the task at hand.