ranger skill: correct tag commands and expand comment guidance
Assisted-by: Claude Opus 5 via Claude Code
diff --git a/skills/ranger/SKILL.md b/skills/ranger/SKILL.md
index c7f564b..7993176 100644
--- a/skills/ranger/SKILL.md
+++ b/skills/ranger/SKILL.md
@@ -36,11 +36,13 @@ ranger comment add <task-key> "Comment text" # Add a comment to a task
ranger comment list <task-key> # List comments on a task
```
+Tags are created automatically — there's no `tag create` command. The first `ranger tag add <task-key> <name>` makes the tag exist.
+
```bash
-# Tags (created implicitly — no "tag create" command; adding a new name creates the tag)
-ranger tag list # List all tags
-ranger tag add <task-key> <tag-name> # Add a tag to a task (creates tag if new)
+ranger tag add <task-key> <tag-name> # Add a tag (creates it if new)
ranger tag remove <task-key> <tag-name> # Remove a tag from a task (alias: rm)
+ranger tag list # List tags in the current backlog
+ranger tag prune # Remove tags no longer attached to any task
```
Task states for `--state`: `icebox`, `ready`, `in_progress`, `done`.
@@ -69,7 +71,7 @@ Top of the queue = most important. Bias toward quick wins — small easy tasks s
- 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.
+- 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, or research and feasibility findings worked out before implementation starts. Commits explain the change that landed; comments explain the trail around it — including the trail leading *up to* it. Comment bodies can be multi-line (pass a heredoc); structure and newlines are preserved.
- 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.