Quick Reference omitted archive/unarchive and comment commands, and
listed a `blocker` noun that doesn't exist — forcing a fallback to
`ranger --help`. Conventions said nothing about state transitions,
when to leave a comment, or what "done" actually means — forcing the
same workflow rules to be re-derived per session. Now states each
rule in one place: done = committed, in_progress reflects active
work, archive (with a why-comment) for superseded or won't-do tasks,
delete only for accidents.

Assisted-by: Claude Opus 4.7 via Claude Code

diff --git a/skills/ranger/SKILL.md b/skills/ranger/SKILL.md
index be29ae9..c7f564b 100644
--- a/skills/ranger/SKILL.md
+++ b/skills/ranger/SKILL.md
@@ -11,7 +11,7 @@ All work must correspond to a task in the backlog. If the user asks for somethin
 
 ## Quick Reference
 
-Commands use `ranger <noun> <verb>` structure. Top-level nouns: `backlog` (alias `b`), `task` (alias `t`), `comment` (alias `c`), `tag`, `blocker`.
+Commands use `ranger <noun> <verb>` structure. Top-level nouns: `backlog` (alias `b`), `task` (alias `t`), `comment` (alias `c`), `tag` (alias `g`).
 
 ```bash
 # Backlogs
@@ -25,7 +25,15 @@ ranger task show <key>                        # Show task details
 ranger task edit <key> --state <state>        # Change task state
 ranger task move <key> -B <other>             # Reorder: place before another task
 ranger task move <key> -A <other>             # Reorder: place after another task
-ranger task delete <key>                      # Delete a task
+ranger task archive <key>                     # Archive a task (hide without deleting)
+ranger task unarchive <key>                   # Restore an archived task
+ranger task delete <key>                      # Delete a task entirely (rare — see Conventions)
+```
+
+```bash
+# Comments
+ranger comment add <task-key> "Comment text"  # Add a comment to a task
+ranger comment list <task-key>                # List comments on a task
 ```
 
 ```bash
@@ -46,13 +54,23 @@ Task keys are short prefixes (e.g. `tl`) of longer IDs — use just enough to be
 - **Icebox**: ideas, not committed to
 - **Ready**: committed, ordered by priority (top = most important)
 - **In Progress**: actively being worked on
-- **Done**: finished
+- **Done**: the change is committed (no commit, not done)
 
 Top of the queue = most important. Bias toward quick wins — small easy tasks should be prioritized higher by default.
 
+### Done vs. archive vs. delete
+
+- **Done means committed.** The transition to done happens *after* `jj commit` (or equivalent) succeeds — never before, never "I'll commit in a sec." If the change isn't in version control, the task isn't done.
+- **Archive** when a task won't be done — ideas decided against, or seed tasks that have been superseded by more concrete tasks broken out of them. Archive preserves history; the task can still be referenced and unarchived later.
+- **Delete** is a last resort, reserved for tasks created in error (typo duplicates, wrong backlog, accidental). Prefer archive so the trail stays intact.
+
 ## Workflow
 
-- Don't mark a task **done** until the changes are committed. Commit first, then transition.
+- Move a task to **in_progress** when starting work on it (`ranger task edit <key> --state in_progress`), and back to **ready** if you stop before it's done. State should reflect what's actually happening — the board is only useful if it's accurate.
+- Done = committed. Always commit first, then transition. If a task can't be tied to one or more commits, it isn't done — re-scope, split, or leave it in_progress until something lands.
+- When creating or editing a task, review its tags. Add tags that apply (e.g. `bug`, area tags) and remove ones that no longer fit so `ranger task list` filters stay useful.
+- Leave a comment on the task when something comes up that future-you (or the next picker-upper) would want to know but that doesn't belong in a commit message: a decision made along the way, a blocker hit, a follow-up deferred, what you tried and ruled out, where you left off when stopping mid-task. Commits explain the change that landed; comments explain the trail around it.
+- When archiving a task, add a comment explaining why (`ranger comment add <key> "..."`) — superseded by which tasks, decided against for what reason. The reason is the point of preserving history.
 - When you encounter a bug in ranger during other work, file it in the ranger backlog (`--backlog ranger`) and tag it `bug`. Include what you observed, the expected behavior, and how to reproduce it in the description. Don't fix it inline — continue with the original task unless the bug blocks it.
 
 ---