HoloTech/tasklist-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add docs

holo
2025-10-06 22:50:14 +10:00
commit d6a77dbb0e
1 changed files with 233 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

233
Home.md Normal file

@@ -0,0 +1,233 @@
# Task Management Commands
Our tasklist system helps you track and share your current task (`!now`),
plan your future tasks (`!plan`),
and review your completed task history along with how long each task took (`!history`).
**Note:** All commands use the `!` prefix (e.g., `!now`).
---
## ⚙️ Track and share what you are working on (Single Task Usage)
These commands are for managing the single task you are actively working on.
The flow is simple. Use `!now task` to show you are working on `task`,
and then write `!done` to mark it complete and see how long you worked on it.
If you want to mark your task complete *and* start another task, you can do
`!next anther task` instead.
If you discover you have made a typo, you can edit with `!edit another task`,
and at any time you can get rid of it entirely with `!clear`.
| Command | Description | Example |
| --------------- | --------------- | --------------- |
| `!now [new task]` | Set or check your current task | `!now Write documentation` |
| `!notnow` | Pause your task (resume it with `!next`) | `!notnow` |
| `!next [another task]` | Complete your current task and start `another task` | `!next Take a break` |
| `!edit <new task>` | Edit the text of your current task to `new task` | `!edit Make coffee` |
| `!done` | Complete your current task without starting a new one. | `!done` |
| `!clear` | Unset your current task. | `!clear` |
## 📝 Making and managing a plan
Sometimes, setting a single task isn't enough!
Maybe you want to remind yourself about something you need to do later (`!plan task`),
or you want to schedule your next few tasks for a seamless flow (`!now task1; task2; task3` and then `!next`).
Or sometimes half way through one task, you need to start another one,
but you don't want to lose the first task or the time tracked on it (`!sidequest`).
Now presenting to you, your `!plan`!
This feature is under active development, so there may be some mild instability or deviations
from what is written here until I can get the documentation updated, sorry about that!
If there are any features you would like to see added or changed,
or anything you find confusing, please let me know so everyone can benefit from improvements!
Candid feedback is *always* welcome.
In the below table, `taskspec` stands for a specification of one or more tasks in any of the following forms:
- A single task, e.g. `Writing documentation`
- A single task number, e.g. `6`
- A *range* of task numbers, e.g. `6-10`
- Any combination of the above separated with semicolons, e.g. `6; Writing Documents; 8-10; Take a break`
Note: Commas `,` *can* also be used to separate tasks, but semicolons are preferred.
In particular, `this, that; the other` represents *two* tasks, `this, that` and `the other`.
However, `this, that` alone represents the tasks `this` and `that`.
We generally recommend avoiding using commas in your tasks, but if you need to
you can take advantage of this behaviour by using trailing semicolons, for example,
`!now this, that;` will set your current task to just `this, that`.
| Command | Description | Example |
| --------------- | --------------- | --------------- |
| `!now <taskspec>` | Set your current task(s). If multiple are given, all tasks are added to the *start* of your plan. | `!now Read; Write` |
| `!next` | Complete your current task and start the first (incomplete) task on your plan. | `!next` |
| `!next <taskspec>` | Complete your current task, and start the first task in `taskpec`. If multiple tasks are given, add all tasks to the *start* of your plan. | `!next Do exercises; Check exercises` |
| `!sidequest <other task>` | Pause your current task (put it on the start of the plan) and start `other task` | `!sidequest Choose music` |
| `!done <taskpec>` | Mark all tasks in `taskspec` as complete. You *can* create new tasks here and mark them as done. | `!done 10-20; Wash the plates` |
| `!plan` | Show the incomplete tasks remaining on your plan. | `!plan` |
| `!plan <taskspec>` | Add all provided tasks to the *end* of your plan. | `!plan Do 10 pushups; Drink water` |
| `!unplan` | Remove all your tasks from your plan (does not delete them) | `!unplan` |
| `!unplan <taskspec>` | Remove the specified tasks from your plan | `!unplan 1-5, 8, 9` |
| `!clear all` | Delete ***all*** the tasks on your tasklist. | `!clear all` |
| `!clear done` | Delete all the completed tasks on your tasklist (this will change your task numbers!) | `!clear done` |
| `!clear <taskspec>` | Delete the tasks in `taskspec` | `!clear 1, 3, 10-20` |
## 📜 Statistics and History
It's satisfying to tick tasks off the tasklist!
It's even more satisfying to see how much we have done!
And for those of us who like data or don't use an external time tracker,
it's useful to see how long each task took to revise our future estimates!
| Command | Description | Example |
| --------------- | --------------- | --------------- |
| `!history` | (Only on Discord) Show a paged list of tasks completed on each day. | `!history` |
## Command Reference
### `!now [taskspec]`
The 'main' task of the task system, this sets or checks your current task(s).
- **Aliases:** `!task`, `!check`
- With no arguments, this shows you your current task and how long you've been working on it.
- If `taskspec` describes a single task, sets this as your current task without modifying your plan.
- If `taskspec` describes multiple tasks, sets the first one as your current task, and adds all the tasks to the *start* of your plan. If the tasks were already in your plan, they get pulled to the front.
#### Examples
- `!now Writing my thesis proposal`
- Sets your current task.
- `!now`
- Replies: `You have been working on 'Writing my thesis proposal' for 15 minutes`
- `!now Prepare lecture notes; Grade assignments`
- Sets "Prepare lecture notes" as your current task and adds "Prepare lecture notes" and "Grade assignments" to the start of your plan.
---
### `!notnow`
Pauses your current task and moves it to the start of your plan. This is useful if you get interrupted and want to resume later.
Resume the task by writing `!next` which will resume that task.
- **Aliases:** `!pause`
#### Example
- `!notnow`
- Replies: `Unset your task '#12: Writing my thesis proposal' and pushed it onto your plan! Use !next when you want to resume it.`
---
### `!next [taskspec]`
Completes your current task and starts your next one.
- With no arguments, this will start the *first incomplete task* on your `!plan`.
- If `taskspec` describes a single task, sets this as your current task without modifying your plan.
- If `taskspec` describes multiple tasks, sets the first one as your current tasks, and adds all the tasks to the start of your plan.
#### Examples
- `!next`
- Replies: `Good work finishing 'Writing my thesis proposal', you worked on it for 1 hour 2 minutes. Started your next task 'Grade assignments', good luck!`
- `!next Take a break`
- Completes your current task and starts "Take a break".
- `!next Make coffee; Drink Coffee`
- Completes your current task, starts `Make Coffee`, and adds `Make Coffee` and `Drink Coffee` to the start of your plan.
---
### `!done [taskspec]`
Marks one or more tasks as complete without starting a new one.
- With no arguments, completes your current task and show you how long you worked on it.
- If `taskspec` is given, this will complete all the (incomplete) tasks in `taskspec`.
- Tasks *may* be created and immediately completed, for the sweet satisfaction of ticking off something you have done.
#### Examples
- `!done`
- Marks your current task as finished.
- `!done 15`
- Completes the task number 15.
- `!done 15-20, Responded to emails`
- Completes the tasks `15, 16, 17, 18, 19, 20`, and creates and immediately completes the task "Responded to emails".
---
### `!edit <new content>`
Edits the description of your current task.
NOTE: Soon to be `!edit [n] <new content>` for editing a task that is not your current one.
#### Example
- `!edit Studying triangulated categories`
- Replies: `Updated your current task!`
---
### ### `!sidequest <taskspec>`
Put your current task on the head of the plan, and start a new task.
This has the effect of pausing your current task to work on the provided new task,
and is particularly useful for 'temporary' tasks that interrupt the main task.
When you finish the sidequest task with `!next`, you'll resume your main task.
- **Aliases:** `!switch`
- If `taskspec` represents multiple tasks, they will all be put on the plan as usual, and your previous current task will be pushed down into the plan.
#### Example
- You are working on "Writing my thesis proposal".
- `!sidequest Make a cup of tea`
- Replies: `Started your sidequest 'Make a cup of tea', good luck! When you are done use '!next' to resume your main quest '#12: Writing my thesis proposal'.`
---
### `!plan [taskspec]`
View your remaining planned tasks, or add tasks to the *end* of your plan.
- **Aliases:** `!later`
- Without arguments, shows you a list of all your incomplete planned tasks.
- If `taskspec` is given, adds all the specified tasks to the *end* of your plan, in the same order they are given.
#### Examples
- `!plan`
- Replies: `You have 2 tasks on the plan, good luck: #14: Grade assignments ┆ #15: Buy groceries`
- `!plan Go to the gym; 15`
- Adds "Go to the gym" to the end of your plan, and moved `15` to the end after that. The result will be:
- `#14: Grade assignments ┆ #16: Go to the gym ┆ #15: Buy groceries`
---
### `!clear [target]`
Deletes tasks from your list. Once deleted, tasks cannot be recovered!
- **Aliases:** `!remove`, `!delete`, `!del`
The `target` can be one of the following:
- (nothing) or `current`: Deletes your current task.
- `plan`: Removes all tasks from your plan (does not delete them).
- `done`: Deletes all completed tasks from your tasklist (this will change your task numbers!).
- `all`: Deletes **all** of your tasks, including current, planned, and completed.
- `taskspec`: Deletes the specified tasks. You can't create new tasks here.
---
### `!history`
Displays a detailed history of your completed tasks, grouped by day.
- **Aliases:** `!hist`, `!taskhist`
- **Platform:** Discord only.
This command generates paginated tables showing which tasks you completed on which days, including start/end times and total duration.