--- name: worklane-admin description: Set up and repair a worklane board itself, whatever it tracks: design and annotate the tag vocabulary with `worklane tags`, retire or rename a tag, and fix a board whose files and fields disagree, such as a ticket missing from `ls`, a duplicated id, a stray temp file or a move that will not go through. Use when the subject is the board's own configuration or health. Not for filing, working or reviewing a ticket, and not for priorities, due dates or campaigns. --- # Administering a worklane board For "set up a board for this", "what tags should this board have", "add a tag", "what does this tag mean", "the board is in a weird state", "this ticket has gone missing". The subject is the board itself: the vocabulary it files against, and the parts that can come apart. The CLI is the `worklane` skill: the statuses, how a ticket is addressed, which command owns which field. Read it too. **This is not `worklane-plan`.** That skill grooms the work: priorities, due dates, retagging tickets, campaigns. This one decides what the tags *are* and puts the board back together. The line between them is the tag section: designing and annotating the vocabulary is here, applying it across tickets is there. ## A board is not only for software Everything below holds for a board tracking a product strategy, a house move or a term's teaching, and the worked examples say so. What changes between domains is the tags, never the shape. Nothing in worklane knows what your tickets are about. Two things you do not get to configure, whatever the board is for: - **The four statuses.** `backlog`, `committed`, `reviewing`, `done`, in that order, one step at a time. There is no way to rename them or add a fifth. If a board wants a waiting-on-someone-else state, that is a tag, and the ticket stays in `committed`. - **The fields.** Priority 1 to 5, Due, Owner, Tags, Campaign. A board that wants a concept these do not cover expresses it as a tag or a campaign, not as a new field. So the tag vocabulary is where a board is fitted to its subject, and it is most of this document. ## Starting a board ``` worklane init # in the directory the board belongs to ``` Which directory decides which board. Commands walk up from the working directory to the nearest `.worklane`, so a board in `~/house` answers every `worklane` run from anywhere under `~/house` and nowhere else. `init` makes the four status directories, the campaigns directory and an empty `tags.md`. Run on a board that already exists it prints a line and changes nothing, which is what makes it safe to run when you are not sure. Then declare the vocabulary before the tickets pile up. Tags applied for months are far harder to change than tags agreed once, because changing one means rewriting every ticket carrying it. ## Designing a tag vocabulary A tag is a word a ticket carries so the board can be cut by it later. `worklane ls --tag kitchen` is the whole payoff, so the test of a good vocabulary is whether the cuts it allows are cuts anyone wants. ### Work in axes An axis is one question every ticket on this board can answer, with a small closed set of answers. Pick two or three axes and keep them apart. Nearly every vocabulary that goes bad is one where two axes were mixed into one pile of words. A software tool: | Axis | Answers | |---|---| | Kind | `feature`, `bug`, `chore`, `docs` | | Area | `cli`, `tui`, `api`, `build` | A product strategy: | Axis | Answers | |---|---| | Kind | `research`, `decision`, `experiment`, `writeup` | | Audience | `enterprise`, `self-serve`, `internal` | A household: | Axis | Answers | |---|---| | Kind | `repair`, `errand`, `admin`, `cleaning` | | Room | `kitchen`, `garden`, `garage`, `car` | Same shape, nothing in common. Derive the axes from the questions somebody will actually ask this board, not from a template: if nobody will ever ask "show me everything in the garage", `garage` is not earning its place. ### The rules - **A tag is for kind, not for state.** State is the status directory. A `doing` tag beside `committed`, a `blocked` tag beside a `blocked by` relation, a `done` tag at all: each is a second copy of something the board already knows, and the copy is the one that goes stale. - **A tag is not a goal.** Everything for one outcome is a campaign, which has a title, a description and a state derived from its members. `worklane campaign` owns that; `worklane-plan` decides what belongs in one. - **A tag is not a field.** No `p1` beside Priority, no `alice` beside Owner, no `august` beside Due. The field is the writer and the tag will disagree with it. - **A tag is not a person.** Owner is a field, and `chown` writes it. - **Two axes, not two words for one thing.** Before adding a word, say which axis it is on. If it does not fit one, either it is a new axis, which is a decision, or it is a private note, which is not a tag. - **Around a dozen tags, up to twenty.** Past that nobody remembers the vocabulary, so they invent a near-duplicate instead of reusing what is there. Fewer, broader tags beat a long tail nobody can recall. - **Singular or plural, pick one and keep to it.** `bug`/`bugs` and `chore`/`chores` are the commonest way a board ends up with two words for one idea. - **Case matters.** `Bug` and `bug` are two tags to `--tag`, to `tags` and to the colour a card is drawn in. Lowercase everything unless there is a reason. ### How many tags per ticket One per axis is the target: a ticket is one kind of thing in one area. A ticket that wants three areas is usually two tickets, and a ticket with no tag at all is invisible to every question asked by tag. ## Annotating a tag ``` worklane tags # every tag, its count and what it means worklane tags add kitchen --annotation "..." # declare one, and say what it means worklane tags set kitchen --annotation "..." # change what it means ``` `.worklane/tags.md` holds one section per declared tag, the tag as the heading and its annotation under it. It is what a person opens to find out what the board means by a word, and it is what an agent reads before choosing one. **Declaring a tag tags nothing, and tagging a ticket declares nothing.** The two lists are separate on purpose: the counts come from what the tickets carry, `tags.md` records what the board agreed on, and the difference between them is the thing worth looking at. A tag carried by tickets but never declared is a word somebody invented in a hurry. `worklane tags` reports both, as the tag, a tab, the count, and a tab and the annotation's opening line for a tag that is declared. So the two cases worth finding read off the listing: a tag at a count of zero is declared and nobody has reached for it, and a tag with no annotation column at all is carried and was never declared. ### What an annotation has to say The definition is the easy half and does the least work. What stops drift is the boundary against the neighbouring tag, so write that. Worthless, because nobody was ever unsure of this: ``` worklane tags add bug --annotation "Bugs." ``` Useful, because it answers the question somebody was actually about to get wrong: ``` worklane tags add bug \ --annotation "Behaviour that contradicts what the tool says it does, reproducible from a described state." \ --annotation "" \ --annotation "Not for something missing. A gap is a feature, however obvious the gap is." ``` The same for a household board: ``` worklane tags add repair \ --annotation "Something that worked and now does not." \ --annotation "" \ --annotation "Not for an improvement to something that works, which is a project, and not for a thing that needs replacing rather than fixing." ``` Repeat `--annotation` for more lines, and pass an empty one for a paragraph break. Three lines is plenty: a definition, then the boundary. Write an annotation for every tag, including the obvious ones. The obvious tags are the ones two people quietly disagree about. ### Traps - `tags add` refuses a tag that is already declared, and `tags set` refuses one that is not. Each names the other, so the refusal tells you which you wanted. - A tag cannot contain a comma, because a comma is what separates one tag from the next in the Tags field. Surrounding spaces are trimmed. - A tag you have declared and never applied lists at a count of zero. That is not a fault; it is the file and the board disagreeing, which is the state that tells you the vocabulary has not landed yet. - Nothing removes a declaration. There is no `tags rm`, so a tag declared in error stays in the file with whatever its annotation says. Say it is retired in the annotation. ## Changing the vocabulary later ### Renaming a tag There is no rename. The tag is the key, so it means rewriting the Tags field of every ticket carrying it, one at a time: ``` worklane ls --tag bugs --ids # every ticket carrying the old word worklane show 1b78a24 # read the whole Tags field of each worklane set 1b78a24 --tags bug,cli # restate all of them, with the new word worklane tags add bug --annotation "..." ``` **`--tags` replaces the whole field.** Restate every tag the ticket should keep or the ones you leave out are gone, with no undo. This is the most destructive command on the board. Read the ticket's current tags before writing, never from memory, and run `worklane tags` before and after: a count that moved where nothing was meant to change is a tag lost to that rule. Propose the whole list of edits and wait for approval before applying any of them, the way `worklane-plan` requires for a sweep. The reason is the same: nothing records what a field held before you wrote to it. ### Retiring a tag Take it off the tickets the same way, then leave the declaration saying it is retired and what replaced it. A tag with a count of zero and an annotation pointing elsewhere is a better answer than a word that simply vanishes, because the next person will otherwise reinvent it. ## Repairing a board Every repair here has been run against a real board. Work by symptom. **The rule that does not bend: do not edit a ticket file.** The filename, the `Status` field and the directory have to agree, and the commands are what keep them agreeing. The two exceptions below are files no command owns, and they are marked as such. ### A ticket has vanished from `ls` `worklane ls` leaves `done` out of its listing, though it still counts it at the top. So first check `worklane ls done`. If it is there and should not be, its file has been moved into the wrong directory by hand or by a restore. The repair is two moves, not one: ``` worklane mv 1b78a24 --status reviewing -f worklane mv 1b78a24 --status done -f ``` `mv` reads the current status from the *directory*, so moving it to the status the directory already says it is in is refused as a no-op and the field stays wrong. Moving it away and back rewrites the field. Check with `worklane show 1b78a24`, whose `Status` line is read from the file rather than from where it sits. ### A command says the id matches several tickets ``` Multiple tickets found matching 'bf2dc18': 1. (bf2dc18) Alpha [backlog] 2. (bf2dc18) Alpha [done] ``` The same file exists in two status directories, usually from a copy or a half-finished restore. The ticket is now unaddressable: every command resolves before it acts, so `show` and `mv` fail the same way and cannot be used to fix it. **File exception.** Read both with `cat`, keep the one whose `Status` field agrees with the directory it is in, and delete the other. If neither agrees, keep either and repair it as above. Then confirm with `worklane show`. ### A move is refused by a blocker ``` Cannot move 'Beta' while it is blocked by: ... Use --force (-f) to move it anyway. ``` Working as intended: a ticket cannot advance while something it waits on is unfinished. Finish the blocker, or use `-f` if the dependency is no longer real. Note that the relation stays on the ticket and will refuse the next move too, and there is no way to take a relation off, so `-f` is the answer every time until the blocker is done. If the message says `is blocked by X, which is not on the board`, the blocker has been deleted. That is a warning rather than a refusal and the move goes through. ### `show` renders `_missing_` A relation or a Campaign field naming something the board no longer holds. Harmless to read and impossible to clear, since `relate` only adds and `assign` only moves a ticket between campaigns that exist. For a campaign, `worklane assign ` overwrites it. For a relation, leave it. ### A status is missing from `worklane ls` The count list at the top of `ls` names every status directory it found, so a status that is absent from it has had its directory deleted. Nothing errors until something tries to move a ticket there, which then fails with a raw file error. **File exception.** `worklane init` will not repair it, since it refuses on a board that already exists. Recreate the directory: ``` mkdir .worklane/reviewing ``` ### A `.wl-*.tmp` file in `.worklane/` The staging file for a write that was killed part way. Every write stages here and renames into place, so a leftover means the write did not finish; nothing reads these and no listing shows them. **File exception.** Delete it. Then check the ticket it names with `worklane show` and redo whatever the interrupted command was. ### Nothing works and the error names `.worklane` Check where you are. Commands resolve the nearest `.worklane` at or above the working directory, so running from the wrong directory addresses another board or none. `worklane ls` from where you think the board is, is the fastest way to find out. ## What this skill does not touch - **Priorities, due dates, campaign membership and retagging sweeps.** That is `worklane-plan`. Deciding the vocabulary is here; applying it across the board is there. - **Filing a ticket, working one, moving it through the statuses.** That is the `worklane` skill. - **Judging whether a finished ticket is really done.** That is `worklane-review`. - **The content of a ticket.** A description or an acceptance criterion that is wrong is the author's, and the answer is a comment on that ticket.