Files
worklane/assets/PLAN.md
T
Ansho ReiandClaude Opus 5 528566d103 (61879a4) Surface campaigns on the board, and bump to 0.20.0
A card label and a frame, not a campaign tab. A tab had to say what its
columns are, and a campaign groups across the flow rather than within one
status, so the answer is the four columns filtered: a filter on the board
it already has, not a fifth tab.

So a card names its campaign on the label row, before the tags, marked ~
and bold, and the row drops the tags whole before it drops the campaign.
`c` opens a picker; taking a campaign filters every column to its members
and draws a frame above them carrying the id, the codename, the name, the
opening line of the description and the standing. The standing comes from
the columns, since while a campaign is selected the columns are its
members. `q` takes off one layer at a time: the overlay, the filter, the
board.

The label needs something to say, which the stored uuid is not, so
campaigns gained `Codename`: one word, `v1` or `beaver`, written by
`campaign add --codename` and validated at parse time. `campaign ls`
prints it and `resolve_in` gained an exact-codename tier above the uuid
prefix, or it would be a field you can read and cannot type. Only
campaigns carry the field, so the tier is empty for a ticket and ticket
resolution is unchanged.

The campaigns index is read once per project in `columns_of`, on the pass
that already builds the cards, and `digest` now watches the campaigns
directory: without it a campaign filed elsewhere never reached the picker.
`frame_rows` grew a row, so the two bools deciding the geometry became one
`Chrome` and the row indices are named.

Left out and filed as d637288: nothing can give a codename to a campaign
that is already on the board.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-23 12:09:07 +02:00

201 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 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.
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.