kanmer-groom

# Grooming a Kanmer board Standup *flags* board problems; groom *fixes* them. But the board is the human's shared workspace, so grooming is propose-then-apply: one batch of findings, their sign-off, then the edits — never a silent reshuffle of someone else's backlog. ## 1. Scan `get_status` (warnings count), `list_board`, `list_items include_archived: true`, and `get_activity` for recent movement. Look for: - **Near-duplicates** — `search_items` on suspicious title pairs; two tickets describing one unit of work. - **Missing fields** — no `area` on a board that has areas; no `profile`, so the ticket silently inherits its area's default when a different one fits where the user uses them. - **Doc-gate debt** — tickets with `docs_todo: true` whose governing PRD/FRD/ADR was never linked, or missing a doc a later stage requires (`get_doc_gates` names the gap). These silently stall at the next gate; hand them to `kanmer-docs` to link/write the doc, or `link_doc` an existing one. Never a quick capture (`capture: true`): it owes no document by design, and a capture carrying `docs_todo` is itself the defect — clear the flag rather than chasing a doc for it. - **Undecided captures** — quick captures that have accumulated. They are not debt and never stale, but a pile of them is a decision nobody has made: list them with `list_items profile: "capture"` and offer the user the six dispositions (`duplicate`, `already-fixed`, `batch`, `promoted`, `retained`, `not-required`). Promotion is always the user's call, never groom's. - **Oversized tickets** — bodies describing several units of work, or checklists that sprawl past one deliverable. - **Dead tickets** — untouched for months, superseded, or describing code that no longer exists. - **Board-vs-reality sweep** — before calling an open ticket stale, list only non-archived Backlog or Preparing tickets, and drop quick captures from that list: an observation nobody has promoted has not stalled, it is waiting on a decision. For each candidate, search `main` history twice: the exact ticket id and a distinctive title phrase; when GitHub is available, search merged PRs too. A keyword/title hit is only a lead: open the matched commit, diff, or PR and record what portion of the ticket actually shipped. In the proposed batch, include the ticket id and stage, searches/sources, commit or PR evidence, shipped versus remaining scope, and one proposed disposition: no action, an Outcome note plus archive for wholly delivered work, or a concrete rescope for partial delivery. The sweep never archives or rescopes automatically — the user signs off before Apply changes the shared board. CORE-028 (PRs #57/#59) is the whole-delivery archive example; GUI-076 (`9ec7741`) is the partial-delivery rescope example. Both records are already repaired, so a current run excludes them rather than mutating the live board to recreate the defect. - **Stale takes** — `taken` with no activity since (>3 days), branch/ worktree pointing at work nobody is doing. - **Off-board statuses** and file warnings from `list_items` — data problems the tools can repair via `move_item` / `update_item`. A move crosses **at most one gated boundary**, so a ticket parked several stages from where it belongs is walked there one stage at a time; a single corrective jump is refused even when every document exists. That refusal is the rule working, not a broken ticket, and there is no way around it: `update_item status` runs the same gate check as `move_item`. ## 2. Propose One message: each finding, the proposed fix, grouped by kind. The user's repo, their priorities — especially for archiving and splitting. ## 3. Apply - **Duplicates**: keep the better ticket, merge anything unique from the other into it (body or docs), link them, archive the loser. Don't delete. - **Splits**: file the new tickets (`kanmer-tickets` conventions), move the relevant checklist items over, link with `rel: "blocks"` where order matters, shrink the original. - **Fields**: `update_item` with `expected_updated` — grooming touches many items, and a conflict means someone else is editing; re-read, don't clobber. - **Stale takes**: ask the owner (or the user) before releasing someone else's take; a release without a note strands the worktree — record the branch/worktree in the checklist progress notes first, per `kanmer-execute`'s pausing rules. - **Archive** with `archived: true`; `delete_item` only on the user's explicit ask. ## Converting grouping labels into groups A board that has been running a while grows labels doing a group's job — `v3-phase-4`, `epic-billing`, `q3` — one of the failures groups exist to fix (PRD-001 problem 2). A label can be filtered on and nothing else: no title, no shared context, no progress. **Only convert labels that name a body of work.** A label describing a *property* of a ticket — `bug`, `blocked`, `security`, `good-first-issue` — is a label doing a label's job. Leave it. The test is whether the label could sensibly have a goal and a completion percentage. 1. **Preview, and stop.** For each candidate: the label, the proposed group, the ticket count and how many are already done. This writes to every matched ticket and `update_item` stamps `updated`, so a wrong run lights up every card on the human's board at once. Do not skip the confirmation because the mapping looks obvious. 2. **Create the group** — `epic` for a body of work, `horizon` for a time-ordered lens — with a `context.md` naming the plan and governing documents that bind its members. That shared context is most of the value: it is written once and read by every member's agent. 3. **Set `groups` on each ticket.** Membership lives on the ticket (ADR-0001); never write a member list into the group. Members and progress are derived. 4. **Leave the labels in place.** Removing them in the same pass makes the run irreversible for no gain. Drop them later, once the groups are trusted. 5. **Re-read before each patch.** Build the patch from a fresh `get_item`, not from a list captured before the run started. A ticket that gained a group earlier in the same pass has a stale `groups` array in that list, and patching from it silently erases the membership you just wrote. 6. **Verify against the source.** Each group's derived `complete`/`total` must equal a direct count of tickets carrying the label. A mismatch means membership did not land — which is exactly how step 5's bug shows itself. Idempotent by construction: a ticket already naming the group is skipped, and a no-op `update_item` does not bump `updated`. A second run should report zero patches. For horizons, derive the split from something real — the roadmap's ordering, `blocks` edges, what is actually taken. An invented NOW/NEXT is worse than none, because a horizon filter that does not match reality teaches people to ignore it. ## 4. Report What changed, one line per item, plus what you deliberately left alone and why. Grooming that can't be audited is indistinguishable from damage. --- **No successor — control returns to the user.** Grooming changes the board, not the work: nothing here moves a ticket forward through its pipeline. Tickets this run made ready go to `kanmer-research` when someone starts them, doc-gate debt goes to `kanmer-docs`, and a board that needs describing rather than fixing was `kanmer-report`'s job in the first place.