`campaign set --codename` replaced whatever was there. Once a campaign has a codename it is referred to by it -- on every card in the campaign, at the command line, and in somebody's shell history -- so changing it silently is the mistake `install-skill --force` exists to prevent. So it is refused, and the refusal names both words and the flag rather than leaving it to be found. Checked before any edit is applied, like `SetArgs::contested`, so a call also carrying `--title` writes neither field rather than half of what was asked for. Setting the codename a campaign already carries stays a no-op rather than becoming a refusal: `--force` is about overwriting a *different* word, and there is nothing to overwrite. That is the division `install::Outcome` already draws between `Unchanged` and `Refused`. `--force` guards the codename alone. A campaign always has a title, so guarding that would mean the flag was always required, which is a tax rather than a guard. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
205 lines
11 KiB
Markdown
205 lines
11 KiB
Markdown
---
|
|
name: worklane-plan
|
|
description: Groom a worklane board as a whole rather than one ticket at a time: review whether the priorities are right relative to each other, plan work by setting due dates, check the tags for consistency, and find the tickets that belong together in a campaign. Use for questions about the backlog as a body of work, what to do next week, what is mis-prioritised or mis-tagged, and what could become one goal. Not for filing or working a single ticket.
|
|
---
|
|
|
|
# Planning a worklane board
|
|
|
|
For "are the backlog priorities right", "plan in tickets for next week", "check the
|
|
tagging", "which of these could be one campaign". The subject is the board, not a
|
|
ticket. Filing one, working one and reviewing one are other jobs.
|
|
|
|
The CLI itself is the `worklane` skill: the statuses, how a ticket is addressed and
|
|
which command owns which field. Read it too. This document is the judgement.
|
|
|
|
## The one rule
|
|
|
|
**Propose the whole set of edits, wait, then apply exactly what was approved.**
|
|
|
|
Every job here writes to many tickets at once, and nothing on the board records what a
|
|
field held before you wrote to it. `--clear` puts a field back to unset, which is **not
|
|
back to what it held**, so a date written over another date is gone. A wrong edit to one
|
|
ticket is a mistake; a wrong sweep is thirty of them with no undo. So a proposal is a
|
|
list, one line per intended edit, each naming the ticket and the command that would make
|
|
it:
|
|
|
|
```
|
|
(1b78a24) priority 3 -> 1 worklane set 1b78a24 --priority 1
|
|
(4179958) due -> 2026-08-29 worklane set 4179958 --due 2026-08-29
|
|
```
|
|
|
|
Then apply what was approved and nothing else. Not "and a few obvious ones while I was
|
|
there": an approval is for the list that was shown.
|
|
|
|
## Who writes what
|
|
|
|
Every field has exactly one command that writes it, and a sweep that reaches for any
|
|
other way is editing the file by hand:
|
|
|
|
| Field | Writer |
|
|
|-------|--------|
|
|
| Priority, Due, Tags | `worklane set <ticket> --priority` / `--due` / `--tags`, and `--clear <field>` to empty one |
|
|
| Relations | `worklane relate <ticket> --blocked-by` / `--regression-of` / `--relates-to` |
|
|
| Campaign membership | `worklane assign <campaign> <ticket>` |
|
|
| Owner | `worklane chown <user> <ticket>`, and `worklane chown --clear <ticket>` to empty it |
|
|
| Status | `worklane mv <ticket> --status <target>` |
|
|
|
|
**Never edit a ticket file directly.** The filename, the `Status` field and the directory
|
|
have to agree, and the commands are what keep them agreeing. A hand-written Relations
|
|
line is worse still: it is the one section read back by machine, and a target that does
|
|
not resolve to a uuid is an error on every later read of that ticket.
|
|
|
|
The last two rows are in the table to be recognised, not used. See the closing section.
|
|
|
|
## Read the board first
|
|
|
|
```
|
|
worklane ls # every status, counts then tickets
|
|
worklane ls backlog # one status
|
|
worklane ls --priority 1 # the top of the pile
|
|
worklane ls --tag bug # one tag's worth of the board
|
|
worklane tags # the whole vocabulary, with counts
|
|
worklane show 1b78a24 # one ticket, with its relations and comments
|
|
worklane campaign ls # the goals that already exist
|
|
```
|
|
|
|
`ls` prints the mark, the id, the title, the owner and the due date, and **not** the tags.
|
|
So the vocabulary comes from `worklane tags`, which is the one command that answers what
|
|
tags exist rather than what carries a tag you already know. One line per tag, alphabetical,
|
|
as the tag, a tab and its count. It is case sensitive like the filter, so `bug` and `Bug`
|
|
list separately and, being alphabetical, land next to each other, which is where a
|
|
near-duplicate is spotted. Start a tag sweep there rather than with a `show` per ticket.
|
|
|
|
Read `done` too when the question is about what to do next. What was finished last is the
|
|
best evidence of what this board actually moves at, and a plan that ignores it is a wish.
|
|
|
|
## Priorities
|
|
|
|
Priority runs **1 most urgent to 5 least**, and may be unset. `worklane set <ticket>
|
|
--priority <n>` is the only writer.
|
|
|
|
Priority is relative. A ticket is never urgent by itself, it is urgent above something
|
|
else, so every proposed change has to name what it now sits above and below. "This looks
|
|
important" is not a reason; "this blocks three tickets that are all dated before it" is.
|
|
|
|
What to look for:
|
|
|
|
- **A blocker priced below what it blocks.** Read the Relations. A ticket that others are
|
|
`blocked by` cannot be less urgent than the most urgent of them, or the board is asking
|
|
for work in an order it will not allow.
|
|
- **A flat board.** If almost everything is 3, the field is carrying no information and
|
|
the answer is not to renumber everything at once. Propose the few that are genuinely 1
|
|
and the few that are genuinely 5, and leave the middle alone.
|
|
- **Too many 1s.** If everything is urgent, nothing is. Say how many there are before
|
|
proposing another.
|
|
- **A low priority already in `committed`.** Either the priority is wrong or starting it
|
|
was, and which one it is decides whether the fix is a `set` or a conversation.
|
|
- **A priority nobody has touched since the ticket was filed.** It is the filer's first
|
|
guess, not a decision. That is the pile worth reading.
|
|
|
|
## Due dates
|
|
|
|
`worklane set <ticket> --due 2026-08-29`, format `YYYY-MM-DD`.
|
|
|
|
A value that is not a real calendar date in that exact form is refused before anything
|
|
is written, so a typo costs nothing. `2026-8-9` is refused too: the padding is part of
|
|
the format. A date can be taken off again with `worklane set <ticket> --clear due`. What
|
|
that cannot do is recover the date that was there before it, so a plan applied over
|
|
existing dates still has no undo.
|
|
|
|
Ask the system what today is rather than assuming it. A plan built on a guessed date is
|
|
wrong by however much the guess was wrong.
|
|
|
|
The rules a dating plan has to keep:
|
|
|
|
- **Nothing is dated before the ticket it is blocked by.** Read the Relations first and
|
|
date blockers ahead of their dependents. A dependent dated before its blocker is a date
|
|
`mv` will refuse to honour anyway.
|
|
- **A blocker left undated makes its dependent's date a fiction.** Either date both or
|
|
neither.
|
|
- **Date what fits, not what exists.** Ask how much capacity the week holds, or take the
|
|
answer from what `done` shows the board finishing in a comparable stretch. Dating the
|
|
whole backlog produces a board where every ticket is late, which is the same as no
|
|
dates at all.
|
|
- **Do not date `done`.** It is finished; a date on it is noise in every listing.
|
|
- Leave the rest unset. An unset due date is honest about what has not been planned, and
|
|
a date that turned out to be wrong is better cleared than left to read as a plan.
|
|
|
|
## Tags
|
|
|
|
`worklane set <ticket> --tags bug,cli` is the writer, and it **replaces the whole
|
|
field**. Restate every tag the ticket should keep, or the ones you left out are gone.
|
|
This is the single most destructive thing in this document. `--clear tags` empties the
|
|
field on purpose, which is a different thing from emptying it by forgetting a tag.
|
|
|
|
`worklane tags` before and after a tag sweep is the cheapest check that it did what was
|
|
proposed: a count that dropped where nothing was meant to change is a tag lost to the
|
|
replace-the-whole-field rule above.
|
|
|
|
Derive the vocabulary from the board rather than inventing one. Read `worklane tags`, count
|
|
what is actually used, and show the count before proposing anything. What to report:
|
|
|
|
- **Two spellings of one idea.** `bug` and `bugfix`, `tui` and `ui`. Pick the one already
|
|
used more and say so.
|
|
- **A tag used exactly once.** Either it is the start of a category and should be applied
|
|
to its siblings, or it is a private note and should go. Do not leave it as it is without
|
|
saying which.
|
|
- **A tag that restates a field.** A `p1` tag beside a Priority field, an `open` tag
|
|
beside a Status, an owner's name as a tag. The field is the writer; the tag is a copy
|
|
that will disagree with it. This board already made that mistake once with priority and
|
|
undid it deliberately.
|
|
- **An untagged ticket** in a board where everything else is tagged. It is invisible to
|
|
every question asked by tag, `worklane ls --tag` included.
|
|
|
|
Tags are for kind, not for state and not for goal. State is the status directory and the
|
|
fields; a goal is a campaign.
|
|
|
|
## Campaigns
|
|
|
|
```
|
|
worklane campaign ls
|
|
worklane campaign show v1
|
|
worklane campaign add --title "..." --codename v1 --description "..."
|
|
worklane campaign set v1 --title "..." # or --codename, on one already filed
|
|
worklane assign v1 1b78a24
|
|
```
|
|
|
|
A campaign is the tickets that have to be finished **together** for one outcome. The test
|
|
is whether you can name the outcome in a single line without listing the members. "The
|
|
tui is usable on a narrow terminal" is a campaign. "The tui tickets" is a tag.
|
|
|
|
- **Do not group by tag.** Ten tickets tagged `bug` share a kind, not a goal, and putting
|
|
them in a container says nothing that the tag did not already say.
|
|
- **Check what exists first.** `campaign ls` before proposing a new one, or you will
|
|
propose a second container for a goal that already has one.
|
|
- **A ticket is in at most one campaign**, and `assign` moves it rather than adding a
|
|
second. So two proposed campaigns that overlap are really one proposal to take members
|
|
out of the other, and it has to say so.
|
|
- **A campaign's state is derived**, open until every member is done. There is nothing to
|
|
close and nothing to move. A campaign whose members are all done is finished already.
|
|
- `assign` takes the **campaign first and the ticket second**, like `chown`.
|
|
- **Propose a codename with the campaign**, one word, `v1` or `beaver`. It is what the
|
|
board draws on every card in it and the shortest thing that addresses it at the command
|
|
line, and a campaign filed without one is drawn by its short id, which says nothing. A
|
|
campaign already on the board that has no codename is worth pointing out for the same
|
|
reason a near-duplicate tag is, and `campaign set` is how it gets one without refiling.
|
|
- **Do not propose renaming a codename a campaign already has.** It is what the campaign is
|
|
called on every card in it and at the command line, so changing it is churn dressed as
|
|
grooming. `campaign set` refuses it without `--force` for that reason.
|
|
|
|
Proposing a campaign means naming the goal, the members, and what is deliberately left
|
|
out of it. The last part is what makes it a goal rather than a pile.
|
|
|
|
## What a planner does not touch
|
|
|
|
- **Descriptions, acceptance criteria and implementation plans.** They are the ticket
|
|
author's account of the work, and grooming is about how the work is ordered, not what
|
|
it is. Something wrong in there is a comment on that ticket.
|
|
- **Status.** `mv` belongs to whoever does the work. A plan that moves tickets between
|
|
columns is reporting progress that did not happen.
|
|
- **Owner.** `chown` records a commitment a person made. Propose it, do not write it,
|
|
unless you were asked to assign the work.
|
|
- **New tickets.** Grooming is about what is on the board. Something genuinely missing is
|
|
worth filing, by the rules in the `worklane` skill, but say it is a new ticket rather
|
|
than folding it into a grooming sweep.
|