From 5f864307b85a6afcfb2720ddda8bdeca67960434 Mon Sep 17 00:00:00 2001
From: Gregory Gauthier <gregory.gauthier@perspectum.com>
Date: Tue, 31 Mar 2026 15:08:52 +0100
Subject: [PATCH] docs(todo): update workon command specification

Refine the steps for the workon command, including moving todo items, generating plans, and optional logging/IDE opening.
Update usage to include -m for custom messages, -f for fixes, and -c for completion.
Add benefits, arguments section, and details for handling features vs fixes.
---
 todo/queued/workon.md | 37 +++++++++++++++++++++++++++----------
 1 file changed, 27 insertions(+), 10 deletions(-)

diff --git a/todo/queued/workon.md b/todo/queued/workon.md
index c954d68..824d1b3 100644
--- a/todo/queued/workon.md
+++ b/todo/queued/workon.md
@@ -2,17 +2,12 @@
 
 **Description**: Automates the initiation of new feature and fix development. 
 
-1. selects a todo item out of the todo queue; 
+1. selects a todo item out of the todo queue and moves it to the "doing" folder; 
 2. creates a branch based on the item; 
-3. generates a plan for implementation;
-4. commits the plan to the branch;
-4. logs the beginning of the work using `cnadd` (if available).
-5. opens the branch in the IDE (specified in the config).
-
-**Usage**:
-```
-grokkit workon <todo_item_title> [-c <custom_commit_message>]
-```
+3. generates a plan for implementation (amending it to the todo item under the heading "Work Plan");
+4. commits the plan to the branch.
+5. [optional] logs the beginning of the work using `cnadd` (if available).
+6. [optional] opens the branch in the IDE (specified in the config).
 
 **Assumptions**:
 
@@ -23,6 +18,28 @@ Also, if no IDE is specified in the config, the feature will default to not open
 **Benefits**:
 
 1. Boosts productivity by automating routine tasks.
+2. Makes it easier to track the progress of the work.
+3. Makes feature development more uniform and consistent.
+
+**Usage**:
+```
+grokkit workon <todo_item_title> [-m '<custom_commit_message>'] [-f] 
+```
+
+**Arguments**:
+- `<todo_item_title>`: The item to be worked on. 
+  - If this is a feature, then there should be a Markdown entry in the queued folder with the same name, which will be moved to the doing folder. That should also be the name of the branch. 
+  - If this is a fix, then use the argument as a branch name and as the name of a markdown file to be created, where the Work Plan will be stored in the "doing" folder. 
+  - In both instances, If spaces are present, replace them with dashes.
+
+- `-m '<custom_commit_message>'`: custom commit message to use for the branch. Default is "Start working on <todo_item_title>".
+
+- `-f`: This signifies a "fix" rather than a todo item (the default is always a todo item)
+
+- `-c`: "completes" the work item. This means: 
+  - If it is a todo, it will be moved to the "completed" folder, and the index readme will be updated. 
+  - If it is a fix, the work plan will be moved to the "completed folder". No index update is necessary. 
+  - In either case, the update will be committed to the branch.
 
 **High-level implementation**: